# FieldPosition Class Reference

`FieldPosition` is a simple class used by `Format` and its subclasses to identify fields in formatted output. More...

`#include <fieldpos.h>`

Inheritance diagram for FieldPosition:

## Public Types
enum | { DONT_CARE = -1 }
| DONT_CARE may be specified as the field to indicate that the caller doesn't need to specify a field. More...
## Public Member Functions
| FieldPosition ()
| Creates a FieldPosition object with a non-specified field.
| FieldPosition (int32_t field)
| Creates a FieldPosition object for the given field.
| FieldPosition (const FieldPosition &copy)
| Copy constructor.
virtual | ~FieldPosition ()
| Destructor.
FieldPosition & | operator= (const FieldPosition &copy)
| Assignment operator.
UBool | operator== (const FieldPosition &that) const
| Equality operator.
UBool | operator!= (const FieldPosition &that) const
| Equality operator.
FieldPosition * | clone () const
| Clone this object.
int32_t | getField (void) const
| Retrieve the field identifier.
int32_t | getBeginIndex (void) const
| Retrieve the index of the first character in the requested field.
int32_t | getEndIndex (void) const
| Retrieve the index of the character following the last character in the requested field.
void | setField (int32_t f)
| Set the field.
void | setBeginIndex (int32_t bi)
| Set the begin index.
void | setEndIndex (int32_t ei)
| Set the end index.
virtual UClassID | getDynamicClassID () const
| ICU "poor man's RTTI", returns a UClassID for the actual class.
## Static Public Member Functions
static UClassID | getStaticClassID ()
| ICU "poor man's RTTI", returns a UClassID for this class.

## Detailed Description

`FieldPosition` is a simple class used by `Format` and its subclasses to identify fields in formatted output.

Fields are identified by constants, whose names typically end with `_FIELD`, defined in the various subclasses of `Format`. See `ERA_FIELD` and its friends in `DateFormat` for an example.

`FieldPosition` keeps track of the position of the field within the formatted output with two indices: the index of the first character of the field and the index of the last character of the field.

One version of the `format` method in the various `Format` classes requires a `FieldPosition` object as an argument. You use this `format` method to perform partial formatting or to get information about the formatted output (such as the position of a field).

The FieldPosition class is not suitable for subclassing.

Below is an example of using `FieldPosition` to aid alignment of an array of formatted floating-point numbers on their decimal points:

            double doubleNum[] = {123456789.0, -12345678.9, 1234567.89, -123456.789,
                      12345.6789, -1234.56789, 123.456789, -12.3456789, 1.23456789};
           int dNumSize = (int)(sizeof(doubleNum)/sizeof(double));

           UErrorCode status = U_ZERO_ERROR;
           DecimalFormat* fmt = (DecimalFormat*) NumberFormat::createInstance(status);
           fmt->setDecimalSeparatorAlwaysShown(true);

           const int tempLen = 20;
           char temp[tempLen];

           for (int i=0; i<dNumSize; i++) {
               FieldPosition pos(NumberFormat::INTEGER_FIELD);
               UnicodeString buf;
               char fmtText[tempLen];
               ToCharString(fmt->format(doubleNum[i], buf, pos), fmtText);
               for (int j=0; j<tempLen; j++) temp[j] = ' '; // clear with spaces
               temp[__min(tempLen, tempLen-pos.getEndIndex())] = '\0';
               cout << temp << fmtText   << endl;
           }
           delete fmt;

The code will generate the following output:

                123,456,789.000
               -12,345,678.900
                 1,234,567.880
                  -123,456.789
                    12,345.678
                    -1,234.567
                       123.456
                       -12.345
                         1.234

Definition at line 106 of file fieldpos.h.

## Member Enumeration Documentation

anonymous enum

DONT_CARE may be specified as the field to indicate that the caller doesn't need to specify a field.

Do not subclass.

Definition at line 112 of file fieldpos.h.

## Constructor & Destructor Documentation

FieldPosition::FieldPosition | ( |  | ) | `[inline]`

Creates a FieldPosition object with a non-specified field.

Stable:
  ICU 2.0

Definition at line 118 of file fieldpos.h.

FieldPosition::FieldPosition | ( | int32_t | field | ) | `[inline]`

