ICU 74.1 74.1
Namespaces | Typedefs | Enumerations | Functions
ulistformatter.h File Reference

C API: Format a list in a locale-appropriate way. More...

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

Go to the source code of this file.

Namespaces

namespace  icu
 File coll.h.
 

Typedefs

typedef struct UListFormatter UListFormatter
 C typedef for struct UListFormatter. More...
 
typedef struct UFormattedList UFormattedList
 Opaque struct to contain the results of a UListFormatter operation. More...
 
typedef enum UListFormatterField UListFormatterField
 FieldPosition and UFieldPosition selectors for format fields defined by ListFormatter. More...
 
typedef enum UListFormatterType UListFormatterType
 Type of meaning expressed by the list. More...
 
typedef enum UListFormatterWidth UListFormatterWidth
 Verbosity level of the list patterns. More...
 

Enumerations

enum  UListFormatterField { ULISTFMT_LITERAL_FIELD , ULISTFMT_ELEMENT_FIELD }
 FieldPosition and UFieldPosition selectors for format fields defined by ListFormatter. More...
 
enum  UListFormatterType { ULISTFMT_TYPE_AND , ULISTFMT_TYPE_OR , ULISTFMT_TYPE_UNITS }
 Type of meaning expressed by the list. More...
 
enum  UListFormatterWidth { ULISTFMT_WIDTH_WIDE , ULISTFMT_WIDTH_SHORT , ULISTFMT_WIDTH_NARROW }
 Verbosity level of the list patterns. More...
 

Functions

U_CAPI UListFormatterulistfmt_open (const char *locale, UErrorCode *status)
 Open a new UListFormatter object using the rules for a given locale. More...
 
U_CAPI UListFormatterulistfmt_openForType (const char *locale, UListFormatterType type, UListFormatterWidth width, UErrorCode *status)
 Open a new UListFormatter object appropriate for the given locale, list type, and style. More...
 
U_CAPI void ulistfmt_close (UListFormatter *listfmt)
 Close a UListFormatter object. More...
 
U_CAPI UFormattedListulistfmt_openResult (UErrorCode *ec)
 Creates an object to hold the result of a UListFormatter operation. More...
 
U_CAPI const UFormattedValueulistfmt_resultAsValue (const UFormattedList *uresult, UErrorCode *ec)
 Returns a representation of a UFormattedList as a UFormattedValue, which can be subsequently passed to any API requiring that type. More...
 
U_CAPI void ulistfmt_closeResult (UFormattedList *uresult)
 Releases the UFormattedList created by ulistfmt_openResult(). More...
 
U_CAPI int32_t ulistfmt_format (const UListFormatter *listfmt, const UChar *const strings[], const int32_t *stringLengths, int32_t stringCount, UChar *result, int32_t resultCapacity, UErrorCode *status)
 Formats a list of strings using the conventions established for the UListFormatter object. More...
 
U_CAPI void ulistfmt_formatStringsToResult (const UListFormatter *listfmt, const UChar *const strings[], const int32_t *stringLengths, int32_t stringCount, UFormattedList *uresult, UErrorCode *status)
 Formats a list of strings to a UFormattedList, which exposes more information than the string exported by ulistfmt_format(). More...
 

Detailed Description

C API: Format a list in a locale-appropriate way.

A UListFormatter is used to format a list of items in a locale-appropriate way, using data from CLDR. Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted as "Alice, Bob, Charlie, and Delta" in English.

Definition in file ulistformatter.h.

Typedef Documentation

◆ UFormattedList

Opaque struct to contain the results of a UListFormatter operation.

Stable:
ICU 64

Definition at line 45 of file ulistformatter.h.

◆ UListFormatter

C typedef for struct UListFormatter.

Stable:
ICU 55

Definition at line 38 of file ulistformatter.h.

◆ UListFormatterField

FieldPosition and UFieldPosition selectors for format fields defined by ListFormatter.

Stable:
ICU 63

◆ UListFormatterType

Type of meaning expressed by the list.

Stable:
ICU 67

◆ UListFormatterWidth

Verbosity level of the list patterns.

Stable:
ICU 67

Enumeration Type Documentation

◆ UListFormatterField

FieldPosition and UFieldPosition selectors for format fields defined by ListFormatter.

Stable:
ICU 63
Enumerator
ULISTFMT_LITERAL_FIELD 

The literal text in the result which came from the resources.

Stable:
ICU 63
ULISTFMT_ELEMENT_FIELD 

The element text in the result which came from the input strings.

Stable:
ICU 63

Definition at line 52 of file ulistformatter.h.

◆ UListFormatterType

Type of meaning expressed by the list.

Stable:
ICU 67
Enumerator
ULISTFMT_TYPE_AND 

Conjunction formatting, e.g.

"Alice, Bob, Charlie, and Delta".

Stable:
ICU 67
ULISTFMT_TYPE_OR 

Disjunction (or alternative, or simply one of) formatting, e.g.

"Alice, Bob, Charlie, or Delta".

Stable:
ICU 67
ULISTFMT_TYPE_UNITS 

Formatting of a list of values with units, e.g.

"5 pounds, 12 ounces".

Stable:
ICU 67

Definition at line 70 of file ulistformatter.h.

◆ UListFormatterWidth

Verbosity level of the list patterns.

Stable:
ICU 67
Enumerator
ULISTFMT_WIDTH_WIDE 

Use list formatting with full words (no abbreviations) when possible.

Stable:
ICU 67
ULISTFMT_WIDTH_SHORT 

Use list formatting of typical length.

Stable:
ICU 67
ULISTFMT_WIDTH_NARROW 

Use list formatting of the shortest possible length.

Stable:
ICU 67

Definition at line 99 of file ulistformatter.h.

Function Documentation

