Tizen Native API
Functions | Typedefs
Alphabetic Index
i18n

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)
 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)
 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.

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.

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]indexLabel will be added to this alphabetic index
[in]languageThe language of the locale
[in]countryThe country of the locale
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexRecord will be added to this alphabetic index
[in]nameThe display name for the record. The Record will be placed in a bucket based on this name.
[in]dataAn optional pointer to user data associated with this item
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets with records
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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.

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]languageThe language of the locale
[in]countryThe country of the locale
[out]indexThe created alphabetic index object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]indexThe alphabetic index to be destroyed
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets with records
[out]bucket_countThe 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets with records
[in]item_nameThe name whose bucket position in the index is to be determined
[out]bucket_indexThe bucket number for this name
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets
[out]labelThe name of the label of the current bucket
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]indexThe alphabetic index, which contains buckets with records
[out]typeThe alphabetic index label type
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets with records
[out]records_countNumber of <name, data> records in the current bucket
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets with records
[out]bucket_indexThe index of the current Bucket
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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 ... &#x0391; &#x0392; &#x0393;

Since :
2.3.2 and 3.0
Remarks:
The obtained label should be released by the caller with the free() function.
Parameters:
[in]indexThe alphabetic index, which contains buckets with records
[out]labelThe default label used for abbreviated bucket between other index characters
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]indexThe alphabetic index, which contains buckets with records
[out]max_label_countThe maximum number of labels
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets
[out]availableA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_ENUM_OUT_OF_SYNCThe 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]indexThe alphabetic index, which contains buckets with records
[out]availableA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_ENUM_OUT_OF_SYNCThe 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]indexThe alphabetic index, which contains buckets with records
[out]labelThe overflow label
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]indexThe alphabetic index, which contains buckets with records
[out]record_countThe 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets with records
    Returns:
    The data pointer of the current record in a current bucket
    Exceptions:
    I18N_ERROR_NONESuccessful
    I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets with records
[out]record_nameThe name of the current index item
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory
I18N_ERROR_INDEX_OUTOFBOUNDSTrying 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]indexThe alphabetic index, which contains buckets with records
[out]labelThe underflow label
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]indexThe alphabetic index, which contains buckets with records
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets with records
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets with records
[in]labelThe new inflow label
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets with records
[in]max_label_countThe new maximum number of labels
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets with records
[in]labelThe new overflow label
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]indexThe alphabetic index, which contains buckets with records
[in]labelThe new underflow label
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter