ICU 63.1 63.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/localpointer.h"`

Go to the source code of this file.

## Namespaces
| icu
| File coll.h.

## Typedefs
typedef struct UListFormatter | UListFormatter
| C typedef for struct UListFormatter. More...
typedef enum UListFormatterField | UListFormatterField
| FieldPosition and UFieldPosition selectors for format fields defined by ListFormatter. More...

## Enumerations
enum | UListFormatterField { ULISTFMT_LITERAL_FIELD, ULISTFMT_ELEMENT_FIELD }
| FieldPosition and UFieldPosition selectors for format fields defined by ListFormatter. More...

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

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

## ◆ UListFormatter

typedef struct UListFormatter UListFormatter

C typedef for struct UListFormatter.

Stable:
  ICU 55

Definition at line 34 of file ulistformatter.h.

## ◆ UListFormatterField

typedef enum UListFormatterField UListFormatterField

FieldPosition and UFieldPosition selectors for format fields defined by ListFormatter.

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

## Enumeration Type Documentation

## ◆ UListFormatterField

enum UListFormatterField

FieldPosition and UFieldPosition selectors for format fields defined by ListFormatter.

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

Enumerator
ULISTFMT_LITERAL_FIELD | The literal text in the result which came from the resources. Draft: This API may be changed in the future versions and was introduced in ICU 63
ULISTFMT_ELEMENT_FIELD | The element text in the result which came from the input strings. Draft: This API may be changed in the future versions and was introduced in ICU 63

Definition at line 42 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

  listfmt | The UListFormatter object to close.

Stable:
  ICU 55

## ◆ 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

  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

## ◆ ulistfmt_open()

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