Tizen(Headed) Native API
6.5
|
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.
Functions | |
int | i18n_uenumeration_destroy (i18n_uenumeration_h enumeration) |
Disposes of resources in use by the iterator. | |
int32_t | i18n_uenumeration_count (i18n_uenumeration_h enumeration) |
Returns the number of elements that the iterator traverses. | |
const i18n_uchar * | i18n_uenumeration_unext (i18n_uenumeration_h enumeration, int32_t *result_length) |
Returns the next element in the iterator's list. | |
const char * | i18n_uenumeration_next (i18n_uenumeration_h enumeration, int32_t *result_length) |
Returns the next element in the iterator's list. | |
int | i18n_uenumeration_reset (i18n_uenumeration_h enumeration) |
Resets the iterator to the current list of service IDs. | |
int | i18n_uenumeration_uchar_strings_enumeration_create (const i18n_uchar *const strings[], int32_t count, i18n_uenumeration_h *enumeration) |
Given an array of const i18n_uchar* strings, return an i18n_uenumeration_h. | |
int | i18n_uenumeration_char_strings_enumeration_create (const char *const strings[], int32_t count, i18n_uenumeration_h *enumeration) |
Given an array of const char* strings (invariant chars only), return an i18n_uenumeration_h. | |
Typedefs | |
typedef void * | i18n_uenumeration_h |
Structure representing an enumeration. |
Typedef Documentation
typedef void* i18n_uenumeration_h |
Structure representing an enumeration.
For usage in C programs.
- Since :
- 2.3.1
Function Documentation
int i18n_uenumeration_char_strings_enumeration_create | ( | const char *const | strings[], |
int32_t | count, | ||
i18n_uenumeration_h * | enumeration | ||
) |
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().
- Remarks:
- Error codes are described in i18n_error_code_e description.
- 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:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid function parameter
- See also:
- i18n_uenumeration_destroy()
int32_t i18n_uenumeration_count | ( | i18n_uenumeration_h | enumeration | ) |
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.
- Remarks:
- The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section. Error codes are described in Exceptions section and i18n_error_code_e description.
- Since :
- 2.3.1
- Parameters:
-
[in] enumeration An i18n_uenumeration_h to count
- Returns:
- The number of elements in the iterator
- Exceptions:
-
I18N_ERROR_INVALID_PARAMETER Invalid function parameter I18N_ERROR_ENUM_OUT_OF_SYNC The iterator is out of sync
int i18n_uenumeration_destroy | ( | i18n_uenumeration_h | enumeration | ) |
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.
- Remarks:
- Error codes are described in i18n_error_code_e description.
- Since :
- 2.3.1
- Parameters:
-
[in] enumeration An i18n_uenumeration_h to destroy
- Returns:
- The obtained error code.
- Return values:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid function parameter
const char* i18n_uenumeration_next | ( | i18n_uenumeration_h | enumeration, |
int32_t * | result_length | ||
) |
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).
- Remarks:
- The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section. Error codes are described in Exceptions section and i18n_error_code_e description.
- 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:
-
I18N_ERROR_INVALID_PARAMETER Invalid function parameter I18N_ERROR_ENUM_OUT_OF_SYNC The iterator is out of sync I18N_ERROR_INVARIANT_CONVERSION The underlying native string is i18n_uchar*
and conversion tochar*
with the invariant converter fails. This error pertains only to current string, so iteration might be able to continue successfully.
int i18n_uenumeration_reset | ( | i18n_uenumeration_h | enumeration | ) |
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.
- Remarks:
- Error codes are described in i18n_error_code_e description.
- Since :
- 2.3.1
- Parameters:
-
[in] enumeration An i18n_uenumeration_h
- Returns:
- The obtained error code.
- Return values:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid function parameter
int i18n_uenumeration_uchar_strings_enumeration_create | ( | const i18n_uchar *const | strings[], |
int32_t | count, | ||
i18n_uenumeration_h * | enumeration | ||
) |
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().
- Remarks:
- Error codes are described in i18n_error_code_e description.
- 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:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid function parameter
- See also:
- i18n_uenumeration_destroy()
const i18n_uchar* i18n_uenumeration_unext | ( | i18n_uenumeration_h | enumeration, |
int32_t * | result_length | ||
) |
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
.
- Remarks:
- The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section. Error codes are described in Exceptions section and i18n_error_code_e description.
- 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:
-
I18N_ERROR_INVALID_PARAMETER Invalid function parameter I18N_ERROR_ENUM_OUT_OF_SYNC The iterator is out of sync