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

ICU 76.1 76.1

Namespaces | Typedefs | Enumerations | Functions
uformattedvalue.h File Reference

C API: Abstract operations for localized strings. More...

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

Go to the source code of this file.

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

## Typedefs
typedef enum UFieldCategory | UFieldCategory
| All possible field categories in ICU.
typedef struct UConstrainedFieldPosition | UConstrainedFieldPosition
| Represents a span of a string containing a given field.
typedef struct UFormattedValue | UFormattedValue
| An abstract formatted value: a string with associated field attributes.

## Enumerations
enum | UFieldCategory { UFIELD_CATEGORY_UNDEFINED = 0 , UFIELD_CATEGORY_DATE , UFIELD_CATEGORY_NUMBER , UFIELD_CATEGORY_LIST , UFIELD_CATEGORY_RELATIVE_DATETIME , UFIELD_CATEGORY_DATE_INTERVAL , UFIELD_CATEGORY_COUNT , UFIELD_CATEGORY_LIST_SPAN = 0x1000 + UFIELD_CATEGORY_LIST , UFIELD_CATEGORY_DATE_INTERVAL_SPAN = 0x1000 + UFIELD_CATEGORY_DATE_INTERVAL , UFIELD_CATEGORY_NUMBER_RANGE_SPAN = 0x1000 + UFIELD_CATEGORY_NUMBER }
| All possible field categories in ICU. More...

## Functions
U_CAPI UConstrainedFieldPosition * | ucfpos_open (UErrorCode *ec)
| Creates a new UConstrainedFieldPosition.
U_CAPI void | ucfpos_reset (UConstrainedFieldPosition *ucfpos, UErrorCode *ec)
| Resets a UConstrainedFieldPosition to its initial state, as if it were newly created.
U_CAPI void | ucfpos_close (UConstrainedFieldPosition *ucfpos)
| Destroys a UConstrainedFieldPosition and releases its memory.
U_CAPI void | ucfpos_constrainCategory (UConstrainedFieldPosition *ucfpos, int32_t category, UErrorCode *ec)
| Sets a constraint on the field category.
U_CAPI void | ucfpos_constrainField (UConstrainedFieldPosition *ucfpos, int32_t category, int32_t field, UErrorCode *ec)
| Sets a constraint on the category and field.
U_CAPI int32_t | ucfpos_getCategory (const UConstrainedFieldPosition *ucfpos, UErrorCode *ec)
| Gets the field category for the current position.
U_CAPI int32_t | ucfpos_getField (const UConstrainedFieldPosition *ucfpos, UErrorCode *ec)
| Gets the field for the current position.
U_CAPI void | ucfpos_getIndexes (const UConstrainedFieldPosition *ucfpos, int32_t *pStart, int32_t *pLimit, UErrorCode *ec)
| Gets the INCLUSIVE start and EXCLUSIVE end index stored for the current position.
U_CAPI int64_t | ucfpos_getInt64IterationContext (const UConstrainedFieldPosition *ucfpos, UErrorCode *ec)
| Gets an int64 that FormattedValue implementations may use for storage.
U_CAPI void | ucfpos_setInt64IterationContext (UConstrainedFieldPosition *ucfpos, int64_t context, UErrorCode *ec)
| Sets an int64 that FormattedValue implementations may use for storage.
U_CAPI UBool | ucfpos_matchesField (const UConstrainedFieldPosition *ucfpos, int32_t category, int32_t field, UErrorCode *ec)
| Determines whether a given field should be included given the constraints.
U_CAPI void | ucfpos_setState (UConstrainedFieldPosition *ucfpos, int32_t category, int32_t field, int32_t start, int32_t limit, UErrorCode *ec)
| Sets new values for the primary public getters.
U_CAPI const UChar * | ufmtval_getString (const UFormattedValue *ufmtval, int32_t *pLength, UErrorCode *ec)
| Returns a pointer to the formatted string.
U_CAPI UBool | ufmtval_nextPosition (const UFormattedValue *ufmtval, UConstrainedFieldPosition *ucfpos, UErrorCode *ec)
| Iterates over field positions in the UFormattedValue.

