* This module provides flexible generation of number or date format patterns and helps you format and parse dates/number for any locale.
* The i18n module provides various features based on data from ICU. The following table shows the version of ICU used in each Tizen platform.
* <table>
- * <tr>
- * <td>Tizen 2.3, 2.3.1, 2.4</td>
- * <td>ICU 51</td>
- * <td>CLDR 23</td>
- * <td>Unicode 6.2</td>
- * </tr>
+ * <tr>
+ * <td>Tizen 2.3, 2.3.1, 2.4</td>
+ * <td>ICU 51</td>
+ * <td>CLDR 23</td>
+ * <td>Unicode 6.2</td>
+ * </tr>
+ * <tr>
+ * <td>Tizen 3.0</td>
+ * <td>ICU 57</td>
+ * <td>CLDR 29</td>
+ * <td>Unicode 8.0</td>
+ * </tr>
* </table>
* @section CAPI_BASE_UTILS_I18N_MODULE_HEADER Required Header
* \#include <utils_i18n.h>
/**
* @ingroup CAPI_BASE_UTILS_I18N_MODULE
- * @defgroup CAPI_BASE_UTILS_I18N_ALPHA_IDX_MODULE AlphabeticIndex
- * @brief AlphabeticIndex supports the creation of a UI index appropriate for a given language.
+ * @defgroup CAPI_BASE_UTILS_I18N_ALPHA_IDX_MODULE Alphabetic Index
+ * @brief Alphabetic Index supports the creation of a UI index appropriate for a given language.
* @section CAPI_BASE_UTILS_I18N_ALPHA_IDX_MODULE_HEADER Required Header
* \#include <utils_i18n.h>
*
/**
* @brief Creates an alphabetic index object for the specified locale.
+ * @details 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.
* @remarks The created object should be released by the caller with the
* #i18n_alpha_idx_destroy() function.
+ * @since_tizen 3.0
*
- * @param[in] language The language of the locale
- * @param[in] country The country of the locale
- * @param[out] index The created alphabetic index object
+ * @param[in] language The language of the locale
+ * @param[in] country The country of the locale
+ * @param[out] index The created alphabetic index object
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
*/
int i18n_alpha_idx_create(const char *language, const char *country,
- i18_alpha_idx_h *index);
+ i18n_alpha_idx_h *index);
/**
* @brief Destroys the alphabetic index object.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index to be destroyed
+ * @param[in] index The alphabetic index to be destroyed
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_destroy(i18_alpha_idx_h index);
+int i18n_alpha_idx_destroy(i18n_alpha_idx_h index);
/**
* @brief Adds the index characters from a specified locale to the index.
+ * @details 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_tizen 3.0
*
- * @param[in] index Label will be added to this alphabetic index
- * @param[in] language The language of the locale
- * @param[in] country The country of the locale
+ * @param[in] index Label will be added to this alphabetic index
+ * @param[in] language The language of the locale
+ * @param[in] country The country of the locale
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_add_labels(i18_alpha_idx_h index, const char *language,
+int i18n_alpha_idx_add_labels(i18n_alpha_idx_h index, const char *language,
const char *country);
/**
* @brief Adds the record to the alphabetic index.
- *
- * @param[in] index Record will be added to this alphabetic index
- * @param[in] name The display name for the record
- * @param[in] data An optional pointer to user data associated with this item
+ * @details 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_tizen 3.0
+ *
+ * @param[in] index Record will be added to this alphabetic index
+ * @param[in] name The display name for the record.
+ * The Record will be placed in a bucket based on this name.
+ * @param[in] data An optional pointer to user data associated with this item
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_add_record(i18_alpha_idx_h index, const char *name,
+int i18n_alpha_idx_add_record(i18n_alpha_idx_h index, const char *name,
const void *data);
/**
* @brief Sets the next bucket as current bucket in the index.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets
- * @param[out] success A flag set to @c true if the iteration succeeded,
- * or @c false at the end of iteration.
+ * @param[in] index The alphabetic index, which contains buckets
+ * @param[out] available A flag set to @c true if the next bucket was available,
+ * or @c false if there were no more buckets.
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #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_bucket(i18_alpha_idx_h index, bool *success);
+int i18n_alpha_idx_get_next_bucket(i18n_alpha_idx_h index, bool *available);
/**
* @brief Sets the next record as current record in current bucket of the index.
- * @details When i18n_alpha_idx_next_bucket() is called, record iteration is reset
+ * @details When i18n_alpha_idx_get_next_bucket() is called, record iteration is reset
* to just before the first record in the new bucket.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] success A flag set to @c true if the iteration succeeded,
- * or @c false at the end of iteration.
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] available A flag set to @c true if the next record was available,
+ * or @c false if there were no more records.
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #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(i18_alpha_idx_h index, bool *success);
+int i18n_alpha_idx_get_next_record(i18n_alpha_idx_h index, bool *available);
/**
* @brief Gets the number of <name, data> records in the current bucket.
+ * @details If the current bucket iteration position is before the first
+ * label or after the last, return 0.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] records_count Number of <name, data> records in the current bucket
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] records_count Number of <name, data> records in the current bucket
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_bucket_record_count(i18_alpha_idx_h index, int32_t *records_count);
+int i18n_alpha_idx_get_bucket_record_count(i18n_alpha_idx_h index, int32_t *records_count);
/**
* @brief Gets the name of the label of the current bucket in alphabetic index.
+ * @details 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.
* @remarks The obtained @a label should be released by the caller with the free() function.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets
- * @param[out] label The name of the label of the current bucket
+ * @param[in] index The alphabetic index, which contains buckets
+ * @param[out] label The name of the label of the current bucket
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
*/
-int i18n_alpha_idx_get_bucket_label(i18_alpha_idx_h index, char **label);
+int i18n_alpha_idx_get_bucket_label(i18n_alpha_idx_h index, char **label);
/**
- * @brief Gets the data pointer of the current record in current bucket in alphabetic index.
+ * @brief Gets the data pointer of the current record in a current bucket in alphabetic index.
+ * @details Returns NULL if:
+ * - the current iteration position is before the first item in this Bucket,
+ * or after the last,
+* - the given @a index parameter is invalid.
+ * @remarks The specific error code can be obtained using the get_last_result() method.
+ * Error codes are described in Exceptions section.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] data The data pointer of the current record
+ * @param[in] index The alphabetic index, which contains buckets with records
*
- * @return @c 0 on success, otherwise a negative error value
- * @retval #I18N_ERROR_NONE Successful
- * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
- * @retval #I18N_ERROR_INDEX_OUTOFBOUNDS Trying to access the index that is out of bounds
+ * @return The data pointer of the current record in a current bucket
+ * @exception #I18N_ERROR_NONE Successful
+ * @exception #I18N_ERROR_INVALID_PARAMETER Invalid parameter
*/
-int i18n_alpha_idx_get_record_data(i18_alpha_idx_h index, const void **data);
+const void *i18n_alpha_idx_get_record_data(i18n_alpha_idx_h index);
/**
* @brief Gets the default label used for abbreviated buckets between other index characters.
- * @details For example, consider the labels when Latin and Greek are used: X Y Z ... Α Β
- * Γ.
+ * @details For example, consider the labels when Latin and Greek are used:
+ * X Y Z ... Α Β Γ
* @remarks The obtained @a label should be released by the caller with the free() function.
+ * @since_tizen 3.0
*
* @param[in] index The alphabetic index, which contains buckets with records
* @param[out] label The default label used for abbreviated bucket between other index characters
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
*/
-int i18n_alpha_idx_get_inflow_label(i18_alpha_idx_h index, char **label);
+int i18n_alpha_idx_get_inflow_label(i18n_alpha_idx_h index, char **label);
/**
* @brief Sets the default label used for abbreviated buckets between other index characters.
* @details 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_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[in] label The default label used for abbreviated bucket between other index characters
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] label The new inflow label
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_set_inflow_label(i18_alpha_idx_h index, const char *label);
+int i18n_alpha_idx_set_inflow_label(i18n_alpha_idx_h index, const char *label);
/**
* @brief Gets the special label used for items that sort after the last normal label,
* and that would not otherwise have an appropriate label.
* @remarks The obtained @a label should be released by the caller with the free() function.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] label The special label used for items that sort after the last normal label
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] label The overflow label
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
*/
-int i18n_alpha_idx_get_overflow_label(i18_alpha_idx_h index, char **label);
+int i18n_alpha_idx_get_overflow_label(i18n_alpha_idx_h index, char **label);
/**
* @brief Sets the special label used for items that sort after the last normal label,
* and that would not otherwise have an appropriate label.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[in] label The special label used for items that sort after the last normal label
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] label The new overflow label
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_set_overflow_label(i18_alpha_idx_h index, const char *label);
+int i18n_alpha_idx_set_overflow_label(i18n_alpha_idx_h index, const char *label);
/**
* @brief Gets the special label used for items that sort before the first normal label,
* and that would not otherwise have an appropriate label.
* @remarks The obtained @a label should be released by the caller with the free() function.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] label The special label used for items that sort before the first normal label
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] label The underflow label
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
*/
-int i18n_alpha_idx_get_underflow_label(i18_alpha_idx_h index, char **label);
+int i18n_alpha_idx_get_underflow_label(i18n_alpha_idx_h index, char **label);
/**
* @brief Sets the special label used for items that sort before the first normal label,
* and that would not otherwise have an appropriate label.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[in] label The special label used for items that sort before the first normal label
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] label The new underflow label
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_set_underflow_label(i18_alpha_idx_h index, const char *label);
+int i18n_alpha_idx_set_underflow_label(i18n_alpha_idx_h index, const char *label);
/**
* @brief Gets the limit on the number of labels permitted in the index.
+ * @details The number does not include over, under and inflow labels.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] max_label_count The maximum number of labels
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] max_label_count The maximum number of labels
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_max_label_count(i18_alpha_idx_h index, int32_t *max_label_count);
+int i18n_alpha_idx_get_max_label_count(i18n_alpha_idx_h index, int32_t *max_label_count);
/**
- * @brief Gets the limit on the number of labels permitted in the index.
+ * @brief Sets a limit on the number of labels permitted in the index.
+ * @details 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_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[in] max_label_count The maximum number of labels
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] max_label_count The new maximum number of labels
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_set_max_label_count(i18_alpha_idx_h index, int32_t max_label_count);
+int i18n_alpha_idx_set_max_label_count(i18n_alpha_idx_h index, int32_t max_label_count);
/**
* @brief Remove all records from the index.
* @details The set of Buckets, which define the headings under which records are classified,
* is not altered.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] index The alphabetic index, which contains buckets with records
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_clear_records(i18_alpha_idx_h index);
+int i18n_alpha_idx_clear_records(i18n_alpha_idx_h index);
/**
* @brief Gets the number of labels in this index.
+ * @remarks Note: may trigger lazy index construction.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] bucket_count The number of labels in this index, including any under,
- * over or inflow labels
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] bucket_count The number of labels in this index, including any under,
+ * over or inflow labels
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_bucket_count(i18_alpha_idx_h index, int32_t *bucket_count);
+int i18n_alpha_idx_get_bucket_count(i18n_alpha_idx_h index, int32_t *bucket_count);
/**
* @brief Gets the total number of records in this index, that is, the number of
* <name, data> pairs added.
+ * @since_tizen 3.0
*
* @param[in] index The alphabetic index, which contains buckets with records
* @param[out] record_count The number of records in this index, that is,
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_record_count(i18_alpha_idx_h index, int32_t *record_count);
+int i18n_alpha_idx_get_record_count(i18n_alpha_idx_h index, int32_t *record_count);
/**
* @brief Given the name of a record, returns the zero-based index of the bucket
* in which the item should appear.
+ * @details 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_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[in] item_name The name whose bucket position in the index is to be determined
- * @param[out] bucket_index The bucket number for this name
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] item_name The name whose bucket position in the index is to be determined
+ * @param[out] bucket_index The bucket number for this name
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_bucket_index(i18_alpha_idx_h index, const char *item_name, int32_t *bucket_index);
+int i18n_alpha_idx_get_bucket_index(i18n_alpha_idx_h index, const char *item_name, int32_t *bucket_index);
/**
* @brief Gets the zero based index of the current bucket of this index.
+ * @details Sets the variable pointed by the @a bucket_index to -1 if no iteration
+ * is in process.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] bucket_index The number of current bucket
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] bucket_index The index of the current Bucket
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_current_bucket_index(i18_alpha_idx_h index, int32_t *bucket_index);
+int i18n_alpha_idx_get_current_bucket_index(i18n_alpha_idx_h index, int32_t *bucket_index);
/**
- * @brief Gets the type of the label for the current bucket.
+ * @brief Gets the type of the label for the current Bucket
+ * (selected by the iteration over Buckets).
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] type The alphabetic index label type
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] type The alphabetic index label type
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_bucket_label_type(i18_alpha_idx_h index,
- i18_alpha_idx_label_type_e *type);
+int i18n_alpha_idx_get_bucket_label_type(i18n_alpha_idx_h index,
+ i18n_alpha_idx_label_type_e *type);
/**
* @brief Gets the name of the current record.
- * @details Returns NULL if the Record iteration position is before first or after the last.
+ * @details If the Record iteration position is before the first or after the last record,
+ * sets the string pointed by the @a record_name parameter to NULL and returns
+ * the #I18N_ERROR_INDEX_OUTOFBOUNDS error code.
* @remarks The obtained @a record_name should be released by the caller with the free() function.
+ * @since_tizen 3.0
*
* @param[in] index The alphabetic index, which contains buckets with records
* @param[out] record_name The name of the current index item
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
* @retval #I18N_ERROR_INDEX_OUTOFBOUNDS Trying to access the index that is out of bounds
*/
-int i18n_alpha_idx_get_record_name(i18_alpha_idx_h index, char **record_name);
+int i18n_alpha_idx_get_record_name(i18n_alpha_idx_h index, char **record_name);
/**
* @brief Resets the bucket iteration for this index.
- * @details The next call to i18n_alpha_idx_next_bucket() will restart the iteration at the first label.
+ * @details The next call to i18n_alpha_idx_get_next_bucket() will restart the iteration at the first label.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] index The alphabetic index, which contains buckets with records
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_reset_bucket_iter(i18_alpha_idx_h index);
+int i18n_alpha_idx_reset_bucket_iter(i18n_alpha_idx_h index);
/**
- * @brief Resets the record iteration for this index.
- * @details The next call to i18n_alpha_idx_next_record() will restart the iteration at the first label.
+ * @brief Resets the record iteration for this index to before the first Record in the current Bucket.
+ * @details The next call to i18n_alpha_idx_get_next_record() will restart the iteration at the first label.
+ * @since_tizen 3.0
*
- * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] index The alphabetic index, which contains buckets with records
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_reset_record_iter(i18_alpha_idx_h index);
+int i18n_alpha_idx_reset_record_iter(i18n_alpha_idx_h index);
/**
* @}
* @brief The Alphabetic index handle.
* @since_tizen 3.0
*/
-typedef void *i18_alpha_idx_h;
+typedef void *i18n_alpha_idx_h;
/**
* @brief Enumeration for alphabetic index label types.
/**
* Normal Label, typically the starting letter of the names in the bucket with this label.
*/
- I18_ALPHA_IDX_NORMAL,
+ I18N_ALPHA_IDX_NORMAL,
/**
* Underflow Label.
* The bucket with this label contains names in scripts that sort before any
* of the bucket labels in this index.
*/
- I18_ALPHA_IDX_UNDERFLOW,
+ I18N_ALPHA_IDX_UNDERFLOW,
/**
* Inflow Label.
* an index contains normal labels for multiple scripts, and skips other
* scripts that sort between some of the included scripts.
*/
- I18_ALPHA_IDX_INFLOW,
+ I18N_ALPHA_IDX_INFLOW,
/**
* Overflow Label.
* The bucket with this label contains names in scripts that sort after
* all of the bucket labels in this index.
*/
- I18_ALPHA_IDX_OVERFLOW,
-} i18_alpha_idx_label_type_e;
+ I18N_ALPHA_IDX_OVERFLOW,
+} i18n_alpha_idx_label_type_e;
/**
* @brief A simple type used by Format module and its submodules to identify fields in formatted output.
* This module provides flexible generation of number or date format patterns and helps you format and parse dates/number for any locale.
* The i18n module provides various features based on data from ICU. The following table shows the version of ICU used in each Tizen platform.
* <table>
- * <tr>
- * <td>Tizen 2.3, 2.3.1, 2.4</td>
- * <td>ICU 51</td>
- * <td>CLDR 23</td>
- * <td>Unicode 6.2</td>
- * </tr>
+ * <tr>
+ * <td>Tizen 2.3.1, 2.3.2</td>
+ * <td>ICU 51</td>
+ * <td>CLDR 23</td>
+ * <td>Unicode 6.2</td>
+ * </tr>
+ * <tr>
+ * <td>Tizen 3.0</td>
+ * <td>ICU 57</td>
+ * <td>CLDR 29</td>
+ * <td>Unicode 8.0</td>
+ * </tr>
* </table>
* @section CAPI_BASE_UTILS_I18N_MODULE_HEADER Required Header
* \#include <utils_i18n.h>
/**
* @ingroup CAPI_BASE_UTILS_I18N_MODULE
- * @defgroup CAPI_BASE_UTILS_I18N_ALPHA_IDX_MODULE AlphabeticIndex
- * @brief AlphabeticIndex supports the creation of a UI index appropriate for a given language.
+ * @defgroup CAPI_BASE_UTILS_I18N_ALPHA_IDX_MODULE Alphabetic Index
+ * @brief Alphabetic Index supports the creation of a UI index appropriate for a given language.
* @section CAPI_BASE_UTILS_I18N_ALPHA_IDX_MODULE_HEADER Required Header
* \#include <utils_i18n.h>
*
/**
* @brief Creates an alphabetic index object for the specified locale.
+ * @details 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.
* @remarks The created object should be released by the caller with the
* #i18n_alpha_idx_destroy() function.
+ * @since_tizen 2.3.2
*
- * @param[in] language The language of the locale
- * @param[in] country The country of the locale
- * @param[out] index The created alphabetic index object
+ * @param[in] language The language of the locale
+ * @param[in] country The country of the locale
+ * @param[out] index The created alphabetic index object
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
*/
int i18n_alpha_idx_create(const char *language, const char *country,
- i18_alpha_idx_h *index);
+ i18n_alpha_idx_h *index);
/**
* @brief Destroys the alphabetic index object.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index to be destroyed
+ * @param[in] index The alphabetic index to be destroyed
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_destroy(i18_alpha_idx_h index);
+int i18n_alpha_idx_destroy(i18n_alpha_idx_h index);
/**
* @brief Adds the index characters from a specified locale to the index.
+ * @details 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_tizen 2.3.2
*
- * @param[in] index Label will be added to this alphabetic index
- * @param[in] language The language of the locale
- * @param[in] country The country of the locale
+ * @param[in] index Label will be added to this alphabetic index
+ * @param[in] language The language of the locale
+ * @param[in] country The country of the locale
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_add_labels(i18_alpha_idx_h index, const char *language,
+int i18n_alpha_idx_add_labels(i18n_alpha_idx_h index, const char *language,
const char *country);
/**
* @brief Adds the record to the alphabetic index.
- *
- * @param[in] index Record will be added to this alphabetic index
- * @param[in] name The display name for the record
- * @param[in] data An optional pointer to user data associated with this item
+ * @details 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_tizen 2.3.2
+ *
+ * @param[in] index Record will be added to this alphabetic index
+ * @param[in] name The display name for the record.
+ * The Record will be placed in a bucket based on this name.
+ * @param[in] data An optional pointer to user data associated with this item
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_add_record(i18_alpha_idx_h index, const char *name,
+int i18n_alpha_idx_add_record(i18n_alpha_idx_h index, const char *name,
const void *data);
/**
* @brief Sets the next bucket as current bucket in the index.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets
- * @param[out] success A flag set to @c true if the iteration succeeded,
- * or @c false at the end of iteration.
+ * @param[in] index The alphabetic index, which contains buckets
+ * @param[out] available A flag set to @c true if the next bucket was available,
+ * or @c false if there were no more buckets.
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #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_bucket(i18_alpha_idx_h index, bool *success);
+int i18n_alpha_idx_get_next_bucket(i18n_alpha_idx_h index, bool *available);
/**
* @brief Sets the next record as current record in current bucket of the index.
- * @details When i18n_alpha_idx_next_bucket() is called, record iteration is reset
+ * @details When i18n_alpha_idx_get_next_bucket() is called, record iteration is reset
* to just before the first record in the new bucket.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] success A flag set to @c true if the iteration succeeded,
- * or @c false at the end of iteration.
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] available A flag set to @c true if the next record was available,
+ * or @c false if there were no more records.
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #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(i18_alpha_idx_h index, bool *success);
+int i18n_alpha_idx_get_next_record(i18n_alpha_idx_h index, bool *available);
/**
* @brief Gets the number of <name, data> records in the current bucket.
+ * @details If the current bucket iteration position is before the first
+ * label or after the last, return 0.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] records_count Number of <name, data> records in the current bucket
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] records_count Number of <name, data> records in the current bucket
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_bucket_record_count(i18_alpha_idx_h index, int32_t *records_count);
+int i18n_alpha_idx_get_bucket_record_count(i18n_alpha_idx_h index, int32_t *records_count);
/**
* @brief Gets the name of the label of the current bucket in alphabetic index.
+ * @details 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.
* @remarks The obtained @a label should be released by the caller with the free() function.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets
- * @param[out] label The name of the label of the current bucket
+ * @param[in] index The alphabetic index, which contains buckets
+ * @param[out] label The name of the label of the current bucket
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
*/
-int i18n_alpha_idx_get_bucket_label(i18_alpha_idx_h index, char **label);
+int i18n_alpha_idx_get_bucket_label(i18n_alpha_idx_h index, char **label);
/**
- * @brief Gets the data pointer of the current record in current bucket in alphabetic index.
+ * @brief Gets the data pointer of the current record in a current bucket in alphabetic index.
+ * @details Returns NULL if:
+ * - the current iteration position is before the first item in this Bucket,
+ * or after the last,
+* - the given @a index parameter is invalid.
+ * @remarks The specific error code can be obtained using the get_last_result() method.
+ * Error codes are described in Exceptions section.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] data The data pointer of the current record
+ * @param[in] index The alphabetic index, which contains buckets with records
*
- * @return @c 0 on success, otherwise a negative error value
- * @retval #I18N_ERROR_NONE Successful
- * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
- * @retval #I18N_ERROR_INDEX_OUTOFBOUNDS Trying to access the index that is out of bounds
+ * @return The data pointer of the current record in a current bucket
+ * @exception #I18N_ERROR_NONE Successful
+ * @exception #I18N_ERROR_INVALID_PARAMETER Invalid parameter
*/
-int i18n_alpha_idx_get_record_data(i18_alpha_idx_h index, const void **data);
+const void *i18n_alpha_idx_get_record_data(i18n_alpha_idx_h index);
/**
* @brief Gets the default label used for abbreviated buckets between other index characters.
- * @details For example, consider the labels when Latin and Greek are used: X Y Z ... Α Β
- * Γ.
+ * @details For example, consider the labels when Latin and Greek are used:
+ * X Y Z ... Α Β Γ
* @remarks The obtained @a label should be released by the caller with the free() function.
+ * @since_tizen 2.3.2
*
* @param[in] index The alphabetic index, which contains buckets with records
* @param[out] label The default label used for abbreviated bucket between other index characters
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
*/
-int i18n_alpha_idx_get_inflow_label(i18_alpha_idx_h index, char **label);
+int i18n_alpha_idx_get_inflow_label(i18n_alpha_idx_h index, char **label);
/**
* @brief Sets the default label used for abbreviated buckets between other index characters.
* @details 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_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[in] label The default label used for abbreviated bucket between other index characters
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] label The new inflow label
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_set_inflow_label(i18_alpha_idx_h index, const char *label);
+int i18n_alpha_idx_set_inflow_label(i18n_alpha_idx_h index, const char *label);
/**
* @brief Gets the special label used for items that sort after the last normal label,
* and that would not otherwise have an appropriate label.
* @remarks The obtained @a label should be released by the caller with the free() function.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] label The special label used for items that sort after the last normal label
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] label The overflow label
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
*/
-int i18n_alpha_idx_get_overflow_label(i18_alpha_idx_h index, char **label);
+int i18n_alpha_idx_get_overflow_label(i18n_alpha_idx_h index, char **label);
/**
* @brief Sets the special label used for items that sort after the last normal label,
* and that would not otherwise have an appropriate label.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[in] label The special label used for items that sort after the last normal label
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] label The new overflow label
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_set_overflow_label(i18_alpha_idx_h index, const char *label);
+int i18n_alpha_idx_set_overflow_label(i18n_alpha_idx_h index, const char *label);
/**
* @brief Gets the special label used for items that sort before the first normal label,
* and that would not otherwise have an appropriate label.
* @remarks The obtained @a label should be released by the caller with the free() function.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] label The special label used for items that sort before the first normal label
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] label The underflow label
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
*/
-int i18n_alpha_idx_get_underflow_label(i18_alpha_idx_h index, char **label);
+int i18n_alpha_idx_get_underflow_label(i18n_alpha_idx_h index, char **label);
/**
* @brief Sets the special label used for items that sort before the first normal label,
* and that would not otherwise have an appropriate label.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[in] label The special label used for items that sort before the first normal label
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] label The new underflow label
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_set_underflow_label(i18_alpha_idx_h index, const char *label);
+int i18n_alpha_idx_set_underflow_label(i18n_alpha_idx_h index, const char *label);
/**
* @brief Gets the limit on the number of labels permitted in the index.
+ * @details The number does not include over, under and inflow labels.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] max_label_count The maximum number of labels
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] max_label_count The maximum number of labels
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_max_label_count(i18_alpha_idx_h index, int32_t *max_label_count);
+int i18n_alpha_idx_get_max_label_count(i18n_alpha_idx_h index, int32_t *max_label_count);
/**
- * @brief Gets the limit on the number of labels permitted in the index.
+ * @brief Sets a limit on the number of labels permitted in the index.
+ * @details 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_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[in] max_label_count The maximum number of labels
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] max_label_count The new maximum number of labels
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_set_max_label_count(i18_alpha_idx_h index, int32_t max_label_count);
+int i18n_alpha_idx_set_max_label_count(i18n_alpha_idx_h index, int32_t max_label_count);
/**
* @brief Remove all records from the index.
* @details The set of Buckets, which define the headings under which records are classified,
* is not altered.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] index The alphabetic index, which contains buckets with records
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_clear_records(i18_alpha_idx_h index);
+int i18n_alpha_idx_clear_records(i18n_alpha_idx_h index);
/**
* @brief Gets the number of labels in this index.
+ * @remarks Note: may trigger lazy index construction.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] bucket_count The number of labels in this index, including any under,
- * over or inflow labels
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] bucket_count The number of labels in this index, including any under,
+ * over or inflow labels
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_bucket_count(i18_alpha_idx_h index, int32_t *bucket_count);
+int i18n_alpha_idx_get_bucket_count(i18n_alpha_idx_h index, int32_t *bucket_count);
/**
* @brief Gets the total number of records in this index, that is, the number of
* <name, data> pairs added.
+ * @since_tizen 2.3.2
*
* @param[in] index The alphabetic index, which contains buckets with records
* @param[out] record_count The number of records in this index, that is,
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_record_count(i18_alpha_idx_h index, int32_t *record_count);
+int i18n_alpha_idx_get_record_count(i18n_alpha_idx_h index, int32_t *record_count);
/**
* @brief Given the name of a record, returns the zero-based index of the bucket
* in which the item should appear.
+ * @details 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_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[in] item_name The name whose bucket position in the index is to be determined
- * @param[out] bucket_index The bucket number for this name
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] item_name The name whose bucket position in the index is to be determined
+ * @param[out] bucket_index The bucket number for this name
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_bucket_index(i18_alpha_idx_h index, const char *item_name, int32_t *bucket_index);
+int i18n_alpha_idx_get_bucket_index(i18n_alpha_idx_h index, const char *item_name, int32_t *bucket_index);
/**
* @brief Gets the zero based index of the current bucket of this index.
+ * @details Sets the variable pointed by the @a bucket_index to -1 if no iteration
+ * is in process.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] bucket_index The number of current bucket
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] bucket_index The index of the current Bucket
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_current_bucket_index(i18_alpha_idx_h index, int32_t *bucket_index);
+int i18n_alpha_idx_get_current_bucket_index(i18n_alpha_idx_h index, int32_t *bucket_index);
/**
- * @brief Gets the type of the label for the current bucket.
+ * @brief Gets the type of the label for the current Bucket
+ * (selected by the iteration over Buckets).
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
- * @param[out] type The alphabetic index label type
+ * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[out] type The alphabetic index label type
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_get_bucket_label_type(i18_alpha_idx_h index,
- i18_alpha_idx_label_type_e *type);
+int i18n_alpha_idx_get_bucket_label_type(i18n_alpha_idx_h index,
+ i18n_alpha_idx_label_type_e *type);
/**
* @brief Gets the name of the current record.
- * @details Returns NULL if the Record iteration position is before first or after the last.
+ * @details If the Record iteration position is before the first or after the last record,
+ * sets the string pointed by the @a record_name parameter to NULL and returns
+ * the #I18N_ERROR_INDEX_OUTOFBOUNDS error code.
* @remarks The obtained @a record_name should be released by the caller with the free() function.
+ * @since_tizen 2.3.2
*
* @param[in] index The alphabetic index, which contains buckets with records
* @param[out] record_name The name of the current index item
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
* @retval #I18N_ERROR_INDEX_OUTOFBOUNDS Trying to access the index that is out of bounds
*/
-int i18n_alpha_idx_get_record_name(i18_alpha_idx_h index, char **record_name);
+int i18n_alpha_idx_get_record_name(i18n_alpha_idx_h index, char **record_name);
/**
* @brief Resets the bucket iteration for this index.
- * @details The next call to i18n_alpha_idx_next_bucket() will restart the iteration at the first label.
+ * @details The next call to i18n_alpha_idx_get_next_bucket() will restart the iteration at the first label.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] index The alphabetic index, which contains buckets with records
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_reset_bucket_iter(i18_alpha_idx_h index);
+int i18n_alpha_idx_reset_bucket_iter(i18n_alpha_idx_h index);
/**
- * @brief Resets the record iteration for this index.
- * @details The next call to i18n_alpha_idx_next_record() will restart the iteration at the first label.
+ * @brief Resets the record iteration for this index to before the first Record in the current Bucket.
+ * @details The next call to i18n_alpha_idx_get_next_record() will restart the iteration at the first label.
+ * @since_tizen 2.3.2
*
- * @param[in] index The alphabetic index, which contains buckets with records
+ * @param[in] index The alphabetic index, which contains buckets with records
*
* @return @c 0 on success, otherwise a negative error value
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*/
-int i18n_alpha_idx_reset_record_iter(i18_alpha_idx_h index);
+int i18n_alpha_idx_reset_record_iter(i18n_alpha_idx_h index);
/**
* @}
* @brief The Alphabetic index handle.
* @since_tizen 2.3.2
*/
-typedef void *i18_alpha_idx_h;
+typedef void *i18n_alpha_idx_h;
/**
* @brief Enumeration for alphabetic index label types.
/**
* Normal Label, typically the starting letter of the names in the bucket with this label.
*/
- I18_ALPHA_IDX_NORMAL,
+ I18N_ALPHA_IDX_NORMAL,
/**
* Underflow Label.
* The bucket with this label contains names in scripts that sort before any
* of the bucket labels in this index.
*/
- I18_ALPHA_IDX_UNDERFLOW,
+ I18N_ALPHA_IDX_UNDERFLOW,
/**
* Inflow Label.
* an index contains normal labels for multiple scripts, and skips other
* scripts that sort between some of the included scripts.
*/
- I18_ALPHA_IDX_INFLOW,
+ I18N_ALPHA_IDX_INFLOW,
/**
* Overflow Label.
* The bucket with this label contains names in scripts that sort after
* all of the bucket labels in this index.
*/
- I18_ALPHA_IDX_OVERFLOW,
-} i18_alpha_idx_label_type_e;
+ I18N_ALPHA_IDX_OVERFLOW,
+} i18n_alpha_idx_label_type_e;
/**
* @brief A simple class used by Format and its subclasses to identify fields in formatted output
#include <utils_i18n_alpha_idx.h>
#include <utils_i18n_private.h>
+#include <malloc.h>
#include <string.h>
#include <unicode/locid.h>
#include <unicode/alphaindex.h>
int i18n_alpha_idx_create(const char *language, const char *country,
- i18_alpha_idx_h *index)
+ i18n_alpha_idx_h *index)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_destroy(i18_alpha_idx_h index)
+int i18n_alpha_idx_destroy(i18n_alpha_idx_h index)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
return I18N_ERROR_NONE;
}
-int i18n_alpha_idx_add_labels(i18_alpha_idx_h index,
+int i18n_alpha_idx_add_labels(i18n_alpha_idx_h index,
const char *language, const char *country)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_add_record(i18_alpha_idx_h index, const char *name,
+int i18n_alpha_idx_add_record(i18n_alpha_idx_h index, const char *name,
const void *data)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
+ retv_if(name == NULL, I18N_ERROR_INVALID_PARAMETER);
const UnicodeString _name(name);
UErrorCode status = U_ZERO_ERROR;
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_get_next_bucket(i18_alpha_idx_h index, bool *success)
+int i18n_alpha_idx_get_next_bucket(i18n_alpha_idx_h index, bool *available)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
UErrorCode status = U_ZERO_ERROR;
- if(success != NULL)
- *success = ((AlphabeticIndex *) index)->nextBucket(status);
+ if(available != NULL)
+ *available = ((AlphabeticIndex *) index)->nextBucket(status);
else
((AlphabeticIndex *) index)->nextBucket(status);
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_get_next_record(i18_alpha_idx_h index, bool *success)
+int i18n_alpha_idx_get_next_record(i18n_alpha_idx_h index, bool *available)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
UErrorCode status = U_ZERO_ERROR;
- if(success != NULL)
- *success = ((AlphabeticIndex *) index)->nextRecord(status);
+ if(available != NULL)
+ *available = ((AlphabeticIndex *) index)->nextRecord(status);
else
((AlphabeticIndex *) index)->nextRecord(status);
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_get_bucket_record_count(i18_alpha_idx_h index,
+int i18n_alpha_idx_get_bucket_record_count(i18n_alpha_idx_h index,
int32_t *records_count)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
return I18N_ERROR_NONE;
}
-int i18n_alpha_idx_get_bucket_label(i18_alpha_idx_h index,
+int i18n_alpha_idx_get_bucket_label(i18n_alpha_idx_h index,
char **label)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
_label.toUTF8String(_label_string);
*label = strdup(_label_string.c_str());
+ retv_if(*label == NULL, I18N_ERROR_OUT_OF_MEMORY);
return I18N_ERROR_NONE;
}
-int i18n_alpha_idx_get_record_data(i18_alpha_idx_h index,
- const void **data)
+const void *i18n_alpha_idx_get_record_data(i18n_alpha_idx_h index)
{
- retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
- retv_if(data == NULL, I18N_ERROR_INVALID_PARAMETER);
-
- *data = ((AlphabeticIndex *) index)->getRecordData();
- retv_if(*data == NULL, I18N_ERROR_INDEX_OUTOFBOUNDS);
+ if (index == NULL) {
+ set_last_result(I18N_ERROR_INVALID_PARAMETER);
+ return NULL;
+ }
- return I18N_ERROR_NONE;
+ return ((AlphabeticIndex *) index)->getRecordData();
}
-int i18n_alpha_idx_get_inflow_label(i18_alpha_idx_h index,
+int i18n_alpha_idx_get_inflow_label(i18n_alpha_idx_h index,
char **label)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
_label.toUTF8String(_label_string);
*label = strdup(_label_string.c_str());
+ retv_if(*label == NULL, I18N_ERROR_OUT_OF_MEMORY);
return I18N_ERROR_NONE;
}
-int i18n_alpha_idx_set_inflow_label(i18_alpha_idx_h index,
+int i18n_alpha_idx_set_inflow_label(i18n_alpha_idx_h index,
const char *label)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_get_overflow_label(i18_alpha_idx_h index,
+int i18n_alpha_idx_get_overflow_label(i18n_alpha_idx_h index,
char **label)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
overflow_label.toUTF8String(_label_string);
*label = strdup(_label_string.c_str());
+ retv_if(*label == NULL, I18N_ERROR_OUT_OF_MEMORY);
return I18N_ERROR_NONE;
}
-int i18n_alpha_idx_set_overflow_label(i18_alpha_idx_h index,
+int i18n_alpha_idx_set_overflow_label(i18n_alpha_idx_h index,
const char *label)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_get_underflow_label(i18_alpha_idx_h index,
+int i18n_alpha_idx_get_underflow_label(i18n_alpha_idx_h index,
char **label)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
retv_if(label == NULL, I18N_ERROR_INVALID_PARAMETER);
- const UnicodeString overflow_label = ((AlphabeticIndex *) index)->getOverflowLabel();
+ const UnicodeString overflow_label = ((AlphabeticIndex *) index)->getUnderflowLabel();
std::string _label_string;
overflow_label.toUTF8String(_label_string);
*label = strdup(_label_string.c_str());
+ retv_if(*label == NULL, I18N_ERROR_OUT_OF_MEMORY);
return I18N_ERROR_NONE;
}
-int i18n_alpha_idx_set_underflow_label(i18_alpha_idx_h index,
+int i18n_alpha_idx_set_underflow_label(i18n_alpha_idx_h index,
const char *label)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
const UnicodeString underflow_label(label);
UErrorCode status = U_ZERO_ERROR;
- ((AlphabeticIndex *) index)->setOverflowLabel(underflow_label, status);
+ ((AlphabeticIndex *) index)->setUnderflowLabel(underflow_label, status);
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_get_max_label_count(i18_alpha_idx_h index,
+int i18n_alpha_idx_get_max_label_count(i18n_alpha_idx_h index,
int32_t *max_label_count)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
return I18N_ERROR_NONE;
}
-int i18n_alpha_idx_set_max_label_count(i18_alpha_idx_h index,
+int i18n_alpha_idx_set_max_label_count(i18n_alpha_idx_h index,
int32_t max_label_count)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_clear_records(i18_alpha_idx_h index)
+int i18n_alpha_idx_clear_records(i18n_alpha_idx_h index)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_get_bucket_count(i18_alpha_idx_h index,
+int i18n_alpha_idx_get_bucket_count(i18n_alpha_idx_h index,
int32_t *bucket_count)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_get_record_count(i18_alpha_idx_h index,
+int i18n_alpha_idx_get_record_count(i18n_alpha_idx_h index,
int32_t *record_count)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_get_bucket_index(i18_alpha_idx_h index,
+int i18n_alpha_idx_get_bucket_index(i18n_alpha_idx_h index,
const char *item_name,
int32_t *bucket_index)
{
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_get_current_bucket_index(i18_alpha_idx_h index,
+int i18n_alpha_idx_get_current_bucket_index(i18n_alpha_idx_h index,
int32_t *bucket_index)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
return I18N_ERROR_NONE;
}
-int i18n_alpha_idx_get_bucket_label_type(i18_alpha_idx_h index,
- i18_alpha_idx_label_type_e *type)
+int i18n_alpha_idx_get_bucket_label_type(i18n_alpha_idx_h index,
+ i18n_alpha_idx_label_type_e *type)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
retv_if(type == NULL, I18N_ERROR_INVALID_PARAMETER);
- *type = (i18_alpha_idx_label_type_e) ((AlphabeticIndex *) index)->getBucketLabelType();
+ *type = (i18n_alpha_idx_label_type_e) ((AlphabeticIndex *) index)->getBucketLabelType();
return I18N_ERROR_NONE;
}
-int i18n_alpha_idx_get_record_name(i18_alpha_idx_h index,
+int i18n_alpha_idx_get_record_name(i18n_alpha_idx_h index,
char **record_name)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
_record_name.toUTF8String(_record_name_string);
*record_name = strdup(_record_name_string.c_str());
+ retv_if(*record_name == NULL, I18N_ERROR_OUT_OF_MEMORY);
if(_record_name.isEmpty()) {
+ free(*record_name);
+ *record_name = NULL;
return I18N_ERROR_INDEX_OUTOFBOUNDS;
}
return I18N_ERROR_NONE;
}
-int i18n_alpha_idx_reset_bucket_iter(i18_alpha_idx_h index)
+int i18n_alpha_idx_reset_bucket_iter(i18n_alpha_idx_h index)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
return _i18n_error_mapping(status);
}
-int i18n_alpha_idx_reset_record_iter(i18_alpha_idx_h index)
+int i18n_alpha_idx_reset_record_iter(i18n_alpha_idx_h index)
{
retv_if(index == NULL, I18N_ERROR_INVALID_PARAMETER);
projects / platform / core / api / base-utils.git / commitdiff