ICU 76.1: i18n/unicode/ufieldpositer.h File Reference

ICU 76.1 76.1

Namespaces | Typedefs | Functions
ufieldpositer.h File Reference

C API: UFieldPositionIterator for use with format APIs. More...

`#include "unicode/utypes.h"`
`#include "unicode/localpointer.h"`

Go to the source code of this file.

## Namespaces
namespace | icu
| File coll.h.

## Typedefs
typedef struct UFieldPositionIterator | UFieldPositionIterator
| C typedef for struct UFieldPositionIterator.

## Functions
U_CAPI UFieldPositionIterator * | ufieldpositer_open (UErrorCode *status)
| Open a new, unset UFieldPositionIterator object.
U_CAPI void | ufieldpositer_close (UFieldPositionIterator *fpositer)
| Close a UFieldPositionIterator object.
U_CAPI int32_t | ufieldpositer_next (UFieldPositionIterator *fpositer, int32_t *beginIndex, int32_t *endIndex)
| Get information for the next field in the formatted string to which this UFieldPositionIterator currently applies, or return a negative value if there are no more fields.

## Detailed Description

C API: UFieldPositionIterator for use with format APIs.

Usage: ufieldpositer_open creates an empty (unset) UFieldPositionIterator. This can be passed to format functions such as `udat_formatForFields`, which will set it to apply to the fields in a particular formatted string. ufieldpositer_next can then be used to iterate over those fields, providing for each field its type (using values that are specific to the particular format type, such as date or number formats), as well as the start and end positions of the field in the formatted string. A given UFieldPositionIterator can be re-used for different format calls; each such call resets it to apply to that format string. ufieldpositer_close should be called to dispose of the UFieldPositionIterator when it is no longer needed.

See also
  FieldPositionIterator

Definition in file ufieldpositer.h.

## Typedef Documentation

## ◆ UFieldPositionIterator

typedef struct UFieldPositionIterator UFieldPositionIterator

C typedef for struct UFieldPositionIterator.

Stable
  ICU 55

Definition at line 46 of file ufieldpositer.h.

## Function Documentation

## ◆ ufieldpositer_close()

U_CAPI void ufieldpositer_close | ( | UFieldPositionIterator * | fpositer | ) |

Close a UFieldPositionIterator object.

Once closed it may no longer be used.

Parameters

  fpositer | A pointer to the UFieldPositionIterator object to close.

Stable
  ICU 55

## ◆ ufieldpositer_next()

U_CAPI int32_t ufieldpositer_next | ( | UFieldPositionIterator * | fpositer,
|  | int32_t * | beginIndex,
|  | int32_t * | endIndex )

Get information for the next field in the formatted string to which this UFieldPositionIterator currently applies, or return a negative value if there are no more fields.

Parameters

  fpositer | A pointer to the UFieldPositionIterator object containing iteration state for the format fields.
  beginIndex | A pointer to an int32_t to receive information about the start offset of the field in the formatted string (undefined if the function returns a negative value). May be NULL if this information is not needed.
  endIndex | A pointer to an int32_t to receive information about the end offset of the field in the formatted string (undefined if the function returns a negative value). May be NULL if this information is not needed.

Returns
  The field type (non-negative value), or a negative value if there are no more fields for which to provide information. If negative, then any values pointed to by beginIndex and endIndex are undefined.

The values for field type depend on what type of formatter the UFieldPositionIterator has been set by; for a date formatter, the values from the UDateFormatField enum. For more information, see the descriptions of format functions that take a UFieldPositionIterator* parameter, such as `udat_formatForFields`.

Stable
  ICU 55

## ◆ ufieldpositer_open()

U_CAPI UFieldPositionIterator * ufieldpositer_open | ( | UErrorCode * | status | ) |

Open a new, unset UFieldPositionIterator object.

Parameters

  status | A pointer to a UErrorCode to receive any errors.

Returns
  A pointer to an empty (unset) UFieldPositionIterator object, or NULL if an error occurred.

Stable
  ICU 55