From: Rafal Szczekutek Date: Wed, 20 Jul 2016 11:51:19 +0000 (+0200) Subject: [Base-utils][AlphabeticIndex] Documentation and naming fixes X-Git-Tag: accepted/tizen/common/20160817.133137~2^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F61%2F76861%2F12;p=platform%2Fcore%2Fapi%2Fbase-utils.git [Base-utils][AlphabeticIndex] Documentation and naming fixes Change-Id: I3cc6fe21f88adfddb88bfef1513a0d699c603107 Signed-off-by: Rafał Szczekutek --- diff --git a/src/include/mobile/utils_i18n.h b/src/include/mobile/utils_i18n.h index 335d79d..63d9a12 100644 --- a/src/include/mobile/utils_i18n.h +++ b/src/include/mobile/utils_i18n.h @@ -58,12 +58,18 @@ extern "C" { * 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. * - * - * - * - * - * - * + * + * + * + * + * + * + * + * + * + * + * + * *
Tizen 2.3, 2.3.1, 2.4ICU 51CLDR 23Unicode 6.2
Tizen 2.3, 2.3.1, 2.4ICU 51CLDR 23Unicode 6.2
Tizen 3.0ICU 57CLDR 29Unicode 8.0
* @section CAPI_BASE_UTILS_I18N_MODULE_HEADER Required Header * \#include diff --git a/src/include/mobile/utils_i18n_alpha_idx.h b/src/include/mobile/utils_i18n_alpha_idx.h index 5131a37..2b9bd5c 100644 --- a/src/include/mobile/utils_i18n_alpha_idx.h +++ b/src/include/mobile/utils_i18n_alpha_idx.h @@ -31,8 +31,8 @@ extern "C" { /** * @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 * @@ -57,12 +57,18 @@ extern "C" { /** * @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 @@ -70,118 +76,152 @@ extern "C" { * @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 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 records in the current bucket + * @param[in] index The alphabetic index, which contains buckets with records + * @param[out] records_count Number of 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 @@ -189,131 +229,150 @@ int i18n_alpha_idx_get_record_data(i18_alpha_idx_h index, const void **data); * @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 * 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, @@ -324,51 +383,63 @@ int i18n_alpha_idx_get_bucket_count(i18_alpha_idx_h index, int32_t *bucket_count * @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 @@ -376,33 +447,36 @@ int i18n_alpha_idx_get_bucket_label_type(i18_alpha_idx_h index, * @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); /** * @} diff --git a/src/include/mobile/utils_i18n_types.h b/src/include/mobile/utils_i18n_types.h index d8ee211..f20c267 100644 --- a/src/include/mobile/utils_i18n_types.h +++ b/src/include/mobile/utils_i18n_types.h @@ -2910,7 +2910,7 @@ typedef enum { * @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. @@ -2922,7 +2922,7 @@ typedef enum { /** * 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. @@ -2930,7 +2930,7 @@ typedef enum { * 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. @@ -2940,7 +2940,7 @@ typedef enum { * 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. @@ -2948,8 +2948,8 @@ typedef enum { * 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. diff --git a/src/include/wearable/utils_i18n.h b/src/include/wearable/utils_i18n.h index 39f12d6..1f2441f 100644 --- a/src/include/wearable/utils_i18n.h +++ b/src/include/wearable/utils_i18n.h @@ -58,12 +58,18 @@ extern "C" { * 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. * - * - * - * - * - * - * + * + * + * + * + * + * + * + * + * + * + * + * *
Tizen 2.3, 2.3.1, 2.4ICU 51CLDR 23Unicode 6.2
Tizen 2.3.1, 2.3.2ICU 51CLDR 23Unicode 6.2
Tizen 3.0ICU 57CLDR 29Unicode 8.0
* @section CAPI_BASE_UTILS_I18N_MODULE_HEADER Required Header * \#include diff --git a/src/include/wearable/utils_i18n_alpha_idx.h b/src/include/wearable/utils_i18n_alpha_idx.h index 5131a37..4cb36ce 100644 --- a/src/include/wearable/utils_i18n_alpha_idx.h +++ b/src/include/wearable/utils_i18n_alpha_idx.h @@ -31,8 +31,8 @@ extern "C" { /** * @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 * @@ -57,12 +57,18 @@ extern "C" { /** * @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 @@ -70,118 +76,152 @@ extern "C" { * @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 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 records in the current bucket + * @param[in] index The alphabetic index, which contains buckets with records + * @param[out] records_count Number of 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 @@ -189,131 +229,150 @@ int i18n_alpha_idx_get_record_data(i18_alpha_idx_h index, const void **data); * @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 * 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, @@ -324,51 +383,63 @@ int i18n_alpha_idx_get_bucket_count(i18_alpha_idx_h index, int32_t *bucket_count * @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 @@ -376,33 +447,36 @@ int i18n_alpha_idx_get_bucket_label_type(i18_alpha_idx_h index, * @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); /** * @} diff --git a/src/include/wearable/utils_i18n_types.h b/src/include/wearable/utils_i18n_types.h index 2e0a48e..d715d11 100644 --- a/src/include/wearable/utils_i18n_types.h +++ b/src/include/wearable/utils_i18n_types.h @@ -2909,7 +2909,7 @@ typedef enum { * @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. @@ -2921,7 +2921,7 @@ typedef enum { /** * 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. @@ -2929,7 +2929,7 @@ typedef enum { * 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. @@ -2939,7 +2939,7 @@ typedef enum { * 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. @@ -2947,8 +2947,8 @@ typedef enum { * 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 diff --git a/src/utils_i18n_alpha_idx.cpp b/src/utils_i18n_alpha_idx.cpp index e0e8831..d26dd7b 100644 --- a/src/utils_i18n_alpha_idx.cpp +++ b/src/utils_i18n_alpha_idx.cpp @@ -17,12 +17,13 @@ #include #include +#include #include #include #include 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); @@ -35,7 +36,7 @@ int i18n_alpha_idx_create(const char *language, const char *country, 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); @@ -44,7 +45,7 @@ int i18n_alpha_idx_destroy(i18_alpha_idx_h index) 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); @@ -57,10 +58,11 @@ int i18n_alpha_idx_add_labels(i18_alpha_idx_h index, 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; @@ -70,35 +72,35 @@ int i18n_alpha_idx_add_record(i18_alpha_idx_h index, const char *name, 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); @@ -109,7 +111,7 @@ int i18n_alpha_idx_get_bucket_record_count(i18_alpha_idx_h index, 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); @@ -121,23 +123,22 @@ int i18n_alpha_idx_get_bucket_label(i18_alpha_idx_h index, _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); @@ -149,11 +150,12 @@ int i18n_alpha_idx_get_inflow_label(i18_alpha_idx_h index, _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); @@ -167,7 +169,7 @@ int i18n_alpha_idx_set_inflow_label(i18_alpha_idx_h index, 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); @@ -179,11 +181,12 @@ int i18n_alpha_idx_get_overflow_label(i18_alpha_idx_h index, 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); @@ -197,23 +200,24 @@ int i18n_alpha_idx_set_overflow_label(i18_alpha_idx_h index, 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); @@ -222,12 +226,12 @@ int i18n_alpha_idx_set_underflow_label(i18_alpha_idx_h index, 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); @@ -238,7 +242,7 @@ int i18n_alpha_idx_get_max_label_count(i18_alpha_idx_h index, 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); @@ -250,7 +254,7 @@ int i18n_alpha_idx_set_max_label_count(i18_alpha_idx_h index, 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); @@ -261,7 +265,7 @@ int i18n_alpha_idx_clear_records(i18_alpha_idx_h index) 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); @@ -274,7 +278,7 @@ int i18n_alpha_idx_get_bucket_count(i18_alpha_idx_h index, 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); @@ -287,7 +291,7 @@ int i18n_alpha_idx_get_record_count(i18_alpha_idx_h index, 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) { @@ -303,7 +307,7 @@ int i18n_alpha_idx_get_bucket_index(i18_alpha_idx_h 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); @@ -314,18 +318,18 @@ int i18n_alpha_idx_get_current_bucket_index(i18_alpha_idx_h index, 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); @@ -337,15 +341,18 @@ int i18n_alpha_idx_get_record_name(i18_alpha_idx_h index, _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); @@ -356,7 +363,7 @@ int i18n_alpha_idx_reset_bucket_iter(i18_alpha_idx_h index) 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);