Creates a FieldPosition object for the given field.

Fields are identified by constants, whose names typically end with _FIELD, in the various subclasses of Format.

See also:
  NumberFormat::INTEGER_FIELD

  NumberFormat::FRACTION_FIELD

  DateFormat::YEAR_FIELD

  DateFormat::MONTH_FIELD

Stable:
  ICU 2.0

Definition at line 132 of file fieldpos.h.

FieldPosition::FieldPosition | ( | const FieldPosition & | copy | ) | `[inline]`

Copy constructor.

Parameters:

  | copy | the object to be copied from.

Stable:
  ICU 2.0

Definition at line 140 of file fieldpos.h.

virtual FieldPosition::~FieldPosition | ( |  | ) | `[virtual]`

Destructor.

Stable:
  ICU 2.0

## Member Function Documentation

FieldPosition* FieldPosition::clone | ( |  | ) | const

Clone this object.

Clones can be used concurrently in multiple threads. If an error occurs, then NULL is returned. The caller must delete the clone.

Returns:
  a clone of this object

See also:
  getDynamicClassID

Stable:
  ICU 2.8

int32_t FieldPosition::getBeginIndex | ( | void |  | ) | const`[inline]`

Retrieve the index of the first character in the requested field.

Returns:
  the index of the first character in the requested field.

Stable:
  ICU 2.0

Definition at line 197 of file fieldpos.h.

virtual UClassID FieldPosition::getDynamicClassID | ( |  | ) | const`[virtual]`

ICU "poor man's RTTI", returns a UClassID for the actual class.

Stable:
  ICU 2.2

Implements UObject.

int32_t FieldPosition::getEndIndex | ( | void |  | ) | const`[inline]`

Retrieve the index of the character following the last character in the requested field.

Returns:
  the index of the character following the last character in the requested field.

Stable:
  ICU 2.0

Definition at line 206 of file fieldpos.h.

int32_t FieldPosition::getField | ( | void |  | ) | const`[inline]`

Retrieve the field identifier.

Returns:
  the field identifier.

Stable:
  ICU 2.0

Definition at line 190 of file fieldpos.h.

static UClassID FieldPosition::getStaticClassID | ( |  | ) | `[static]`

ICU "poor man's RTTI", returns a UClassID for this class.

Stable:
  ICU 2.2

UBool FieldPosition::operator!= | ( | const FieldPosition & | that | ) | const`[inline]`

Equality operator.

Parameters:

  | that | the object to be compared with.

Returns:
  TRUE if the two field positions are not equal, FALSE otherwise.

Stable:
  ICU 2.0

Definition at line 281 of file fieldpos.h.

References operator==().

FieldPosition & FieldPosition::operator= | ( | const FieldPosition & | copy | ) | `[inline]`

Assignment operator.

Parameters:

  | copy | the object to be copied from.

Stable:
  ICU 2.0

Definition at line 264 of file fieldpos.h.

References fBeginIndex, fEndIndex, and fField.

UBool FieldPosition::operator== | ( | const FieldPosition & | that | ) | const`[inline]`

Equality operator.

Parameters:

  | that | the object to be compared with.

Returns:
  TRUE if the two field positions are equal, FALSE otherwise.

Stable:
  ICU 2.0

Definition at line 273 of file fieldpos.h.

References fBeginIndex, fEndIndex, and fField.

Referenced by operator!=().

void FieldPosition::setBeginIndex | ( | int32_t | bi | ) | `[inline]`

Set the begin index.

For use by subclasses of Format.

Parameters:

  | bi | the new value of the begin index

Stable:
  ICU 2.0

Definition at line 220 of file fieldpos.h.

void FieldPosition::setEndIndex | ( | int32_t | ei | ) | `[inline]`

Set the end index.

For use by subclasses of Format.

Parameters:

  | ei | the new value of the end index

Stable:
  ICU 2.0

Definition at line 227 of file fieldpos.h.

void FieldPosition::setField | ( | int32_t | f | ) | `[inline]`

Set the field.

Parameters:

  | f | the new value of the field.

Stable:
  ICU 2.0

Definition at line 213 of file fieldpos.h.

The documentation for this class was generated from the following file:

- fieldpos.h