ICU 74.1 74.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 More...
 

Functions

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

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

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

◆ 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" };
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.
struct UEnumeration UEnumeration
structure representing an enumeration object instance
Definition: uenum.h:44
Parameters
stringsarray of char* strings (each null terminated). All storage is owned by the caller.
countlength of the array
ecerror 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
adoptedthe C++ StringEnumeration to be wrapped in a UEnumeration.
ecthe 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);
U_CAPI UEnumeration * uenum_openUCharStringsEnumeration(const UChar *const strings[], int32_t count, UErrorCode *ec)
Given an array of const UChar* strings, return a UEnumeration.
char16_t UChar
The base type for UTF-16 code units and pointers.
Definition: umachine.h:386
Parameters
stringsarray of const UChar* strings (each null terminated). All storage is owned by the caller.
countlength of the array
ecerror 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
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

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