ICU 76.1: icu::ConstrainedFieldPosition Class Reference

ICU 76.1 76.1

Public Member Functions
icu::ConstrainedFieldPosition Class Reference

Represents a span of a string containing a given field. More...

`#include <formattedvalue.h>`

Inheritance diagram for icu::ConstrainedFieldPosition:

## Public Member Functions
| ConstrainedFieldPosition ()
| Initializes a ConstrainedFieldPosition.
| ~ConstrainedFieldPosition ()
void | reset ()
| Resets this ConstrainedFieldPosition to its initial state, as if it were newly created:
void | constrainCategory (int32_t category)
| Sets a constraint on the field category.
void | constrainField (int32_t category, int32_t field)
| Sets a constraint on the category and field.
int32_t | getCategory () const
| Gets the field category for the current position.
int32_t | getField () const
| Gets the field for the current position.
int32_t | getStart () const
| Gets the INCLUSIVE start index for the current position.
int32_t | getLimit () const
| Gets the EXCLUSIVE end index stored for the current position.
int64_t | getInt64IterationContext () const
| Gets an int64 that FormattedValue implementations may use for storage.
void | setInt64IterationContext (int64_t context)
| Sets an int64 that FormattedValue implementations may use for storage.
UBool | matchesField (int32_t category, int32_t field) const
| Determines whether a given field should be included given the constraints.
void | setState (int32_t category, int32_t field, int32_t start, int32_t limit)
| Sets new values for the primary public getters.

## Detailed Description

Represents a span of a string containing a given field.

This class differs from FieldPosition in the following ways:

1. It has information on the field category.
2. It allows you to set constraints to use when iterating over field positions.
3. It is used for the newer FormattedValue APIs.

This class is not intended for public subclassing.

Stable
  ICU 64

Definition at line 41 of file formattedvalue.h.

## Constructor & Destructor Documentation

## ◆ ConstrainedFieldPosition()

icu::ConstrainedFieldPosition::ConstrainedFieldPosition | ( |  | ) |

Initializes a ConstrainedFieldPosition.

By default, the ConstrainedFieldPosition has no iteration constraints.

Stable
  ICU 64

## ◆ ~ConstrainedFieldPosition()

icu::ConstrainedFieldPosition::~ConstrainedFieldPosition | ( |  | ) |

Stable
  ICU 64

## Member Function Documentation

## ◆ constrainCategory()

void icu::ConstrainedFieldPosition::constrainCategory | ( | int32_t | category | ) |

Sets a constraint on the field category.

When this instance of ConstrainedFieldPosition is passed to FormattedValue::nextPosition, positions are skipped unless they have the given category.

Any previously set constraints are cleared.

For example, to loop over only the number-related fields:

    ConstrainedFieldPosition cfpos;
    cfpos.constrainCategory(UFIELDCATEGORY_NUMBER_FORMAT);
    while (fmtval.nextPosition(cfpos, status)) {
        // handle the number-related field position
    }

Changing the constraint while in the middle of iterating over a FormattedValue does not generally have well-defined behavior.

Parameters

  category | The field category to fix when iterating.

Stable
  ICU 64

## ◆ constrainField()

void icu::ConstrainedFieldPosition::constrainField | ( | int32_t | category,
|  | int32_t | field )

Sets a constraint on the category and field.

When this instance of ConstrainedFieldPosition is passed to FormattedValue::nextPosition, positions are skipped unless they have the given category and field.

Any previously set constraints are cleared.

For example, to loop over all grouping separators:

    ConstrainedFieldPosition cfpos;
    cfpos.constrainField(UFIELDCATEGORY_NUMBER_FORMAT, UNUM_GROUPING_SEPARATOR_FIELD);
    while (fmtval.nextPosition(cfpos, status)) {
        // handle the grouping separator position
    }

Changing the constraint while in the middle of iterating over a FormattedValue does not generally have well-defined behavior.

Parameters

  category | The field category to fix when iterating.
  field | The field to fix when iterating.

Stable
  ICU 64

## ◆ getCategory()

int32_t icu::ConstrainedFieldPosition::getCategory | ( |  | ) | const
| inline

Gets the field category for the current position.

The return value is well-defined only after FormattedValue::nextPosition returns true.

Returns
  The field category saved in the instance.

Stable
  ICU 64

Definition at line 124 of file formattedvalue.h.

## ◆ getField()

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

Gets the field for the current position.

The return value is well-defined only after FormattedValue::nextPosition returns true.

Returns
  The field saved in the instance.

Stable
  ICU 64

Definition at line 137 of file formattedvalue.h.

## ◆ getInt64IterationContext()

int64_t icu::ConstrainedFieldPosition::getInt64IterationContext | ( |  | ) | const
| inline

Gets an int64 that FormattedValue implementations may use for storage.

The initial value is zero.

Users of FormattedValue should not need to call this method.

Returns
  The current iteration context from `setInt64IterationContext`.

Stable
  ICU 64

Definition at line 180 of file formattedvalue.h.

## ◆ getLimit()

int32_t icu::ConstrainedFieldPosition::getLimit | ( |  | ) | const
| inline

Gets the EXCLUSIVE end index stored for the current position.

The return value is well-defined only after FormattedValue::nextPosition returns true.

Returns
  The end index saved in the instance.

Stable
  ICU 64

Definition at line 161 of file formattedvalue.h.

## ◆ getStart()

int32_t icu::ConstrainedFieldPosition::getStart | ( |  | ) | const
| inline

Gets the INCLUSIVE start index for the current position.

The return value is well-defined only after FormattedValue::nextPosition returns true.

Returns
  The start index saved in the instance.

Stable
  ICU 64

Definition at line 149 of file formattedvalue.h.

## ◆ matchesField()

UBool icu::ConstrainedFieldPosition::matchesField | ( | int32_t | category,
|  | int32_t | field ) const

Determines whether a given field should be included given the constraints.

Intended to be used by FormattedValue implementations.

Parameters

  category | The category to test.
  field | The field to test.

Stable
  ICU 64

## ◆ reset()

void icu::ConstrainedFieldPosition::reset | ( |  | ) |

Resets this ConstrainedFieldPosition to its initial state, as if it were newly created:

- Removes any constraints that may have been set on the instance.

- Resets the iteration position.

  Stable
    ICU 64

## ◆ setInt64IterationContext()

void icu::ConstrainedFieldPosition::setInt64IterationContext | ( | int64_t | context | ) |

Sets an int64 that FormattedValue implementations may use for storage.

Intended to be used by FormattedValue implementations.

Parameters

  context | The new iteration context.

Stable
  ICU 64

## ◆ setState()

void icu::ConstrainedFieldPosition::setState | ( | int32_t | category,
|  | int32_t | field,
|  | int32_t | start,
|  | int32_t | limit )

Sets new values for the primary public getters.

Intended to be used by FormattedValue implementations.

It is up to the implementation to ensure that the user-requested constraints are satisfied. This method does not check!

Parameters

  category | The new field category.
  field | The new field.
  start | The new inclusive start index.
  limit | The new exclusive end index.

Stable
  ICU 64

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

- i18n/unicode/formattedvalue.h