ulistformatter.h File Reference

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

#include "unicode/utypes.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.
Functions
U_CAPI UListFormatter *	ulistfmt_open (const char *locale, UErrorCode *status)
	Open a new UListFormatter object using the rules for a given locale.
U_CAPI void	ulistfmt_close (UListFormatter *listfmt)
	Close a UListFormatter object.
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.

---

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 UListFormatter UListFormatter

C typedef for struct UListFormatter.

Stable:

ICU 55

Definition at line 34 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 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 UListFormatter* ulistfmt_open	(	const char *	locale,
		UErrorCode *	status
	)

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

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