ICU 4.8.1.1  4.8.1.1
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.

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 UCharuenum_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:
enUEnumeration 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:
enUEnumeration structure pointer
statuserror 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:
enthe iterator object
resultLengthpointer to receive the length of the result (not including the terminating \0). If the pointer is NULL it is ignored.
statusthe 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:
enthe iterator object
statusthe 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:
enthe iterator object
resultLengthpointer to receive the length of the result (not including the terminating \0). If the pointer is NULL it is ignored.
statusthe 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