ICU 74.1 74.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. 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 , UFIELD_CATEGORY_NUMBER_RANGE_SPAN = 0x1000 + UFIELD_CATEGORY_NUMBER
}
 All possible field categories in ICU. More...
 

Functions

U_CAPI UConstrainedFieldPositionucfpos_open (UErrorCode *ec)
 Creates a new UConstrainedFieldPosition. More...
 
U_CAPI void ucfpos_reset (UConstrainedFieldPosition *ucfpos, UErrorCode *ec)
 Resets a UConstrainedFieldPosition to its initial state, as if it were newly created. More...
 
U_CAPI void ucfpos_close (UConstrainedFieldPosition *ucfpos)
 Destroys a UConstrainedFieldPosition and releases its memory. More...
 
U_CAPI void ucfpos_constrainCategory (UConstrainedFieldPosition *ucfpos, int32_t category, UErrorCode *ec)
 Sets a constraint on the field category. More...
 
U_CAPI void ucfpos_constrainField (UConstrainedFieldPosition *ucfpos, int32_t category, int32_t field, UErrorCode *ec)
 Sets a constraint on the category and field. More...
 
U_CAPI int32_t ucfpos_getCategory (const UConstrainedFieldPosition *ucfpos, UErrorCode *ec)
 Gets the field category for the current position. More...
 
U_CAPI int32_t ucfpos_getField (const UConstrainedFieldPosition *ucfpos, UErrorCode *ec)
 Gets the field for the current position. More...
 
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. More...
 
U_CAPI int64_t ucfpos_getInt64IterationContext (const UConstrainedFieldPosition *ucfpos, UErrorCode *ec)
 Gets an int64 that FormattedValue implementations may use for storage. More...
 
U_CAPI void ucfpos_setInt64IterationContext (UConstrainedFieldPosition *ucfpos, int64_t context, UErrorCode *ec)
 Sets an int64 that FormattedValue implementations may use for storage. More...
 
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. More...
 
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. More...
 
U_CAPI const UCharufmtval_getString (const UFormattedValue *ufmtval, int32_t *pLength, UErrorCode *ec)
 Returns a pointer to the formatted string. More...
 
U_CAPI 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

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

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

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

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
ucfposThe 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
ucfposThe instance of UConstrainedFieldPosition.
categoryThe field category to fix when iterating.
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
categoryThe field category to fix when iterating.
fieldThe field to fix when iterating.
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
pStartSet to the start index saved in the instance. Ignored if nullptr.
pLimitSet to the end index saved in the instance. Ignored if nullptr.
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
categoryThe category to test.
fieldThe field to test.
ecSet 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
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
contextThe new iteration context.
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
categoryThe new field category.
fieldThe new field.
startThe new inclusive start index.
limitThe new exclusive end index.
ecSet 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
ufmtvalThe object containing the formatted string and attributes.
pLengthOutput variable for the length of the string. Ignored if NULL.
ecSet 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
ufmtvalThe object containing the formatted string and attributes.
ucfposThe object used for iteration state; can provide constraints to iterate over only one specific category or field; see ucfpos_constrainCategory and ucfpos_constrainField.
ecSet if an error occurs.
Returns
true if another position was found; false otherwise.
Stable:
ICU 64