Alphabetic Index supports the creation of a UI index appropriate for a given language.

Required Header

#include <utils_i18n.h>

Overview

The module can generate a list of labels for use as a UI "index", that is, a list of clickable characters (or character sequences) that allow the user to see a segment (bucket) of a larger "target" list. That is, each label corresponds to a bucket in the target list, where everything in the bucket is greater than or equal to the character (according to the locale's collation). Strings can be added to the index; they will be in sorted order in the right bucket. The module also supports having buckets for strings before the first (underflow), after the last (overflow), and between scripts (inflow). For example, if the index is constructed with labels for Russian and English, Greek characters would fall into an inflow bucket between the other two scripts.

Functions
int	i18n_alpha_idx_create (const char language, const char country, i18n_alpha_idx_h *index) TIZEN_DEPRECATED_API
	Creates an alphabetic index object for the specified locale.
int	i18n_alpha_idx_destroy (i18n_alpha_idx_h index)
	Destroys the alphabetic index object.
int	i18n_alpha_idx_add_labels (i18n_alpha_idx_h index, const char language, const char country) TIZEN_DEPRECATED_API
	Adds the index characters from a specified locale to the index.
int	i18n_alpha_idx_add_record (i18n_alpha_idx_h index, const char name, const void data)
	Adds the record to the alphabetic index.
int	i18n_alpha_idx_get_next_bucket (i18n_alpha_idx_h index, bool *available)
	Sets the next bucket as current bucket in the index.
int	i18n_alpha_idx_get_next_record (i18n_alpha_idx_h index, bool *available)
	Sets the next record as current record in current bucket of the index.
int	i18n_alpha_idx_get_bucket_record_count (i18n_alpha_idx_h index, int32_t *records_count)
	Gets the number of <name, data> records in the current bucket.
int	i18n_alpha_idx_get_bucket_label (i18n_alpha_idx_h index, char **label)
	Gets the name of the label of the current bucket in alphabetic index.
const void *	i18n_alpha_idx_get_record_data (i18n_alpha_idx_h index)
	Gets the data pointer of the current record in a current bucket in alphabetic index.
int	i18n_alpha_idx_get_inflow_label (i18n_alpha_idx_h index, char **label)
	Gets the default label used for abbreviated buckets between other index characters.
int	i18n_alpha_idx_set_inflow_label (i18n_alpha_idx_h index, const char *label)
	Sets the default label used for abbreviated buckets between other index characters.
int	i18n_alpha_idx_get_overflow_label (i18n_alpha_idx_h index, char **label)
	Gets the special label used for items that sort after the last normal label, and that would not otherwise have an appropriate label.
int	i18n_alpha_idx_set_overflow_label (i18n_alpha_idx_h index, const char *label)
	Sets the special label used for items that sort after the last normal label, and that would not otherwise have an appropriate label.
int	i18n_alpha_idx_get_underflow_label (i18n_alpha_idx_h index, char **label)
	Gets the special label used for items that sort before the first normal label, and that would not otherwise have an appropriate label.
int	i18n_alpha_idx_set_underflow_label (i18n_alpha_idx_h index, const char *label)
	Sets the special label used for items that sort before the first normal label, and that would not otherwise have an appropriate label.
int	i18n_alpha_idx_get_max_label_count (i18n_alpha_idx_h index, int32_t *max_label_count)
	Gets the limit on the number of labels permitted in the index.
int	i18n_alpha_idx_set_max_label_count (i18n_alpha_idx_h index, int32_t max_label_count)
	Sets a limit on the number of labels permitted in the index.
int	i18n_alpha_idx_clear_records (i18n_alpha_idx_h index)
	Remove all records from the index.
int	i18n_alpha_idx_get_bucket_count (i18n_alpha_idx_h index, int32_t *bucket_count)
	Gets the number of labels in this index.
int	i18n_alpha_idx_get_record_count (i18n_alpha_idx_h index, int32_t *record_count)
	Gets the total number of records in this index, that is, the number of <name, data> pairs added.
int	i18n_alpha_idx_get_bucket_index (i18n_alpha_idx_h index, const char item_name, int32_t bucket_index)
	Given the name of a record, returns the zero-based index of the bucket in which the item should appear.
int	i18n_alpha_idx_get_current_bucket_index (i18n_alpha_idx_h index, int32_t *bucket_index)
	Gets the zero based index of the current bucket of this index.
int	i18n_alpha_idx_get_bucket_label_type (i18n_alpha_idx_h index, i18n_alpha_idx_label_type_e *type)
	Gets the type of the label for the current Bucket (selected by the iteration over Buckets).
int	i18n_alpha_idx_get_record_name (i18n_alpha_idx_h index, char **record_name)
	Gets the name of the current record.
int	i18n_alpha_idx_reset_bucket_iter (i18n_alpha_idx_h index)
	Resets the bucket iteration for this index.
int	i18n_alpha_idx_reset_record_iter (i18n_alpha_idx_h index)
	Resets the record iteration for this index to before the first Record in the current Bucket.
int	i18n_alpha_idx_create_from_locale_id (const char locale_id, i18n_alpha_idx_h index)
	Creates an alphabetic index object for the specified locale.
int	i18n_alpha_idx_add_labels_with_locale_id (i18n_alpha_idx_h index, const char *locale_id)
	Adds the index characters from a specified locale to the index.
Typedefs
typedef void *	i18n_alpha_idx_h
	The Alphabetic index handle.

Typedef Documentation

typedef void* i18n_alpha_idx_h

The Alphabetic index handle.

Since :: 3.0

Enumeration Type Documentation

enum i18n_alpha_idx_label_type_e

Enumeration for alphabetic index label types.

Since :: 3.0

See also:: i18n_alpha_idx_get_bucket_label_type()

Enumerator:

I18N_ALPHA_IDX_NORMAL	Normal Label, typically the starting letter of the names in the bucket with this label.
I18N_ALPHA_IDX_UNDERFLOW	Underflow Label. The bucket with this label contains names in scripts that sort before any of the bucket labels in this index.
I18N_ALPHA_IDX_INFLOW	Inflow Label. The bucket with this label contains names in scripts that sort between two of the bucket labels in this index. Inflow labels are created when an index contains normal labels for multiple scripts, and skips other scripts that sort between some of the included scripts.
I18N_ALPHA_IDX_OVERFLOW	Overflow Label. The bucket with this label contains names in scripts that sort after all of the bucket labels in this index.

Function Documentation

int i18n_alpha_idx_add_labels	(	i18n_alpha_idx_h	index,
		const char *	language,
		const char *	country
	)

Adds the index characters from a specified locale to the index.

Deprecated:: Deprecated since 5.0. Use i18n_alpha_idx_add_labels_with_locale_id() instead.

The labels are added to those that are already in the index; they do not replace the existing index characters. The collation order for this index is not changed; it remains that of the locale that was originally specified when creating this Index.

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	Label will be added to this alphabetic index
[in]	language	The language of the locale
[in]	country	The country of the locale

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_add_labels_with_locale_id	(	i18n_alpha_idx_h	index,
		const char *	locale_id
	)

Adds the index characters from a specified locale to the index.

The labels are added to those that are already in the index; they do not replace the existing index characters. The collation order for this index is not changed; it remains that of the locale that was originally specified when creating this Index.

Since :: 5.0

Parameters:

[in]	index	Label will be added to this alphabetic index
[in]	locale_id	The locale string containing language and country code

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_add_record	(	i18n_alpha_idx_h	index,
		const char *	name,
		const void *	data
	)

Adds the record to the alphabetic index.

Each record will be associated with an index Bucket based on the record's name. The list of records for each bucket will be sorted based on the collation ordering of the names in the index's locale. Records with duplicate names are permitted; they will be kept in the order that they were added.

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	Record will be added to this alphabetic index
[in]	name	The display name for the record. The Record will be placed in a bucket based on this name.
[in]	data	An optional pointer to user data associated with this item

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_clear_records ( i18n_alpha_idx_h index )

Remove all records from the index.

The set of Buckets, which define the headings under which records are classified, is not altered.

Since :: 2.3.2 and 3.0

Parameters:

[in] index The alphabetic index, which contains buckets with records

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_create	(	const char *	language,
		const char *	country,
		i18n_alpha_idx_h *	index
	)

Creates an alphabetic index object for the specified locale.

Deprecated:: Deprecated since 5.0. Use i18n_alpha_idx_create_from_locale_id() instead.

If the locale's data does not include index characters, a set of them will be synthesized based on the locale's exemplar characters. The locale determines the sorting order for both the index characters and the user item names appearing under each Index character.

Since :: 2.3.2 and 3.0

Remarks:: The created object should be released by the caller with the i18n_alpha_idx_destroy() function.

Parameters:

[in]	language	The language of the locale
[in]	country	The country of the locale
[out]	index	The created alphabetic index object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_alpha_idx_create_from_locale_id	(	const char *	locale_id,
		i18n_alpha_idx_h *	index
	)

Creates an alphabetic index object for the specified locale.

If the locale's data does not include index characters, a set of them will be synthesized based on the locale's exemplar characters. The locale determines the sorting order for both the index characters and the user item names appearing under each Index character.

Since :: 5.0

Remarks:: The created object should be released by the caller with the i18n_alpha_idx_destroy() function.

Parameters:

[in]	locale_id	The locale string containing language and country code
[out]	index	The created alphabetic index object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_alpha_idx_destroy ( i18n_alpha_idx_h index )

Destroys the alphabetic index object.

Since :: 2.3.2 and 3.0

Parameters:

[in] index The alphabetic index to be destroyed

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_get_bucket_count	(	i18n_alpha_idx_h	index,
		int32_t *	bucket_count
	)

Gets the number of labels in this index.

Since :: 2.3.2 and 3.0

Remarks:: Note: may trigger lazy index construction.

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[out]	bucket_count	The number of labels in this index, including any under, over or inflow labels

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_get_bucket_index	(	i18n_alpha_idx_h	index,
		const char *	item_name,
		int32_t *	bucket_index
	)

Given the name of a record, returns the zero-based index of the bucket in which the item should appear.

The name need not be in the index. A Record will not be added to the index by this function. Bucket numbers are zero-based, in Bucket iteration order.

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[in]	item_name	The name whose bucket position in the index is to be determined
[out]	bucket_index	The bucket number for this name

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_get_bucket_label	(	i18n_alpha_idx_h	index,
		char **	label
	)

Gets the name of the label of the current bucket in alphabetic index.

If the iteration is before the first Bucket (i18n_alpha_idx_get_next_bucket() has not been called), or after the last, return an empty string.

Since :: 2.3.2 and 3.0

Remarks:: The obtained label should be released by the caller with the free() function.

Parameters:

[in]	index	The alphabetic index, which contains buckets
[out]	label	The name of the label of the current bucket

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_alpha_idx_get_bucket_label_type	(	i18n_alpha_idx_h	index,
		i18n_alpha_idx_label_type_e *	type
	)

Gets the type of the label for the current Bucket (selected by the iteration over Buckets).

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[out]	type	The alphabetic index label type

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_get_bucket_record_count	(	i18n_alpha_idx_h	index,
		int32_t *	records_count
	)

Gets the number of <name, data> records in the current bucket.

If the current bucket iteration position is before the first label or after the last, return 0.

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[out]	records_count	Number of <name, data> records in the current bucket

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_get_current_bucket_index	(	i18n_alpha_idx_h	index,
		int32_t *	bucket_index
	)

Gets the zero based index of the current bucket of this index.

Sets the variable pointed by the bucket_index to -1 if no iteration is in process.

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[out]	bucket_index	The index of the current Bucket

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_get_inflow_label	(	i18n_alpha_idx_h	index,
		char **	label
	)

Gets the default label used for abbreviated buckets between other index characters.

For example, consider the labels when Latin and Greek are used: X Y Z ... Α Β Γ

Since :: 2.3.2 and 3.0

Remarks:: The obtained label should be released by the caller with the free() function.

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[out]	label	The default label used for abbreviated bucket between other index characters

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_alpha_idx_get_max_label_count	(	i18n_alpha_idx_h	index,
		int32_t *	max_label_count
	)

Gets the limit on the number of labels permitted in the index.

The number does not include over, under and inflow labels.

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[out]	max_label_count	The maximum number of labels

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_get_next_bucket	(	i18n_alpha_idx_h	index,
		bool *	available
	)

Sets the next bucket as current bucket in the index.

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	The alphabetic index, which contains buckets
[out]	available	A flag set to `true` if the next bucket was available, or `false` if there were no more buckets.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_ENUM_OUT_OF_SYNC	The index is modified while an enumeration of its contents are in process.

int i18n_alpha_idx_get_next_record	(	i18n_alpha_idx_h	index,
		bool *	available
	)

Sets the next record as current record in current bucket of the index.

When i18n_alpha_idx_get_next_bucket() is called, record iteration is reset to just before the first record in the new bucket.

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[out]	available	A flag set to `true` if the next record was available, or `false` if there were no more records.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_ENUM_OUT_OF_SYNC	The index is modified while an enumeration of its contents are in process.

int i18n_alpha_idx_get_overflow_label	(	i18n_alpha_idx_h	index,
		char **	label
	)

Gets the special label used for items that sort after the last normal label, and that would not otherwise have an appropriate label.

Since :: 2.3.2 and 3.0

Remarks:: The obtained label should be released by the caller with the free() function.

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[out]	label	The overflow label

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_alpha_idx_get_record_count	(	i18n_alpha_idx_h	index,
		int32_t *	record_count
	)

Gets the total number of records in this index, that is, the number of <name, data> pairs added.

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[out]	record_count	The number of records in this index, that is, the total number of (name, data) items added with i18n_alpha_idx_add_record()

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

const void* i18n_alpha_idx_get_record_data ( i18n_alpha_idx_h index )

Gets the data pointer of the current record in a current bucket in alphabetic index.

Returns NULL if:

the current iteration position is before the first item in this Bucket, or after the last,
the given index parameter is invalid.
Since :
2.3.2 and 3.0

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.

Parameters:

[in] index The alphabetic index, which contains buckets with records

Returns:
The data pointer of the current record in a current bucket

Exceptions:

I18N_ERROR_NONE Successful

I18N_ERROR_INVALID_PARAMETER Invalid parameter

int i18n_alpha_idx_get_record_name	(	i18n_alpha_idx_h	index,
		char **	record_name
	)

Gets the name of the current record.

If the Record iteration position is before the first or after the last record, sets the string pointed by the record_name parameter to NULL and returns the I18N_ERROR_INDEX_OUTOFBOUNDS error code.

Since :: 2.3.2 and 3.0

Remarks:: The obtained record_name should be released by the caller with the free() function.

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[out]	record_name	The name of the current index item

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory
I18N_ERROR_INDEX_OUTOFBOUNDS	Trying to access the index that is out of bounds

int i18n_alpha_idx_get_underflow_label	(	i18n_alpha_idx_h	index,
		char **	label
	)

Gets the special label used for items that sort before the first normal label, and that would not otherwise have an appropriate label.

Since :: 2.3.2 and 3.0

Remarks:: The obtained label should be released by the caller with the free() function.

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[out]	label	The underflow label

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_alpha_idx_reset_bucket_iter ( i18n_alpha_idx_h index )

Resets the bucket iteration for this index.

The next call to i18n_alpha_idx_get_next_bucket() will restart the iteration at the first label.

Since :: 2.3.2 and 3.0

Parameters:

[in] index The alphabetic index, which contains buckets with records

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_reset_record_iter ( i18n_alpha_idx_h index )

Resets the record iteration for this index to before the first Record in the current Bucket.

The next call to i18n_alpha_idx_get_next_record() will restart the iteration at the first label.

Since :: 2.3.2 and 3.0

Parameters:

[in] index The alphabetic index, which contains buckets with records

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_set_inflow_label	(	i18n_alpha_idx_h	index,
		const char *	label
	)

Sets the default label used for abbreviated buckets between other index characters.

An inflow label will be automatically inserted if two otherwise-adjacent label characters are from different scripts, e.g. Latin and Cyrillic, and a third script, e.g. Greek, sorts between the two. The default inflow character is an ellipsis (...)

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[in]	label	The new inflow label

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_set_max_label_count	(	i18n_alpha_idx_h	index,
		int32_t	max_label_count
	)

Sets a limit on the number of labels permitted in the index.

The number does not include over, under and inflow labels. Currently, if the number is exceeded, then every nth item is removed to bring the count down. A more sophisticated mechanism may be available in the future.

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[in]	max_label_count	The new maximum number of labels

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_set_overflow_label	(	i18n_alpha_idx_h	index,
		const char *	label
	)

Sets the special label used for items that sort after the last normal label, and that would not otherwise have an appropriate label.

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[in]	label	The new overflow label

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_alpha_idx_set_underflow_label	(	i18n_alpha_idx_h	index,
		const char *	label
	)

Sets the special label used for items that sort before the first normal label, and that would not otherwise have an appropriate label.

Since :: 2.3.2 and 3.0

Parameters:

[in]	index	The alphabetic index, which contains buckets with records
[in]	label	The new underflow label

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation