Tizen Native API
5.5
|
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
Enumeration for alphabetic index label types.
- Since :
- 3.0
- Enumerator:
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, orfalse
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, orfalse
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