ICU 76.1: common/unicode/uenum.h File Reference

ICU 76.1 76.1

Namespaces | Typedefs | Functions
uenum.h File Reference

C API: String Enumeration. 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 UEnumeration | UEnumeration
| structure representing an enumeration object instance

## Functions
U_CAPI void | uenum_close (UEnumeration *en)
| Disposes of resources in use by the iterator.
U_CAPI int32_t | uenum_count (UEnumeration *en, UErrorCode *status)
| Returns the number of elements that the iterator traverses.
U_CAPI const UChar * | uenum_unext (UEnumeration *en, int32_t *resultLength, UErrorCode *status)
| Returns the next element in the iterator's list.
U_CAPI const char * | uenum_next (UEnumeration *en, int32_t *resultLength, UErrorCode *status)
| Returns the next element in the iterator's list.
U_CAPI void | uenum_reset (UEnumeration *en, UErrorCode *status)
| Resets the iterator to the current list of service IDs.
U_CAPI UEnumeration * | uenum_openFromStringEnumeration (icu::StringEnumeration *adopted, UErrorCode *ec)
| Given a StringEnumeration, wrap it in a UEnumeration.
U_CAPI UEnumeration * | uenum_openUCharStringsEnumeration (const UChar *const strings[], int32_t count, UErrorCode *ec)
| Given an array of const UChar* strings, return a UEnumeration.
U_CAPI UEnumeration * | uenum_openCharStringsEnumeration (const char *const strings[], int32_t count, UErrorCode *ec)
| Given an array of const char* strings (invariant chars only), return a UEnumeration.

## Detailed Description

C API: String Enumeration.

Definition in file uenum.h.

## Typedef Documentation

## ◆ UEnumeration

typedef struct UEnumeration UEnumeration

structure representing an enumeration object instance

Stable
  ICU 2.2

Definition at line 44 of file uenum.h.

## Function Documentation

## ◆ uenum_close()

U_CAPI void uenum_close | ( | UEnumeration * | en | ) |

Disposes of resources in use by the iterator.

If en is NULL, does nothing. After this call, any char* or UChar* pointer returned by uenum_unext() or uenum_next() is invalid.

Parameters

  en | UEnumeration structure pointer

Stable
  ICU 2.2

## ◆ uenum_count()

U_CAPI int32_t uenum_count | ( | UEnumeration * | en,
|  | UErrorCode * | status )

Returns the number of elements that the iterator traverses.

If the iterator is out-of-sync with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR. This is a convenience function. It can end up being very expensive as all the items might have to be pre-fetched (depending on the type of data being traversed). Use with caution and only when necessary.

Parameters

  en | UEnumeration structure pointer
  status | error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the iterator is out of sync.

Returns
  number of elements in the iterator

Stable
  ICU 2.2

## ◆ uenum_next()

U_CAPI const char * uenum_next | ( | UEnumeration * | en,
|  | int32_t * | resultLength,
|  | UErrorCode * | status )

Returns the next element in the iterator's list.

If there are no more elements, returns NULL. If the iterator is out-of-sync with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned. If the native service string is a UChar* string, it is converted to char* with the invariant converter. The result is terminated by (char)0. If the conversion fails (because a character cannot be converted) then status is set to U_INVARIANT_CONVERSION_ERROR and the return value is undefined (but non-NULL).

Parameters

  en | the iterator object
  resultLength | pointer to receive the length of the result (not including the terminating \0). If the pointer is NULL it is ignored.
  status | the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if the iterator is out of sync with its service. Set to U_INVARIANT_CONVERSION_ERROR if the underlying native string is UChar* and conversion to char* with the invariant converter fails. This error pertains only to current string, so iteration might be able to continue successfully.

Returns
  a pointer to the string. The string will be zero-terminated. The return pointer is owned by this iterator and must not be deleted by the caller. The pointer is valid until the next call to any uenum_... method, including uenum_next() or uenum_unext(). When all strings have been traversed, returns NULL.

Stable
  ICU 2.2

## ◆ uenum_openCharStringsEnumeration()

U_CAPI UEnumeration * uenum_openCharStringsEnumeration | ( | const char *const | strings[],
|  | int32_t | count,
|  | UErrorCode * | ec )

Given an array of const char* strings (invariant chars only), return a UEnumeration.

String pointers from 0..count-1 must not be null. Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close.

const char* strings[] = { "Firstly", "Secondly", "Thirdly", "Fourthly" };
UEnumeration *u = uenum_openCharStringsEnumeration(strings, 4, &status);

Parameters

  strings | array of char* strings (each null terminated). All storage is owned by the caller.
  count | length of the array
  ec | error code

Returns
  the new UEnumeration object. Caller is responsible for calling uenum_close to free memory

See also
  uenum_close

Stable
  ICU 50

## ◆ uenum_openFromStringEnumeration()

U_CAPI UEnumeration * uenum_openFromStringEnumeration | ( | icu::StringEnumeration * | adopted,
|  | UErrorCode * | ec )

Given a StringEnumeration, wrap it in a UEnumeration.

The StringEnumeration is adopted; after this call, the caller must not delete it (regardless of error status).

Parameters

  adopted | the C++ StringEnumeration to be wrapped in a UEnumeration.
  ec | the error code.

Returns
  a UEnumeration wrapping the adopted StringEnumeration.

Stable
  ICU 4.2

## ◆ uenum_openUCharStringsEnumeration()

U_CAPI UEnumeration * uenum_openUCharStringsEnumeration | ( | const UChar *const | strings[],
|  | int32_t | count,
|  | UErrorCode * | ec )

Given an array of const UChar* strings, return a UEnumeration.

String pointers from 0..count-1 must not be null. Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close.

static const UChar nko_1[] = {0x07c1,0}, nko_2[] = {0x07c2,0}, nko_3[] = {0x07c3,0}, nko_4[] = {0x07c4,0};
static const UChar* ustrings[] = { nko_1, nko_2, nko_3, nko_4 };
UEnumeration *u = uenum_openUCharStringsEnumeration(ustrings, 4, &status);

Parameters

  strings | array of const UChar* strings (each null terminated). All storage is owned by the caller.
  count | length of the array
  ec | error code

Returns
  the new UEnumeration object. Caller is responsible for calling uenum_close to free memory.

See also
  uenum_close

Stable
  ICU 50

## ◆ uenum_reset()

U_CAPI void uenum_reset | ( | UEnumeration * | en,
|  | UErrorCode * | status )

Resets the iterator to the current list of service IDs.

This re-establishes sync with the service and rewinds the iterator to start at the first element.

Parameters

  en | the iterator object
  status | the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if the iterator is out of sync with its service.

Stable
  ICU 2.2

## ◆ uenum_unext()

U_CAPI const UChar * uenum_unext | ( | UEnumeration * | en,
|  | int32_t * | resultLength,
|  | UErrorCode * | status )

Returns the next element in the iterator's list.

If there are no more elements, returns NULL. If the iterator is out-of-sync with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned. If the native service string is a char* string, it is converted to UChar* with the invariant converter. The result is terminated by (UChar)0.

Parameters

  en | the iterator object
  resultLength | pointer to receive the length of the result (not including the terminating \0). If the pointer is NULL it is ignored.
  status | the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if the iterator is out of sync with its service.

Returns
  a pointer to the string. The string will be zero-terminated. The return pointer is owned by this iterator and must not be deleted by the caller. The pointer is valid until the next call to any uenum_... method, including uenum_next() or uenum_unext(). When all strings have been traversed, returns NULL.

Stable
  ICU 2.2