## Detailed Description

C API: Abstract operations for localized strings.

This file contains declarations for classes that deal with formatted strings. A number of APIs throughout ICU use these classes for expressing their localized output.

Definition in file uformattedvalue.h.

## Typedef Documentation

## ◆ UConstrainedFieldPosition

typedef struct UConstrainedFieldPosition UConstrainedFieldPosition

Represents a span of a string containing a given field.

This struct differs from UFieldPosition 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.

Stable
  ICU 64

Definition at line 118 of file uformattedvalue.h.

## ◆ UFieldCategory

typedef enum UFieldCategory UFieldCategory

All possible field categories in ICU.

Every entry in this enum corresponds to another enum that exists in ICU.

In the APIs that take a UFieldCategory, an int32_t type is used. Field categories having any of the top four bits turned on are reserved as private-use for external APIs implementing FormattedValue. This means that categories 2^28 and higher or below zero (with the highest bit turned on) are private-use and will not be used by ICU in the future.

Stable
  ICU 64

## ◆ UFormattedValue

typedef struct UFormattedValue UFormattedValue

An abstract formatted value: a string with associated field attributes.

Many formatters format to types compatible with UFormattedValue.

Stable
  ICU 64

Definition at line 368 of file uformattedvalue.h.

## Enumeration Type Documentation

## ◆ UFieldCategory

enum UFieldCategory

All possible field categories in ICU.

Every entry in this enum corresponds to another enum that exists in ICU.

In the APIs that take a UFieldCategory, an int32_t type is used. Field categories having any of the top four bits turned on are reserved as private-use for external APIs implementing FormattedValue. This means that categories 2^28 and higher or below zero (with the highest bit turned on) are private-use and will not be used by ICU in the future.

Stable
  ICU 64

Enumerator
UFIELD_CATEGORY_UNDEFINED | For an undefined field category. Stable ICU 64
UFIELD_CATEGORY_DATE | For fields in UDateFormatField (udat.h), from ICU 3.0. Stable ICU 64
UFIELD_CATEGORY_NUMBER | For fields in UNumberFormatFields (unum.h), from ICU 49. Stable ICU 64
UFIELD_CATEGORY_LIST | For fields in UListFormatterField (ulistformatter.h), from ICU 63. Stable ICU 64
UFIELD_CATEGORY_RELATIVE_DATETIME | For fields in URelativeDateTimeFormatterField (ureldatefmt.h), from ICU 64. Stable ICU 64
UFIELD_CATEGORY_DATE_INTERVAL | Reserved for possible future fields in UDateIntervalFormatField. Internal Do not use. This API is for internal use only.
UFIELD_CATEGORY_COUNT | Internal Do not use. This API is for internal use only.
UFIELD_CATEGORY_LIST_SPAN | Category for spans in a list. Stable ICU 64
UFIELD_CATEGORY_DATE_INTERVAL_SPAN | Category for spans in a date interval. Stable ICU 64
UFIELD_CATEGORY_NUMBER_RANGE_SPAN | Category for spans in a number range. Stable ICU 69

Definition at line 34 of file uformattedvalue.h.

## Function Documentation

## ◆ ucfpos_close()

U_CAPI void ucfpos_close | ( | UConstrainedFieldPosition * | ucfpos | ) |

Destroys a UConstrainedFieldPosition and releases its memory.

Parameters

  ucfpos | The instance of UConstrainedFieldPosition.

Stable
  ICU 64

## ◆ ucfpos_constrainCategory()

U_CAPI void ucfpos_constrainCategory | ( | UConstrainedFieldPosition * | ucfpos,
|  | int32_t | category,
|  | UErrorCode * | ec )

Sets a constraint on the field category.

