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

## Typedefs
typedef struct UEnumeration | UEnumeration
| structure representing an enumeration object instance
## Functions
void | uenum_close (UEnumeration *en)
| Disposes of resources in use by the iterator.
int32_t | uenum_count (UEnumeration *en, UErrorCode *status)
| Returns the number of elements that the iterator traverses.
const UChar * | uenum_unext (UEnumeration *en, int32_t *resultLength, UErrorCode *status)
| Returns the next element in the iterator's list.
const char * | uenum_next (UEnumeration *en, int32_t *resultLength, UErrorCode *status)
| Returns the next element in the iterator's list.
void | uenum_reset (UEnumeration *en, UErrorCode *status)
| Resets the iterator to the current list of service IDs.

## Detailed Description

C API: String Enumeration.

Definition in file uenum.h.

## Typedef Documentation

typedef struct UEnumeration UEnumeration

structure representing an enumeration object instance

Stable:
  ICU 2.2

Definition at line 39 of file uenum.h.

## Function Documentation

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

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

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

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

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

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Defines