"Fossies" - the Fresh Open Source Software Archive

Member "uformattedvalue_8h.html" (3 Oct 2019, 59215 Bytes) of package /linux/misc/icu4c-65_1-docs.zip:


Caution: In this restricted "Fossies" environment the current HTML page may not be correctly presentated and may have some non-functional links. You can here alternatively try to browse the pure source code or just view or download the uninterpreted raw source code. If the rendering is insufficient you may try to find and view the page on the project site itself.

ICU 65.1  65.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

 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

UConstrainedFieldPositionucfpos_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 UCharufmtval_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

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

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

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

◆ 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 363 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.

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 36 of file uformattedvalue.h.

Function Documentation

◆ ucfpos_close()

void ucfpos_close ( UConstrainedFieldPosition ucfpos)

Destroys a UConstrainedFieldPosition and releases its memory.

Parameters
ucfposThe 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
ucfposThe instance of UConstrainedFieldPosition.
categoryThe field category to fix when iterating.
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
categoryThe field category to fix when iterating.
fieldThe field to fix when iterating.
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
ecSet 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
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.
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
ucfposThe instance of UConstrainedFieldPosition.
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
categoryThe category to test.
fieldThe field to test.
ecSet 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
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
ecSet 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
ucfposThe instance of UConstrainedFieldPosition.
contextThe new iteration context.
ecSet 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
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.
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
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.
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
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.
Draft:
This API may be changed in the future versions and was introduced in ICU 64