UEnumeration defines functions for handling String Enumeration.
Required Header
#include <utils_i18n.h>
Overview
The UEnumeration module allows to create String Enumeration from chars and uchars.
Typedef Documentation
Structure representing an enumeration.
For usage in C programs.
- Since :
- 2.3.1
Function Documentation
Given an array of const char*
strings (invariant chars only), return an i18n_uenumeration_h.
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 i18n_uenumeration_destroy().
- Since :
- 2.3.1
- Parameters:
-
[in] | strings | A array of char* strings (each null terminated). All storage is owned by the caller. |
[in] | count | The length of the array |
[out] | enumeration | A pointer to the new i18n_uenumeration_h. Caller is responsible for calling i18n_uenumeration_destroy() to free memory |
- Returns:
- The obtained error code.
- Return values:
-
- See also:
- i18n_uenumeration_destroy()
Returns the number of elements that the iterator traverses.
If the iterator is out-of-sync with its service, error code is set to I18N_ERROR_ENUM_OUT_OF_SYNC. 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.
- Since :
- 2.3.1
- Parameters:
-
- Returns:
- The number of elements in the iterator
- Exceptions:
-
Disposes of resources in use by the iterator.
If enumeration
is NULL
, does nothing. After this call, any char*
or i18n_uchar*
returned by i18n_uenumeration_unext() or i18n_uenumeration_next() is invalid.
- Since :
- 2.3.1
- Parameters:
-
- Returns:
- The obtained error code.
- Return values:
-
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, the I18N_ERROR_ENUM_OUT_OF_SYNC error code is set and NULL
is returned. If the native service string is a i18n_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 the error code is set to I18N_ERROR_INVARIANT_CONVERSION and the return value is undefined (but non-NULL).
- Since :
- 2.3.1
- Parameters:
-
[in] | enumeration | An i18n_uenumeration_h |
[out] | result_length | A pointer to receive the length of the result (not including the terminating \0). If the pointer is NULL it is ignored. |
- 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 i18n_uenumeration_... method, including i18n_uenumeration_next() or i18n_uenumeration_unext(). When all strings have been traversed, returns
NULL
.
- Exceptions:
-
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.
- Since :
- 2.3.1
- Parameters:
-
- Returns:
- The obtained error code.
- Return values:
-
Given an array of const i18n_uchar*
strings, return an i18n_uenumeration_h.
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 i18n_uenumeration_destroy().
- Since :
- 2.3.1
- Parameters:
-
[in] | strings | An array of const i18n_uchar* strings (each null terminated). All storage is owned by the caller. |
[in] | count | The length of the array |
[out] | enumeration | A pointer to the new i18n_uenumeration_h. Caller is responsible for calling i18n_uenumeration_destroy() to free memory. |
- Returns:
- The obtained error code.
- Return values:
-
- See also:
- i18n_uenumeration_destroy()
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, error code is set to I18N_ERROR_ENUM_OUT_OF_SYNC and NULL
is returned. If the native service string is a char*
string, it is converted to i18n_uchar*
with the invariant converter. The result is terminated by (i18n_uchar)0
.
- Since :
- 2.3.1
- Parameters:
-
[in] | enumeration | An i18n_uenumeration_h |
[out] | result_length | A pointer to receive the length of the result (not including the terminating \0). If the pointer is NULL it is ignored. |
- 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 i18n_uenumeration_... method, including i18n_uenumeration_next() or i18n_uenumeration_unext(). When all strings have been traversed, returns
NULL
.
- Exceptions:
-