Tizen(Headed) Native API  6.5
UEnumeration

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_uchari18n_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]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

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.

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