When this instance of UConstrainedFieldPosition is passed to ufmtval_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:

    UConstrainedFieldPosition* ucfpos = ucfpos_open(ec);
    ucfpos_constrainCategory(ucfpos, UFIELDCATEGORY_NUMBER_FORMAT, ec);
    while (ufmtval_nextPosition(ufmtval, ucfpos, ec)) {
        // handle the number-related field position
    }
    ucfpos_close(ucfpos);

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

Parameters

  ucfpos | The instance of UConstrainedFieldPosition.
  category | The field category to fix when iterating.
  ec | Set if an error occurs.

Stable
  ICU 64

## ◆ ucfpos_constrainField()

U_CAPI void ucfpos_constrainField | ( | UConstrainedFieldPosition * | ucfpos,
|  | int32_t | category,
|  | int32_t | field,
|  | UErrorCode * | ec )

Sets a constraint on the category and field.

When this instance of UConstrainedFieldPosition is passed to ufmtval_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:

    UConstrainedFieldPosition* ucfpos = ucfpos_open(ec);
    ucfpos_constrainField(ucfpos, UFIELDCATEGORY_NUMBER_FORMAT, UNUM_GROUPING_SEPARATOR_FIELD, ec);
    while (ufmtval_nextPosition(ufmtval, ucfpos, ec)) {
        // handle the grouping separator position
    }
    ucfpos_close(ucfpos);

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

Parameters

  ucfpos | The instance of UConstrainedFieldPosition.
  category | The field category to fix when iterating.
  field | The field to fix when iterating.
  ec | Set if an error occurs.

Stable
  ICU 64

## ◆ ucfpos_getCategory()

U_CAPI int32_t ucfpos_getCategory | ( | const UConstrainedFieldPosition * | ucfpos,
|  | UErrorCode * | ec )

Gets the field category for the current position.

If a category or field constraint was set, this function returns the constrained category. Otherwise, the return value is well-defined only after ufmtval_nextPosition returns true.

Parameters

  ucfpos | The instance of UConstrainedFieldPosition.
  ec | Set if an error occurs.

Returns
  The field category saved in the instance.

Stable
  ICU 64

## ◆ ucfpos_getField()

U_CAPI int32_t ucfpos_getField | ( | const UConstrainedFieldPosition * | ucfpos,
|  | UErrorCode * | ec )

Gets the field for the current position.

If a field constraint was set, this function returns the constrained field. Otherwise, the return value is well-defined only after ufmtval_nextPosition returns true.

Parameters

  ucfpos | The instance of UConstrainedFieldPosition.
  ec | Set if an error occurs.

Returns
  The field saved in the instance.

Stable
  ICU 64

## ◆ ucfpos_getIndexes()

U_CAPI void ucfpos_getIndexes | ( | const UConstrainedFieldPosition * | ucfpos,
|  | int32_t * | pStart,
|  | int32_t * | pLimit,
|  | UErrorCode * | ec )

Gets the INCLUSIVE start and EXCLUSIVE end index stored for the current position.

The output values are well-defined only after ufmtval_nextPosition returns true.

Parameters

  ucfpos | The instance of UConstrainedFieldPosition.
  pStart | Set to the start index saved in the instance. Ignored if nullptr.
  pLimit | Set to the end index saved in the instance. Ignored if nullptr.
  ec | Set if an error occurs.

Stable
  ICU 64

## ◆ ucfpos_getInt64IterationContext()

U_CAPI int64_t ucfpos_getInt64IterationContext | ( | const UConstrainedFieldPosition * | ucfpos,
|  | UErrorCode * | ec )

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.

Parameters

  ucfpos | The instance of UConstrainedFieldPosition.
  ec | Set if an error occurs.

Returns
  The current iteration context from ucfpos_setInt64IterationContext.

Stable
  ICU 64

## ◆ ucfpos_matchesField()

