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

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Function Documentation