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

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

Namespaces
	icu
	File coll.h.

Typedefs
typedef enum UFieldCategory	UFieldCategory
	All possible field categories in ICU. More...

typedef struct UConstrainedFieldPosition	UConstrainedFieldPosition
	Represents a span of a string containing a given field. More...

typedef struct UFormattedValue	UFormattedValue
	An abstract formatted value: a string with associated field attributes. More...

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 }
	All possible field categories in ICU. More...

Functions
UConstrainedFieldPosition *	ucfpos_open (UErrorCode *ec)
	Creates a new UConstrainedFieldPosition. More...

void	ucfpos_reset (UConstrainedFieldPosition ucfpos, UErrorCode ec)
	Resets a UConstrainedFieldPosition to its initial state, as if it were newly created. More...

void	ucfpos_close (UConstrainedFieldPosition *ucfpos)
	Destroys a UConstrainedFieldPosition and releases its memory. More...

void	ucfpos_constrainCategory (UConstrainedFieldPosition ucfpos, int32_t category, UErrorCode ec)
	Sets a constraint on the field category. More...

void	ucfpos_constrainField (UConstrainedFieldPosition ucfpos, int32_t category, int32_t field, UErrorCode ec)
	Sets a constraint on the category and field. More...

int32_t	ucfpos_getCategory (const UConstrainedFieldPosition ucfpos, UErrorCode ec)
	Gets the field category for the current position. More...

int32_t	ucfpos_getField (const UConstrainedFieldPosition ucfpos, UErrorCode ec)
	Gets the field for the current position. More...

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. More...

int64_t	ucfpos_getInt64IterationContext (const UConstrainedFieldPosition ucfpos, UErrorCode ec)
	Gets an int64 that FormattedValue implementations may use for storage. More...

void	ucfpos_setInt64IterationContext (UConstrainedFieldPosition ucfpos, int64_t context, UErrorCode ec)
	Sets an int64 that FormattedValue implementations may use for storage. More...

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. More...

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. More...

const UChar *	ufmtval_getString (const UFormattedValue ufmtval, int32_t pLength, UErrorCode *ec)
	Returns a pointer to the formatted string. More...

UBool	ufmtval_nextPosition (const UFormattedValue ufmtval, UConstrainedFieldPosition ucfpos, UErrorCode *ec)
	Iterates over field positions in the UFormattedValue. More...

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:

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

Draft:: This API may be changed in the future versions and was introduced in ICU 64

Definition at line 112 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.

Draft:: This API may be changed in the future versions and was introduced in 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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

Definition at line 362 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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

Enumerator
UFIELD_CATEGORY_UNDEFINED	For an undefined field category. Draft: This API may be changed in the future versions and was introduced in ICU 64
UFIELD_CATEGORY_DATE	For fields in UDateFormatField (udat.h), from ICU 3.0. Draft: This API may be changed in the future versions and was introduced in ICU 64
UFIELD_CATEGORY_NUMBER	For fields in UNumberFormatFields (unum.h), from ICU 49. Draft: This API may be changed in the future versions and was introduced in ICU 64
UFIELD_CATEGORY_LIST	For fields in UListFormatterField (ulistformatter.h), from ICU 63. Draft: This API may be changed in the future versions and was introduced in ICU 64
UFIELD_CATEGORY_RELATIVE_DATETIME	For fields in URelativeDateTimeFormatterField (ureldatefmt.h), from ICU 64. Draft: This API may be changed in the future versions and was introduced in 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. Draft: This API may be changed in the future versions and was introduced in ICU 64
UFIELD_CATEGORY_DATE_INTERVAL_SPAN	Category for spans in a date interval. Draft: This API may be changed in the future versions and was introduced in ICU 64

Definition at line 35 of file uformattedvalue.h.

Function Documentation

◆ ucfpos_close()

void ucfpos_close ( UConstrainedFieldPosition * ucfpos )

Destroys a UConstrainedFieldPosition and releases its memory.

Parameters

ucfpos The instance of UConstrainedFieldPosition.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

◆ ucfpos_constrainCategory()

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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

◆ ucfpos_constrainField()

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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

◆ ucfpos_getCategory()

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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

◆ ucfpos_getField()

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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

◆ ucfpos_getIndexes()

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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

◆ ucfpos_getInt64IterationContext()

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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

◆ ucfpos_matchesField()

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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

◆ ucfpos_open()

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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

◆ ucfpos_reset()

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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

◆ ucfpos_setInt64IterationContext()

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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

◆ ucfpos_setState()

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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

◆ ufmtval_getString()

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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

◆ ufmtval_nextPosition()

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.

Draft:: This API may be changed in the future versions and was introduced in ICU 64

Namespaces

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ UConstrainedFieldPosition

◆ UFieldCategory

◆ UFormattedValue

Enumeration Type Documentation

◆ UFieldCategory

Function Documentation

◆ ucfpos_close()

◆ ucfpos_constrainCategory()

◆ ucfpos_constrainField()

◆ ucfpos_getCategory()

◆ ucfpos_getField()

◆ ucfpos_getIndexes()

◆ ucfpos_getInt64IterationContext()

◆ ucfpos_matchesField()

◆ ucfpos_open()

◆ ucfpos_reset()

◆ ucfpos_setInt64IterationContext()

◆ ucfpos_setState()

◆ ufmtval_getString()

◆ ufmtval_nextPosition()