U_CAPI UBool ucfpos_matchesField | ( | const UConstrainedFieldPosition * | ucfpos,
|  | int32_t | category,
|  | int32_t | field,
|  | UErrorCode * | ec )

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

Intended to be used by FormattedValue implementations.

Parameters

  ucfpos | The instance of UConstrainedFieldPosition.
  category | The category to test.
  field | The field to test.
  ec | Set if an error occurs.

Stable
  ICU 64

## ◆ ucfpos_open()

U_CAPI UConstrainedFieldPosition * ucfpos_open | ( | UErrorCode * | ec | ) |

Creates a new UConstrainedFieldPosition.

By default, the UConstrainedFieldPosition has no iteration constraints.

Parameters

  ec | Set if an error occurs.

Returns
  The new object, or NULL if an error occurs.

Stable
  ICU 64

## ◆ ucfpos_reset()

U_CAPI void ucfpos_reset | ( | UConstrainedFieldPosition * | ucfpos,
|  | UErrorCode * | ec )

Resets a UConstrainedFieldPosition to its initial state, as if it were newly created.

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

Parameters

  ucfpos | The instance of UConstrainedFieldPosition.
  ec | Set if an error occurs.

Stable
  ICU 64

## ◆ ucfpos_setInt64IterationContext()

U_CAPI void ucfpos_setInt64IterationContext | ( | UConstrainedFieldPosition * | ucfpos,
|  | int64_t | context,
|  | UErrorCode * | ec )

Sets an int64 that FormattedValue implementations may use for storage.

Intended to be used by FormattedValue implementations.

Parameters

  ucfpos | The instance of UConstrainedFieldPosition.
  context | The new iteration context.
  ec | Set if an error occurs.

Stable
  ICU 64

## ◆ ucfpos_setState()

U_CAPI void ucfpos_setState | ( | UConstrainedFieldPosition * | ucfpos,
|  | int32_t | category,
|  | int32_t | field,
|  | int32_t | start,
|  | int32_t | limit,
|  | UErrorCode * | ec )

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

  ucfpos | The instance of UConstrainedFieldPosition.
  category | The new field category.
  field | The new field.
  start | The new inclusive start index.
  limit | The new exclusive end index.
  ec | Set if an error occurs.

Stable
  ICU 64

## ◆ ufmtval_getString()

U_CAPI const UChar * ufmtval_getString | ( | const UFormattedValue * | ufmtval,
|  | int32_t * | pLength,
|  | UErrorCode * | ec )

Returns a pointer to the formatted string.

The pointer is owned by the UFormattedValue. The return value is valid only as long as the UFormattedValue is present and unchanged in memory.

The return value is NUL-terminated but could contain internal NULs.

Parameters

  ufmtval | The object containing the formatted string and attributes.
  pLength | Output variable for the length of the string. Ignored if NULL.
  ec | Set if an error occurs.

Returns
  A NUL-terminated char16 string owned by the UFormattedValue.

Stable
  ICU 64

## ◆ ufmtval_nextPosition()

U_CAPI UBool ufmtval_nextPosition | ( | const UFormattedValue * | ufmtval,
|  | UConstrainedFieldPosition * | ucfpos,
|  | UErrorCode * | ec )

Iterates over field positions in the UFormattedValue.

This lets you determine the position of specific types of substrings, like a month or a decimal separator.

To loop over all field positions:

    UConstrainedFieldPosition* ucfpos = ucfpos_open(ec);
    while (ufmtval_nextPosition(ufmtval, ucfpos, ec)) {
        // handle the field position; get information from ucfpos
    }
    ucfpos_close(ucfpos);

Parameters

  ufmtval | The object containing the formatted string and attributes.
  ucfpos | The object used for iteration state; can provide constraints to iterate over only one specific category or field; see ucfpos_constrainCategory and ucfpos_constrainField.
  ec | Set if an error occurs.

Returns
  true if another position was found; false otherwise.

Stable
  ICU 64