◆ ulistfmt_close()

U_CAPI void ulistfmt_close ( UListFormatter listfmt)

Close a UListFormatter object.

Once closed it may no longer be used.

Parameters
listfmtThe UListFormatter object to close.
Stable:
ICU 55

◆ ulistfmt_closeResult()

U_CAPI void ulistfmt_closeResult ( UFormattedList uresult)

Releases the UFormattedList created by ulistfmt_openResult().

Parameters
uresultThe object to release.
Stable:
ICU 64

◆ ulistfmt_format()

U_CAPI int32_t ulistfmt_format ( const UListFormatter listfmt,
const UChar *const  strings[],
const int32_t *  stringLengths,
int32_t  stringCount,
UChar result,
int32_t  resultCapacity,
UErrorCode status 
)

Formats a list of strings using the conventions established for the UListFormatter object.

Parameters
listfmtThe UListFormatter object specifying the list conventions.
stringsAn array of pointers to UChar strings; the array length is specified by stringCount. Must be non-NULL if stringCount > 0.
stringLengthsAn array of string lengths corresponding to the strings[] parameter; any individual length value may be negative to indicate that the corresponding strings[] entry is 0-terminated, or stringLengths itself may be NULL if all of the strings are 0-terminated. If non-NULL, the stringLengths array must have stringCount entries.
stringCountthe number of entries in strings[], and the number of entries in the stringLengths array if it is not NULL. Must be >= 0.
resultA pointer to a buffer to receive the formatted list.
resultCapacityThe maximum size of result.
statusA pointer to a standard ICU UErrorCode (input/output parameter). Its input value must pass the U_SUCCESS() test, or else the function returns immediately. The caller should check its output value with U_FAILURE(), or use with function chaining (see User Guide for details).
Returns
The total buffer size needed; if greater than resultLength, the output was truncated. May be <=0 if unable to determine the total buffer size needed (e.g. for illegal arguments).
Stable:
ICU 55

◆ ulistfmt_formatStringsToResult()

U_CAPI void ulistfmt_formatStringsToResult ( const UListFormatter listfmt,
const UChar *const  strings[],
const int32_t *  stringLengths,
int32_t  stringCount,
UFormattedList uresult,
UErrorCode status 
)

Formats a list of strings to a UFormattedList, which exposes more information than the string exported by ulistfmt_format().

Parameters
listfmtThe UListFormatter object specifying the list conventions.
stringsAn array of pointers to UChar strings; the array length is specified by stringCount. Must be non-NULL if stringCount > 0.
stringLengthsAn array of string lengths corresponding to the strings[] parameter; any individual length value may be negative to indicate that the corresponding strings[] entry is 0-terminated, or stringLengths itself may be NULL if all of the strings are 0-terminated. If non-NULL, the stringLengths array must have stringCount entries.
stringCountthe number of entries in strings[], and the number of entries in the stringLengths array if it is not NULL. Must be >= 0.
uresultThe object in which to store the result of the list formatting operation. See ulistfmt_openResult().
statusError code set if an error occurred during formatting.
Stable:
ICU 64

◆ ulistfmt_open()

U_CAPI UListFormatter * ulistfmt_open ( const char *  locale,
UErrorCode status 
)

Open a new UListFormatter object using the rules for a given locale.

The object will be initialized with AND type and WIDE width.

Parameters
localeThe locale whose rules should be used; may be NULL for default locale.
statusA pointer to a standard ICU UErrorCode (input/output parameter). Its input value must pass the U_SUCCESS() test, or else the function returns immediately. The caller should check its output value with U_FAILURE(), or use with function chaining (see User Guide for details).
Returns
A pointer to a UListFormatter object for the specified locale, or NULL if an error occurred.
Stable:
ICU 55

◆ ulistfmt_openForType()

U_CAPI UListFormatter * ulistfmt_openForType ( const char *  locale,
UListFormatterType  type,
UListFormatterWidth  width,
UErrorCode status 
)

Open a new UListFormatter object appropriate for the given locale, list type, and style.

Parameters
localeThe locale whose rules should be used; may be NULL for default locale.
typeThe type of list formatting to use.
widthThe width of formatting to use.
statusA pointer to a standard ICU UErrorCode (input/output parameter). Its input value must pass the U_SUCCESS() test, or else the function returns immediately. The caller should check its output value with U_FAILURE(), or use with function chaining (see User Guide for details).
Returns
A pointer to a UListFormatter object for the specified locale, or NULL if an error occurred.
Stable:
ICU 67

◆ ulistfmt_openResult()

U_CAPI UFormattedList * ulistfmt_openResult ( UErrorCode ec)

Creates an object to hold the result of a UListFormatter operation.

The object can be used repeatedly; it is cleared whenever passed to a format function.

Parameters
ecSet if an error occurs.
Returns
A pointer needing ownership.
Stable:
ICU 64

◆ ulistfmt_resultAsValue()

U_CAPI const UFormattedValue * ulistfmt_resultAsValue ( const UFormattedList uresult,
UErrorCode ec 
)

Returns a representation of a UFormattedList as a UFormattedValue, which can be subsequently passed to any API requiring that type.

The returned object is owned by the UFormattedList and is valid only as long as the UFormattedList is present and unchanged in memory.

You can think of this method as a cast between types.

When calling ufmtval_nextPosition(): The fields are returned from start to end. The special field category UFIELD_CATEGORY_LIST_SPAN is used to indicate which argument was inserted at the given position. The span category will always occur before the corresponding instance of UFIELD_CATEGORY_LIST in the ufmtval_nextPosition() iterator.

Parameters
uresultThe object containing the formatted string.
ecSet if an error occurs.
Returns
A UFormattedValue owned by the input object.
Stable:
ICU 64