Tizen Native API
Functions | Typedefs
UEnumeration
i18n

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.

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

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]stringsA array of char* strings (each null terminated). All storage is owned by the caller.
[in]countThe length of the array
[out]enumerationA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]enumerationAn i18n_uenumeration_h to count
Returns:
The number of elements in the iterator
Exceptions:
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_ENUM_OUT_OF_SYNCThe 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]enumerationAn i18n_uenumeration_h to destroy
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]enumerationAn i18n_uenumeration_h
[out]result_lengthA 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_PARAMETERInvalid function parameter
I18N_ERROR_ENUM_OUT_OF_SYNCThe iterator is out of sync
I18N_ERROR_INVARIANT_CONVERSIONThe underlying native string is i18n_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.
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]enumerationAn i18n_uenumeration_h
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]stringsAn array of const i18n_uchar* strings (each null terminated). All storage is owned by the caller.
[in]countThe length of the array
[out]enumerationA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]enumerationAn i18n_uenumeration_h
[out]result_lengthA 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_PARAMETERInvalid function parameter
I18N_ERROR_ENUM_OUT_OF_SYNCThe iterator is out of sync