ulistformatter.h File Reference

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

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

Typedefs
typedef struct UListFormatter	UListFormatter
	C typedef for struct UListFormatter.
typedef struct UFormattedList	UFormattedList
	Opaque struct to contain the results of a UListFormatter operation.
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 UListFormatter *	ulistfmt_open (const char locale, UErrorCode status)
	Open a new UListFormatter object using the rules for a given locale.
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.
U_CAPI void	ulistfmt_close (UListFormatter *listfmt)
	Close a UListFormatter object.
U_CAPI UFormattedList *	ulistfmt_openResult (UErrorCode *ec)
	Creates an object to hold the result of a UListFormatter operation.
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.
U_CAPI void	ulistfmt_closeResult (UFormattedList *uresult)
	Releases the UFormattedList created by ulistfmt_openResult().
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.
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().

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

typedef struct UFormattedList UFormattedList

Opaque struct to contain the results of a UListFormatter operation.

Stable:: ICU 64

Definition at line 42 of file ulistformatter.h.

typedef struct UListFormatter UListFormatter

C typedef for struct UListFormatter.

Stable:: ICU 55

Definition at line 35 of file ulistformatter.h.

Enumeration Type Documentation

enum 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 49 of file ulistformatter.h.

enum UListFormatterType

Type of meaning expressed by the list.

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

Enumerator:

ULISTFMT_TYPE_AND

Conjunction formatting, e.g.

"Alice, Bob, Charlie, and Delta".

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

ULISTFMT_TYPE_OR

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

"Alice, Bob, Charlie, or Delta".

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

ULISTFMT_TYPE_UNITS

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

"5 pounds, 12 ounces".

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

Definition at line 68 of file ulistformatter.h.

enum UListFormatterWidth

Verbosity level of the list patterns.

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

Enumerator:

ULISTFMT_WIDTH_WIDE

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

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

ULISTFMT_WIDTH_SHORT

Use list formatting of typical length.

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

ULISTFMT_WIDTH_NARROW

Use list formatting of the shortest possible length.

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

Definition at line 97 of file ulistformatter.h.

Function Documentation

U_CAPI void ulistfmt_close ( UListFormatter * listfmt )

Close a UListFormatter object.

Once closed it may no longer be used.

Parameters:

listfmt

The UListFormatter object to close.

Stable:: ICU 55

U_CAPI void ulistfmt_closeResult ( UFormattedList * uresult )

Releases the UFormattedList created by ulistfmt_openResult().

Parameters:

uresult

The object to release.

Stable:: ICU 64

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:

	listfmt	The UListFormatter object specifying the list conventions.
	strings	An array of pointers to UChar strings; the array length is specified by stringCount. Must be non-NULL if stringCount > 0.
	stringLengths	An 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.
	stringCount	the number of entries in strings[], and the number of entries in the stringLengths array if it is not NULL. Must be >= 0.
	result	A pointer to a buffer to receive the formatted list.
	resultCapacity	The maximum size of result.
	status	A 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

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:

	listfmt	The UListFormatter object specifying the list conventions.
	strings	An array of pointers to UChar strings; the array length is specified by stringCount. Must be non-NULL if stringCount > 0.
	stringLengths	An 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.
	stringCount	the number of entries in strings[], and the number of entries in the stringLengths array if it is not NULL. Must be >= 0.
	uresult	The object in which to store the result of the list formatting operation. See ulistfmt_openResult().
	status	Error code set if an error occurred during formatting.

Stable:: ICU 64

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:

	locale	The locale whose rules should be used; may be NULL for default locale.
	status	A 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

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:

	locale	The locale whose rules should be used; may be NULL for default locale.
	type	The type of list formatting to use.
	width	The width of formatting to use.
	status	A 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.

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

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:

ec

Set if an error occurs.

Returns:: A pointer needing ownership.

Stable:: ICU 64

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:

	uresult	The object containing the formatted string.
	ec	Set if an error occurs.

Returns:: A UFormattedValue owned by the input object.

Stable:: ICU 64

ulistformatter.h File Reference

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation