ICU 76.1: icu::FieldPosition Class Reference

ICU 76.1 76.1

Public Types | Public Member Functions | Static Public Member Functions
icu::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 icu::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.
bool | operator== (const FieldPosition &that) const
| Equality operator.
bool | operator!= (const FieldPosition &that) const
| Equality operator.
FieldPosition * | clone () const
| Clone this object.
int32_t | getField () const
| Retrieve the field identifier.
int32_t | getBeginIndex () const
| Retrieve the index of the first character in the requested field.
int32_t | getEndIndex () 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 override
| ICU "poor man's RTTI", returns a UClassID for the actual class.
Public Member Functions inherited from icu::UObject
virtual | ~UObject ()
| Destructor.

## 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 intended for public 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;
    icu::DecimalFormatIMPORTANT: New users are strongly encouraged to see if numberformatter.h fits their use case.Definition decimfmt.h:666
    icu::DecimalFormat::setDecimalSeparatorAlwaysShownvirtual void setDecimalSeparatorAlwaysShown(UBool newValue)Allows you to set the behavior of the decimal separator with integers.
    icu::DecimalFormat::formatUnicodeString & format(double number, UnicodeString &appendTo, FieldPosition &pos) const overrideFormat a double or long number using base-10 representation.
    icu::FieldPositionFieldPosition is a simple class used by Format and its subclasses to identify fields in formatted out...Definition fieldpos.h:110
    icu::NumberFormat::INTEGER_FIELD@ INTEGER_FIELDThese constants are provided for backwards compatibility only.Definition numfmt.h:267
    icu::NumberFormat::createInstancestatic NumberFormat * createInstance(UErrorCode &)Create a default style NumberFormat for the current default locale.
    icu::UnicodeStringUnicodeString is a string class that stores Unicode characters directly and provides similar function...Definition unistr.h:296
    UErrorCodeUErrorCodeStandard ICU4C error code type, a substitute for exceptions.Definition utypes.h:430
    U_ZERO_ERROR@ U_ZERO_ERRORNo error, no warning.Definition utypes.h:465

<p<blockquote>‍ 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 110 of file fieldpos.h.

## Member Enumeration Documentation

## ◆ anonymous enum

anonymous enum

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

Stable
  ICU 2.0

Definition at line 117 of file fieldpos.h.

## Constructor & Destructor Documentation

## ◆ FieldPosition() [1/3]

icu::FieldPosition::FieldPosition | ( |  | ) |
| inline

Creates a FieldPosition object with a non-specified field.

Stable
  ICU 2.0

Definition at line 123 of file fieldpos.h.

## ◆ FieldPosition() [2/3]

icu::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 137 of file fieldpos.h.

## ◆ FieldPosition() [3/3]

icu::FieldPosition::FieldPosition | ( | const FieldPosition & | copy | ) |
| inline

Copy constructor.

Parameters

  copy | the object to be copied from.

Stable
  ICU 2.0

Definition at line 145 of file fieldpos.h.

## ◆ ~FieldPosition()

virtual icu::FieldPosition::~FieldPosition | ( |  | ) |
| virtual

Destructor.

Stable
  ICU 2.0

## Member Function Documentation

## ◆ clone()

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

Clone this object.

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

Returns
  a clone of this object

See also
  getDynamicClassID

Stable
  ICU 2.8

## ◆ getBeginIndex()

int32_t icu::FieldPosition::getBeginIndex | ( |  | ) | 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 202 of file fieldpos.h.

## ◆ getDynamicClassID()

virtual UClassID icu::FieldPosition::getDynamicClassID | ( |  | ) | const
| overridevirtual

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

Stable
  ICU 2.2

Reimplemented from icu::UObject.

## ◆ getEndIndex()

int32_t icu::FieldPosition::getEndIndex | ( |  | ) | 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 211 of file fieldpos.h.

## ◆ getField()

int32_t icu::FieldPosition::getField | ( |  | ) | const
| inline

Retrieve the field identifier.

Returns
  the field identifier.

Stable
  ICU 2.0

Definition at line 195 of file fieldpos.h.

## ◆ getStaticClassID()

static UClassID icu::FieldPosition::getStaticClassID | ( |  | ) |
| static

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

Stable
  ICU 2.2

## ◆ operator!=()

bool icu::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 286 of file fieldpos.h.

References icu::operator==().

## ◆ operator=()

FieldPosition & icu::FieldPosition::operator= | ( | const FieldPosition & | copy | ) |
| inline

Assignment operator.

Parameters

  copy | the object to be copied from.

Stable
  ICU 2.0

Definition at line 269 of file fieldpos.h.

## ◆ operator==()

bool icu::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 278 of file fieldpos.h.

## ◆ setBeginIndex()

void icu::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 225 of file fieldpos.h.

## ◆ setEndIndex()

void icu::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 232 of file fieldpos.h.

## ◆ setField()

void icu::FieldPosition::setField | ( | int32_t | f | ) |
| inline

Set the field.

Parameters

  f | the new value of the field.

Stable
  ICU 2.0

Definition at line 218 of file fieldpos.h.

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

- i18n/unicode/fieldpos.h