From 693fb37218cdce2b1dbee0304a81902a4c3357ad Mon Sep 17 00:00:00 2001 From: JinWang An Date: Fri, 24 May 2024 14:25:29 +0900 Subject: [PATCH] Add example code about release handle Change-Id: Ia21058d1c93686cf2239af75d0cfc79f165579f0 Signed-off-by: JinWang An --- src/include/utils_i18n_timezone.h | 374 +++++++++++++++++++++++- src/include/utils_i18n_ubidi.h | 2 + src/include/utils_i18n_ubrk.h | 2 + src/include/utils_i18n_ucalendar.h | 120 ++++++++ src/include/utils_i18n_uchar.h | 4 +- src/include/utils_i18n_uchar_iter.h | 18 ++ src/include/utils_i18n_ucnv.h | 95 +++++- src/include/utils_i18n_ucnvsel.h | 92 ++++++ src/include/utils_i18n_ucollator.h | 137 +++++++++ src/include/utils_i18n_udate.h | 35 +++ src/include/utils_i18n_udatepg.h | 92 ++++++ src/include/utils_i18n_ulocale.h | 1 + src/include/utils_i18n_unormalization.h | 6 + src/include/utils_i18n_unumber.h | 28 +- src/include/utils_i18n_unumsys.h | 36 ++- src/include/utils_i18n_ures.h | 22 +- src/include/utils_i18n_usearch.h | 1 + src/include/utils_i18n_uset.h | 143 ++++++++- src/include/utils_i18n_ustring.h | 1 + src/include/utils_i18n_utext.h | 18 +- tests/utc-capi-base-utils-timezone.c | 1 + 21 files changed, 1206 insertions(+), 22 deletions(-) diff --git a/src/include/utils_i18n_timezone.h b/src/include/utils_i18n_timezone.h index a20fcd9..4ea170b 100644 --- a/src/include/utils_i18n_timezone.h +++ b/src/include/utils_i18n_timezone.h @@ -63,12 +63,37 @@ extern "C" { * @brief Returns the "unknown" time zone. * @details #i18n_timezone_create() returns a mutable clone of this time zone if the input ID is not recognized. * @since_tizen 2.3 + * @remarks The @a timezone should be released using i18n_timezone_destory(). * * @param[out] timezone the "unknown" time zone. * * @retval #I18N_ERROR_NONE Successful * @see i18n_timezone_create() * @see i18n_timezone_create_gmt() + * @code + * #include + * #include + * #include + * int main() { + * i18n_timezone_h timezone; + * i18n_error_code_e error_code; + * char *timezone_id = NULL; + * + * error_code = i18n_timezone_create_unknown(&timezone); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error creating unknown timezone: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * i18n_timezone_get_id(timezone, &timezone_id); + * printf("Created unknown timezone: %s\n", timezone_id); + * + * i18n_timezone_destroy(timezone); + * free(timezone_id); + * + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_timezone_create_unknown(i18n_timezone_h *timezone); @@ -77,22 +102,74 @@ int i18n_timezone_create_unknown(i18n_timezone_h *timezone); * @details This is a commonly used time zone.\n * Note: For backward compatibility reason, the ID used by the time zone returned by this method is "GMT", although the I18N's canonical ID for the GMT time zone is "Etc/GMT". * @since_tizen 2.3 + * @remarks The @a timezone should be released using i18n_timezone_destory(). * * @param[out] timezone the GMT/UTC time zone. * * @retval #I18N_ERROR_NONE Successful * @see i18n_timezone_create_unknown() + * @code + * #include + * #include + * #include + * + * int main() { + * i18n_timezone_h timezone; + * i18n_error_code_e error_code; + * char *timezone_id = NULL; + * + * error_code = i18n_timezone_create_gmt(&timezone); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error creating GMT timezone: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * i18n_timezone_get_id(timezone, &timezone_id); + * printf("Created gmt timezone: %s\n", timezone_id); + * + * i18n_timezone_destroy(timezone); + * free(timezone_id); + * + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_timezone_create_gmt(i18n_timezone_h *timezone); /** * @brief Creates an i18n_timezone_h for the given timezone_id. * @since_tizen 2.3 + * @remarks The @a timezone should be released using i18n_timezone_destory(). * * @param[out] timezone the GMT/UTC time zone. * @param[in] timezone_id the ID for an i18n_timezone_h, such as "America/Los_Angeles", or a custom ID such as "GMT-8:00". * * @retval #I18N_ERROR_NONE Successful + * @code + * #include + * #include + * #include + * + * int main() { + * i18n_timezone_h timezone; + * i18n_error_code_e error_code; + * char *timezone_id = NULL; + * + * error_code = i18n_timezone_create(&timezone, "Asia/Seoul"); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error creating timezone: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * i18n_timezone_get_id(timezone, &timezone_id); + * printf("Created timezone: %s\n", timezone_id); + * + * i18n_timezone_destroy(timezone); + * free(timezone_id); + * + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_timezone_create(i18n_timezone_h *timezone, const char *timezone_id); @@ -188,6 +265,7 @@ int i18n_timezone_count_equivalent_ids(const char *timezone_id, int32_t *count); * If the given id is not a valid system time zone, * or if 'index' is out of range, then returns an empty string. * @since_tizen 2.3 + * @remarks The @a equivalent_timezone_id should be released using free(). * * @param[in] timezone_id a system time zone ID * @param[in] index a value from 0 to n-1, where n is the out parameter value from i18n_timezone_count_equivalent_ids(timezone_id, &n) @@ -196,6 +274,25 @@ int i18n_timezone_count_equivalent_ids(const char *timezone_id, int32_t *count); * * @retval #I18N_ERROR_NONE Successful * @see i18n_timezone_count_equivalent_ids() + * @code + * #include + * #include + * #include + * + * int main() { + * const char *timezone_id = "PST"; + * int32_t index = 0; + * char *equivalent_timezone_id; + * ret = i18n_timezone_get_equivalent_id(timezone_id, index, &equivalent_timezone_id); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error creating timezone: %d\n", error_code); + * return EXIT_FAILURE; + * } + * printf("equivalent timezone id: %s\n", equivalent_timezone_id); + * free(equivalent_timezone_id); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_timezone_get_equivalent_id(const char *timezone_id, int32_t index, char **equivalent_timezone_id); @@ -213,10 +310,35 @@ int i18n_timezone_get_equivalent_id(const char *timezone_id, int32_t index, char * To query the system for the current timezone, use i18n_timezone_detect_host_timezone(). * * @since_tizen 2.3 + * @remarks The @a timezone should be released using i18n_timezone_destory(). * * @param[out] timezone A default i18n_timezone_h. Clients are responsible for deleting the time zone object returned. * * @retval #I18N_ERROR_NONE Successful + * @code + * #include + * #include + * #include + * + * int main() { + * i18n_timezone_h timezone; + * i18n_error_code_e error_code; + * char *timezone_id = NULL; + * + * error_code = i18n_timezone_create_default(&timezone); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error creating default timezone: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_timezone_get_id(timezone, &timezone_id); + * printf("Created default timezone: %s\n", timezone_id); + * + * i18n_timezone_destroy(timezone); + * free(timezone_id); + * + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_timezone_create_default(i18n_timezone_h *timezone); @@ -307,22 +429,48 @@ int i18n_timezone_get_raw_offset(i18n_timezone_h timezone, int32_t *offset_milli /** * @brief Fills in "timezone_id" with the i18n_timezone_h's ID. * @since_tizen 2.3 + * @remarks The @a timezone_id should be released using free(). * * @param[in] timezone The i18n_timezone_h to get a timezone ID. * @param[out] timezone_id Receives this i18n_timezone_h's ID. * * @retval #I18N_ERROR_NONE Successful + * @code + * #include + * #include + * #include + * + * int main() { + * i18n_timezone_h timezone; + * i18n_error_code_e error_code; + * char *timezone_id = NULL; + * + * error_code = i18n_timezone_create(&timezone, "Asia/Seoul"); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error creating timezone: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * i18n_timezone_get_id(timezone, &timezone_id); + * printf("Created timezone: %s\n", timezone_id); + * + * i18n_timezone_destroy(timezone); + * free(timezone_id); + * + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_timezone_get_id(i18n_timezone_h timezone, char **timezone_id); /** * @brief Sets the i18n_timezone_h's ID to the specified value. * @details This doesn't affect any other fields. for example,\n - * \n - * i18n_timezone_h timezone = NULL;\n - * i18n_timezone_create ( &timezone, "America/New_York" );\n - * i18n_timezone_set_id ( "America/Los_Angeles" );\n - * \n + * \n + * i18n_timezone_h timezone = NULL;\n + * i18n_timezone_create ( &timezone, "America/New_York" );\n + * i18n_timezone_set_id ( "America/Los_Angeles" );\n + * \n * the timezone's GMT offset and daylight-savings rules don't change to those for Los Angeles. * They're still those for New York. Only the ID has changed. * @since_tizen 2.3 @@ -339,11 +487,47 @@ int i18n_timezone_set_id(i18n_timezone_h timezone, const char *timezone_id); * @details This method returns the long name, not including daylight savings. * If the display name is not available for the locale, then this method returns a string in the localized GMT offset format such as GMT[+-]HH:mm. * @since_tizen 2.3 + * @remarks The @a display_name should be released using free(). * * @param[in] timezone The i18n_timezone_h to get a display name. * @param[out] display_name The human-readable name of this time zone in the default locale. * * @retval #I18N_ERROR_NONE Successful + * @code + * #include + * #include + * #include + * + * int main() + * { + * char *display_name; + * i18n_timezone_h timezone = NULL; + * i18n_error_code_e error_code; + * char timezone_id[10]; + * int gmt = -12; + * for(; gmt < 15; gmt++) { + * snprintf(timezone_id, 10, (gmt<0)? "GMT%d:00" : "GMT+%d:00", gmt); + * error_code = i18n_timezone_create(&timezone, timezone_id); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_timezone_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * error_code = i18n_timezone_get_display_name(timezone, &display_name); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_timezone_get_display_name: %d\n", error_code); + * i18n_timezone_destroy(timezone); + * return EXIT_FAILURE; + * } + * printf("Created %s timezone display_name: %s\n", timezone_id, display_name); + * free(display_name); + * i18n_timezone_destroy(timezone); + * timezone = NULL; + * } + * + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_timezone_get_display_name(i18n_timezone_h timezone, char **display_name); @@ -353,6 +537,7 @@ int i18n_timezone_get_display_name(i18n_timezone_h timezone, char **display_name * @details This method returns the long name, not including daylight savings. * If the display name is not available for the locale, then this method returns a string in the localized GMT offset format such as GMT[+-]HH:mm. * @since_tizen 2.3 + * @remarks The @a display_name should be released using free(). * * @param[in] timezone The i18n_timezone_h to get a display name. * @param[in] language The language in which to supply the display name. This parameter can be NULL; if so, the locale is initialized to match the current default locale. @@ -360,6 +545,44 @@ int i18n_timezone_get_display_name(i18n_timezone_h timezone, char **display_name * @param[out] display_name The human-readable name of this time zone in the default locale. * * @retval #I18N_ERROR_NONE Successful + * @code + * #include + * #include + * #include + * + * int main() + * { + * const char *language = I18N_ULOCALE_ENGLISH; + * const char *country = "US"; + * char *display_name; + * i18n_timezone_h timezone = NULL; + * i18n_error_code_e error_code; + * char timezone_id[10]; + * int gmt = -12; + * for(; gmt < 15; gmt++) { + * snprintf(timezone_id, 10, (gmt<0)? "GMT%d:00" : "GMT+%d:00", gmt); + * error_code = i18n_timezone_create(&timezone, timezone_id); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_timezone_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * error_code = i18n_timezone_get_display_name_with_locale(timezone, language, country, &display_name); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_timezone_get_display_name_with_locale: %d\n", error_code); + * i18n_timezone_destroy(timezone); + * return EXIT_FAILURE; + * } + * printf("Created %s timezone display_name: %s\n", timezone_id, display_name); + * free(display_name); + * + * i18n_timezone_destroy(timezone); + * timezone = NULL; + * } + * + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_timezone_get_display_name_with_locale(i18n_timezone_h timezone, const char *language, const char *country , char **display_name) TIZEN_DEPRECATED_API; @@ -368,6 +591,7 @@ int i18n_timezone_get_display_name_with_locale(i18n_timezone_h timezone, const c * @details If the display name is not available for the locale, * then this method returns a string in the localized GMT offset format such as GMT[+-]HH:mm. * @since_tizen 2.3 + * @remarks The @a display_name should be released using free(). * * @param[in] timezone The i18n_timezone_h to get a display name. * @param[in] daylight If true, display_name is filled with the daylight savings name. @@ -375,6 +599,47 @@ int i18n_timezone_get_display_name_with_locale(i18n_timezone_h timezone, const c * @param[out] display_name The human-readable name of this time zone in the default locale. * * @retval #I18N_ERROR_NONE Successful + * @code + * #include + * #include + * #include + * + * int main() + * { + * i18n_timezone_h timezone = NULL; + * i18n_ubool daylight = true; + * i18n_timezone_display_type_e type = I18N_TIMEZONE_DISPLAY_TYPE_SHORT; + * i18n_error_code_e error_code; + * char *display_name; + * char timezone_id[10]; + * int gmt = -12; + * for(; gmt < 15; gmt++) { + * type = I18N_TIMEZONE_DISPLAY_TYPE_SHORT; + * snprintf(timezone_id, 10, (gmt<0)? "GMT%d:00" : "GMT+%d:00", gmt); + * error_code = i18n_timezone_create(&timezone, timezone_id); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_timezone_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * for(; type <= I18N_TIMEZONE_DISPLAY_TYPE_GENERIC_LOCATION; type++) { + * error_code = i18n_timezone_get_display_name_with_type(timezone, daylight, type, &display_name); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_timezone_get_display_name_with_type: %d\n", error_code); + * i18n_timezone_destroy(timezone); + * return EXIT_FAILURE; + * } + * printf("Created %s timezone display_name: %s\n", timezone_id, display_name); + * free(display_name); + * } + * + * error_code = i18n_timezone_destroy(timezone); + * timezone = NULL; + * } + * + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_timezone_get_display_name_with_type(i18n_timezone_h timezone, i18n_ubool daylight, i18n_timezone_display_type_e style, char **display_name); @@ -384,6 +649,7 @@ int i18n_timezone_get_display_name_with_type(i18n_timezone_h timezone, i18n_uboo * @details If the display name is not available for the locale, * then this method returns a string in the localized GMT offset format such as GMT[+-]HH:mm. * @since_tizen 2.3 + * @remarks The @a display_name should be released using free(). * * @param[in] timezone The i18n_timezone_h to get a display name. * @param[in] daylight If true, display_name is filled with the daylight savings name. @@ -393,6 +659,44 @@ int i18n_timezone_get_display_name_with_type(i18n_timezone_h timezone, i18n_uboo * @param[out] display_name The human-readable name of this time zone in the default locale. * * @retval #I18N_ERROR_NONE Successful + * @code + * #include + * #include + * #include + * + * int main() { + * i18n_timezone_h timezone; + * i18n_error_code_e error_code; + * i18n_ubool daylight = true; + * i18n_timezone_display_type_e style = I18N_TIMEZONE_DISPLAY_TYPE_LONG; + * char *timezone_id = NULL; + * const char *language = I18N_ULOCALE_ENGLISH; + * const char *country = "US"; + * char *display_name; + * + * error_code = i18n_timezone_create_default(&timezone); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error creating default timezone: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * error_code = i18n_timezone_get_display_name_with_type_locale(timezone, daylight, style, language, country, &display_name); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_timezone_get_display_name_with_type_locale: %d\n", error_code); + * i18n_timezone_destroy(timezone); + * return EXIT_FAILURE; + * } + * + * i18n_timezone_get_id(timezone, &timezone_id); + * printf("Created %s timezone display_name: %s\n", timezone_id, display_name); + * + * i18n_timezone_destroy(timezone); + * free(display_name); + * free(timezone_id); + * + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_timezone_get_display_name_with_type_locale(i18n_timezone_h timezone, i18n_ubool daylight, i18n_timezone_display_type_e style, const char *language, const char *country, char **display_name) TIZEN_DEPRECATED_API; @@ -424,11 +728,45 @@ int i18n_timezone_has_same_rule(i18n_timezone_h timezone, i18n_timezone_h other, * @brief Clones i18n_timezone_h polymorphically. * @details Clients are responsible for deleting the i18n_timezone_h cloned. * @since_tizen 2.3 + * @remarks The @a clone should be released using i18n_timezone_destroy(). * * @param[in] timezone The i18n_timezone_h to clone. * @param[out] clone A new copy of this i18n_timezone_h. * * @retval #I18N_ERROR_NONE Successful + * @code + * #include + * #include + * #include + * + * int main() { + * i18n_timezone_h timezone, clone; + * i18n_error_code_e error_code; + * char *timezone_id = NULL; + * + * error_code = i18n_timezone_create_default(&timezone); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error creating default timezone: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * error_code = i18n_timezone_clone(timezone, &clone); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_timezone_get_display_name_with_type_locale: %d\n", error_code); + * i18n_timezone_destroy(timezone); + * return EXIT_FAILURE; + * } + * + * i18n_timezone_get_id(clone, &timezone_id); + * printf("Created clone timezone: %s\n", timezone_id); + * + * i18n_timezone_destroy(timezone); + * i18n_timezone_destroy(clone); + * free(timezone_id); + * + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_timezone_clone(i18n_timezone_h timezone, i18n_timezone_h *clone); @@ -453,6 +791,7 @@ int i18n_timezone_get_dst_savings(i18n_timezone_h timezone, int32_t *dst_savings * ICU's default. It may return a different #i18n_timezone_h from the one returned by * i18n_timezone_create_default(). * @since_tizen 3.0 + * @remarks The @a timezone should be released using i18n_timezone_destory(). * * @param[out] timezone A new instance of #i18n_timezone_h detected from the current host system * configuration. Users are responsible for deleting the returned time zone object with @@ -460,6 +799,31 @@ int i18n_timezone_get_dst_savings(i18n_timezone_h timezone, int32_t *dst_savings * * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * + * int main() { + * i18n_timezone_h timezone; + * i18n_error_code_e error_code; + * char *timezone_id = NULL; + * + * error_code = i18n_timezone_detect_host_timezone(&timezone); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error creating timezone: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * i18n_timezone_get_id(timezone, &timezone_id); + * printf("Created timezone: %s\n", timezone_id); + * + * i18n_timezone_destroy(timezone); + * free(timezone_id); + * + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_timezone_detect_host_timezone(i18n_timezone_h *timezone); diff --git a/src/include/utils_i18n_ubidi.h b/src/include/utils_i18n_ubidi.h index ec167d6..bf518b4 100644 --- a/src/include/utils_i18n_ubidi.h +++ b/src/include/utils_i18n_ubidi.h @@ -129,6 +129,7 @@ int i18n_ubidi_get_base_direction(const i18n_uchar *text, int32_t length, /** * @brief Gets the current callback function used for ubidi class determination. * @since_tizen 3.0 + * @remarks The @a fn and @a context should not be released. * * @param[in] ubidi The paragraph #i18n_ubidi_h object * @param[out] fn The callback function pointer. This can be @c NULL. @@ -827,6 +828,7 @@ int i18n_ubidi_reorder_visual(const i18n_ubidi_level_t *levels, int32_t length, * logical lines which are part of a report organized in columns: there should not be * interaction between adjacent cells. * @since_tizen 3.0 + * @remarks The @a old_fn and @a old_context should not be released. * * @param[in] ubidi The paragraph #i18n_ubidi_h object * @param[in] new_fn The new callback function pointer diff --git a/src/include/utils_i18n_ubrk.h b/src/include/utils_i18n_ubrk.h index cab7650..3d6d4b3 100644 --- a/src/include/utils_i18n_ubrk.h +++ b/src/include/utils_i18n_ubrk.h @@ -73,6 +73,7 @@ int i18n_ubrk_create(i18n_ubreak_iterator_type_e type, const char *locale, const * @brief Opens a new #i18n_ubreak_iterator_h for locating text boundaries using specified breaking rules. * @remarks Error codes are described in #i18n_error_code_e description. * @since_tizen 2.3.1 + * @remarks The @a break_iter and @a parse_err should not be released. * @param[in] rules A set of rules specifying the text breaking conventions. * @param[in] rules_length The number of characters in rules, or -1 if NULL-terminated. * @param[in] text The text to be iterated over. May be @c NULL, in which case i18n_ubrk_set_text() is @@ -92,6 +93,7 @@ int i18n_ubrk_create_rules(const i18n_uchar *rules, int32_t rules_length, const * @brief Thread safe cloning operation. * @remarks Error codes are described in #i18n_error_code_e description. * @since_tizen 2.3.1 + * @remarks The @a break_iter_clone should not be released. * @param[in] break_iter iterator to be cloned. Must not be @c NULL. * @param[in] stack_buffer (Deprecated Since 3.0. Use NULL instead.) User allocated space for the new clone. If @c NULL new memory will be allocated. * If buffer is not large enough, new memory will be allocated. diff --git a/src/include/utils_i18n_ucalendar.h b/src/include/utils_i18n_ucalendar.h index 4840bc4..267bda5 100644 --- a/src/include/utils_i18n_ucalendar.h +++ b/src/include/utils_i18n_ucalendar.h @@ -186,11 +186,41 @@ int i18n_ucalendar_destroy(i18n_ucalendar_h calendar); * @brief Creates a copy of a #i18n_ucalendar_h. * This function performs a deep copy. * @since_tizen 2.3 + * @remarks Must release @a identical_to_cal using i18n_ucalendar_destroy(). * * @param[in] cal The #i18n_ucalendar_h to copy * @param[out] identical_to_cal A pointer to a #i18n_ucalendar_h identical to @a cal. * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_ucalendar_h cal = NULL; + * i18n_ucalendar_h identical_to_cal = NULL; + * i18n_error_code_e error_code; + * + * error_code = i18n_ucalendar_create(NULL, -1, I18N_ULOCALE_US, I18N_UCALENDAR_DEFAULT, &cal); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucalendar_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * i18n_ucalendar_set_date_time(cal, 2000, 1, 1, 1, 1, 1); + * + * error_code = i18n_ucalendar_clone(cal, &identical_to_cal); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucalendar_clone: %d\n", error_code); + * i18n_ucalendar_destroy(cal); + * return EXIT_FAILURE; + * } + * + * i18n_ucalendar_destroy(identical_to_cal); + * i18n_ucalendar_destroy(cal); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucalendar_clone(const i18n_ucalendar_h cal, i18n_ucalendar_h *identical_to_cal); @@ -421,6 +451,7 @@ int32_t i18n_ucalendar_get_field_difference(i18n_ucalendar_h calendar, i18n_udat /** * @brief Creates an enumeration over system time zone IDs with the given filter conditions. * @since_tizen 2.3.1 + * @remarks The @a enumeration should be released using i18n_uenumeration_destroy(). * * @param[in] zone_type The system time zone type. * @param[in] region The ISO 3166 two-letter country code or UN M.49 three-digit @@ -434,12 +465,29 @@ int32_t i18n_ucalendar_get_field_difference(i18n_ucalendar_h calendar, i18n_udat * @return Error code. Error codes not listed below are described in #i18n_error_code_e * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_uenumeration_h enumeration = NULL; + * i18n_error_code_e error_code; + * error_code = i18n_ucalendar_timezone_id_enumeration_create(I18N_UCALENDAR_ZONE_TYPE_ANY, "US", NULL, &enumeration); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucalendar_timezone_id_enumeration_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_uenumeration_destroy(enumeration); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucalendar_timezone_id_enumeration_create(i18n_system_timezone_type_e zone_type, const char *region, const int32_t *raw_offset, i18n_uenumeration_h *enumeration); /** * @brief Creates an enumeration over all time zones. * @since_tizen 2.3.1 + * @remarks The @a enumeration should be released using i18n_uenumeration_destroy(). * * @param[out] enumeration A pointer to the enumeration object that the caller must dispose of using * i18n_uenumeration_destroy(), or @c NULL upon failure. @@ -447,6 +495,22 @@ int i18n_ucalendar_timezone_id_enumeration_create(i18n_system_timezone_type_e zo * @return Error code. Error codes not listed below are described in #i18n_error_code_e * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_uenumeration_h enumeration = NULL; + * i18n_error_code_e error_code; + * error_code = i18n_ucalendar_timezones_create(&enumeration); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucalendar_timezones_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_uenumeration_destroy(enumeration); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucalendar_timezones_create(i18n_uenumeration_h *enumeration); @@ -454,6 +518,7 @@ int i18n_ucalendar_timezones_create(i18n_uenumeration_h *enumeration); * @brief Creates an enumeration over all time zones associated with the given country. * @details Some zones are affiliated with no country (e.g., "UTC"); these may also be retrieved, as a group. * @since_tizen 2.3.1 + * @remarks The @a enumeration should be released using i18n_uenumeration_destroy(). * * @param[in] country The ISO 3166 two-letter country code, or @c NULL to retrieve zones not affiliated with any country * @@ -463,6 +528,22 @@ int i18n_ucalendar_timezones_create(i18n_uenumeration_h *enumeration); * @return Error code. Error codes not listed below are described in #i18n_error_code_e * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_uenumeration_h enumeration = NULL; + * i18n_error_code_e error_code; + * error_code = i18n_ucalendar_country_timezones_create("US", &enumeration); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucalendar_country_timezones_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_uenumeration_destroy(enumeration); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucalendar_country_timezones_create(const char *country, i18n_uenumeration_h *enumeration); @@ -808,6 +889,7 @@ const char *i18n_ucalendar_get_type(const i18n_ucalendar_h calendar); * locale formed from the input locale plus input keyword and that value * has different behavior than creation with the input locale alone. * @since_tizen 2.3.1 + * @remarks The @a enumeration should be released using i18n_uenumeration_destroy(). * * @param[in] key One of the keys supported by this service. For now, only "calendar" is supported. * @param[in] locale The locale @@ -820,6 +902,44 @@ const char *i18n_ucalendar_get_type(const i18n_ucalendar_h calendar); * @return Error code. Error codes not listed below are described in #i18n_error_code_e * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * + * int main() { + * i18n_ucalendar_h cal = NULL; + * i18n_error_code_e error_code; + * i18n_uenumeration_h enumeration = NULL; + * + * error_code = i18n_ucalendar_create(NULL, -1, I18N_ULOCALE_US, I18N_UCALENDAR_DEFAULT, &cal); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucalendar_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * const char *key = i18n_ucalendar_get_type(cal); + * error_code = get_last_result(); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucalendar_create: %d\n", error_code); + * i18n_ucalendar_destroy(cal); + * return EXIT_FAILURE; + * } + * + * const char *locale = i18n_ucalendar_get_available(1); + * error_code = i18n_ucalendar_get_keyword_values_for_locale(key, locale, 0, &enumeration); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucalendar_get_keyword_values_for_localee: %d\n", error_code); + * i18n_ucalendar_destroy(cal); + * return EXIT_FAILURE; + * } + * + * i18n_uenumeration_destroy(enumeration); + * i18n_ucalendar_destroy(cal); + * return EXIT_SUCCESS; + * } + * + * @endcode */ int i18n_ucalendar_get_keyword_values_for_locale(const char *key, const char *locale, i18n_ubool commonly_used, i18n_uenumeration_h *enumeration); diff --git a/src/include/utils_i18n_uchar.h b/src/include/utils_i18n_uchar.h index 06333e8..e280162 100644 --- a/src/include/utils_i18n_uchar.h +++ b/src/include/utils_i18n_uchar.h @@ -962,6 +962,7 @@ int i18n_uchar_enum_char_names(i18n_uchar32 start, * @details In addition, this function maps the property #I18N_UCHAR_GENERAL_CATEGORY_MASK to the * synthetic names "gcm" / "General_Category_Mask". * @since_tizen 4.0 + * @remarks The @a name should not be released. * * @param[in] property #18n_uchar_uproperty_e selector other than #I18N_UCHAR_INVALID_CODE. * If out of range, NULL is returned. @@ -975,7 +976,7 @@ int i18n_uchar_enum_char_names(i18n_uchar32 start, * NULL, then all larger values of @a name_choice will return NULL, * with one exception: if NULL is returned for #I18N_UCHAR_U_SHORT_PROPERTY_NAME, * then #I18N_UCHAR_U_LONG_PROPERTY_NAME (and higher) may still return - * a non-NULL value. The returned pointer is valid until 18n_uclean_cleanup() + * a non-NULL value. The returned pointer is valid until i18n_uclean_cleanup() * (not implemented) is called. * * @return @c 0 on success, otherwise a negative error value @@ -1014,6 +1015,7 @@ int i18n_uchar_get_property_enum(const char *alias, i18n_uchar_uproperty_e *prop * "Cased_Letter", "M" / "Mark", "N" / "Number", "P" / "Punctuation", "S" / "Symbol", * and "Z" / "Separator". * @since_tizen 4.0 + * @remarks The @a name should not be released. * * @param[in] property #i18n_uchar_uproperty_e selector constant. Must be * #I18N_UCHAR_BINARY_START <= @a property < #I18N_UCHAR_BINARY_LIMIT or diff --git a/src/include/utils_i18n_uchar_iter.h b/src/include/utils_i18n_uchar_iter.h index bf62243..1c35f08 100644 --- a/src/include/utils_i18n_uchar_iter.h +++ b/src/include/utils_i18n_uchar_iter.h @@ -64,6 +64,24 @@ extern "C" { * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter * @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory + * @code + * #include + * #include + * #include + * + * int main() { + * i18n_error_code_e error_code; + * i18n_iter_h iter = NULL; + * error_code = i18n_iter_create(&iter); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_iter_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_iter_destroy(iter); + * return EXIT_SUCCESS; + * } + * + * @endcode */ int i18n_uchar_iter_create(i18n_uchar_iter_h *iter); diff --git a/src/include/utils_i18n_ucnv.h b/src/include/utils_i18n_ucnv.h index cf850ec..61c8015 100644 --- a/src/include/utils_i18n_ucnv.h +++ b/src/include/utils_i18n_ucnv.h @@ -112,7 +112,22 @@ int i18n_ucnv_compare_names(const char *name1, const char *name2); * @see i18n_ucnv_get_default_name() * @see i18n_ucnv_destroy() * @see i18n_ucnv_compare_names() - * + * @code + * #include + * #include + * #include + * int main() { + * i18n_ucnv_h converter; + * i18n_error_code_e error_code; + * error_code = i18n_ucnv_create("ibm-949", &converter); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucnv_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_ucnv_destroy(converter); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucnv_create(const char *converter_name, i18n_ucnv_h *converter); @@ -139,6 +154,23 @@ int i18n_ucnv_create(const char *converter_name, i18n_ucnv_h *converter); * @see i18n_ucnv_destroy() * @see i18n_ucnv_compare_names() * + * @code + * #include + * #include + * #include + * int main() { + * i18n_ucnv_h converter; + * i18n_error_code_e error_code; + * i18n_uchar name[] = {0x0069, 0x0062, 0x006d, 0x002d, 0x0039, 0x0034, 0x0033, 0x0000}; + * error_code = i18n_ucnv_create_unicode(name, &converter); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucnv_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_ucnv_destroy(converter); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucnv_create_unicode(const i18n_uchar *name, i18n_ucnv_h *converter); @@ -173,6 +205,27 @@ int i18n_ucnv_create_unicode(const i18n_uchar *name, i18n_ucnv_h *converter); * @see i18n_ucnv_get_ccsid() * @see i18n_ucnv_get_platform() * + * @code + * #include + * #include + * #include + * int main() { + * i18n_ucnv_h converter; + * i18n_error_code_e error_code; + * int32_t ccsids[] = {37, 850, 943, 949, 950, 1047, 1252, 1392, 33722}; + * + * for (int i = 0; i < 9; ++i) + * { + * error_code = i18n_ucnv_create_ccsid(ccsids[i], I18N_UCNV_IBM, &converter); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucnv_create_ccsid: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_ucnv_destroy(converter); + * } + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucnv_create_ccsid(int32_t codepage, i18n_ucnv_platform_e platform, i18n_ucnv_h *converter); @@ -198,6 +251,22 @@ int i18n_ucnv_create_ccsid(int32_t codepage, i18n_ucnv_platform_e platform, i18n * @see i18n_ucnv_create() * @see i18n_ucnv_safe_clone() * + * @code + * #include + * #include + * #include + * int main() { + * i18n_ucnv_h converter; + * i18n_error_code_e error_code; + * error_code = i18n_ucnv_create_package("", "", &converter); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucnv_create_package: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_ucnv_destroy(converter); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucnv_create_package(const char *package_name, const char *converter_name, i18n_ucnv_h *converter); @@ -211,6 +280,30 @@ int i18n_ucnv_create_package(const char *package_name, const char *converter_nam * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter * + * @code + * #include + * #include + * #include + * int main() { + * i18n_ucnv_h converter; + * i18n_ucnv_h cloned_converter; + * i18n_error_code_e error_code; + * error_code = i18n_ucnv_create("iso-8859-3", &converter); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucnv_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * error_code = i18n_ucnv_safe_clone(converter, &cloned_converter); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucnv_safe_clone: %d\n", error_code); + * i18n_ucnv_destroy(converter); + * return EXIT_FAILURE; + * } + * i18n_ucnv_destroy(converter); + * i18n_ucnv_destroy(cloned_converter); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucnv_safe_clone(i18n_ucnv_h converter, i18n_ucnv_h *cloned_converter); diff --git a/src/include/utils_i18n_ucnvsel.h b/src/include/utils_i18n_ucnvsel.h index ad3cc59..8783b9e 100644 --- a/src/include/utils_i18n_ucnvsel.h +++ b/src/include/utils_i18n_ucnvsel.h @@ -123,6 +123,51 @@ int i18n_ucnvsel_serialize(const i18n_uconverter_selector_h sel, void *buffer, i * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter * + * @code + * int main() { + * i18n_uenumeration_h enumeration = NULL; + * i18n_uconverter_selector_h sel; + * i18n_uset_h excluded_set = NULL; + * const char *char_str = "Hello World!"; + * const i18n_uchar string[20] = {0,}; + * i18n_error_code_e error_code; + * int32_t length; + * + * i18n_ustring_from_UTF8((i18n_uchar *)string, I18N_UPRV_LENGTHOF(string), &length, char_str, 5, &error_code); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ustring_from_UTF8: %d\n", error_code); + * i18n_uenumeration_destroy(enumeration); + * return EXIT_FAILURE; + * } + * + * error_code = i18n_uset_create_empty(&excluded_set); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_uset_create_empty: %d\n", error_code); + * i18n_uenumeration_destroy(enumeration); + * return EXIT_FAILURE; + * } + * + * error_code = i18n_ucnvsel_create(NULL, 0, excluded_set, I18N_UCNV_ROUNDTRIP_AND_FALLBACK_SET, &sel); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucnvsel_create: %d\n", error_code); + * i18n_uset_destroy(excluded_set); + * return EXIT_FAILURE; + * } + * + * error_code = i18n_ucnvsel_select_for_string(sel, string, length, &enumeration); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucnvsel_select_for_string: %d\n", error_code); + * i18n_uset_destroy(excluded_set); + * i18n_ucnvsel_destroy(sel); + * return EXIT_FAILURE; + * } + * + * i18n_uenumeration_destroy(enumeration); + * i18n_uset_destroy(excluded_set); + * i18n_ucnvsel_destroy(sel); + * return EXIT_SUCCESS; + * } + * @encode */ int i18n_ucnvsel_select_for_string(const i18n_uconverter_selector_h sel, const i18n_uchar *string, int32_t length, i18n_uenumeration_h *enumeration); @@ -138,6 +183,53 @@ int i18n_ucnvsel_select_for_string(const i18n_uconverter_selector_h sel, const i * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter * + * @code + * #include + * #include + * #include + * #include + * #define I18N_UPRV_LENGTHOF(array) (int32_t)(sizeof(array)/sizeof((array)[0])) + * + * int main() { + * i18n_uenumeration_h enumeration = NULL; + * i18n_uconverter_selector_h sel; + * i18n_uset_h excluded_set = NULL; + * const char *string = "Hello World!"; + * i18n_error_code_e error_code; + * + * error_code = i18n_ucalendar_timezone_id_enumeration_create(I18N_UCALENDAR_ZONE_TYPE_ANY, "US", NULL, &enumeration); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_ucalendar_timezone_id_enumeration_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * error_code = i18n_uset_create_empty(&excluded_set); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_uset_create_empty: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * error_code = i18n_ucnvsel_create(NULL, 0, excluded_set, I18N_UCNV_ROUNDTRIP_AND_FALLBACK_SET, &sel); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucnvsel_create: %d\n", error_code); + * i18n_uset_destroy(excluded_set); + * return EXIT_FAILURE; + * } + * + * error_code = i18n_ucnvsel_select_for_utf8(sel, string, strlen(string), &enumeration); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucnvsel_select_for_utf8: %d\n", error_code); + * i18n_uset_destroy(excluded_set); + * i18n_ucnvsel_destroy(sel); + * return EXIT_FAILURE; + * } + * + * i18n_uenumeration_destroy(enumeration); + * i18n_uset_destroy(excluded_set); + * i18n_ucnvsel_destroy(sel); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucnvsel_select_for_utf8(const i18n_uconverter_selector_h sel, const char *string, int32_t length, i18n_uenumeration_h *enumeration); diff --git a/src/include/utils_i18n_ucollator.h b/src/include/utils_i18n_ucollator.h index 6949988..6db8633 100644 --- a/src/include/utils_i18n_ucollator.h +++ b/src/include/utils_i18n_ucollator.h @@ -157,6 +157,7 @@ int i18n_ucollator_create(const char *locale, i18n_ucollator_h *collator); * called tailoring. The resulting #i18n_ucollator_h pointer can be used in the same way as * the one obtained by i18n_ucollator_str_collator(). * @since_tizen 4.0 + * @remarks The @a collator should be released using i18n_ucollator_destroy(). * * @param[in] rules A string describing the collation rules. For the syntax of the rules * please see users guide @@ -182,6 +183,29 @@ int i18n_ucollator_create(const char *locale, i18n_ucollator_h *collator); * @see i18n_ucollator_create() * @see i18n_ucollator_safe_clone() * @see i18n_ucollator_destroy() + * @code + * #include + * #include + * #include + * #include + * int main() { + * i18n_error_code_e error_code; + * i18n_ucollator_h collator = NULL; + * i18n_uparse_error_s parse_error; + * const char *test_rules = "&9 < a, A < b, B < c, C; ch, cH, Ch, CH < d, D, e, E"; + * i18n_uchar rules[128]; + * + * i18n_ustring_copy_ua(rules, test_rules); + * error_code = i18n_ucollator_create_rules(rules, strlen(test_rules), I18N_UCOLLATOR_ON, I18N_UCOLLATOR_DEFAULT_STRENGTH, + * &parse_error, &collator); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucollator_create_rules: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_ucollator_destroy(collator); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucollator_create_rules(const i18n_uchar *rules, int32_t rules_length, @@ -498,12 +522,24 @@ int i18n_ucollator_get_display_name(const char *obj_locale, const char *disp_loc * @details An #i18n_ucollator_h in a locale returned by this function will perform the correct * collation for the locale. * @since_tizen 4.0 + * @remarks The @a locale should not be released. * * @param[in] locale_index The index of the desired locale * @param[out] locale A locale for which collation rules are available, or @c 0 if none * * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * i18n_error_code_e error_code; + * const char *locale = NULL; + * int32_t locale_index = 0; + * + * i18n_ucollator_get_available(locale_index, &locale); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucollator_get_available: %d\n", error_code); + * return EXIT_FAILURE; + * } + * @endcode */ int i18n_ucollator_get_available(int32_t locale_index, const char **locale); @@ -523,12 +559,30 @@ int i18n_ucollator_count_available(int32_t *n_available); /** * @brief Creates a string enumerator of all locales for which a valid collator may be created. * @since_tizen 4.0 + * @remarks The @a locales should be released using i18n_uenumeration_destroy(). * * @param[out] locales A string enumeration over locale strings. The caller is responsible for * releasing the result. * * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_error_code_e error_code; + * i18n_uenumeration_h locales; + * + * error_code = i18n_ucollator_create_available_locales(&locales); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucollator_create_available_locales: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_uenumeration_destroy(locales); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucollator_create_available_locales(i18n_uenumeration_h *locales); @@ -536,12 +590,30 @@ int i18n_ucollator_create_available_locales(i18n_uenumeration_h *locales); * @brief Creates a string enumerator of all possible keywords that are relevant to collation. * @details At this point, the only recognized keyword for this service is "collation". * @since_tizen 4.0 + * @remarks The @a keywords should be released using i18n_uenumeration_destroy(). * * @param[out] keywords A string enumeration over locale strings. The caller is responsible for * releasing the result. * * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_error_code_e error_code; + * i18n_uenumeration_h keywords; + * + * error_code = i18n_ucollator_get_keywords(&keywords); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucollator_get_keywords: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_uenumeration_destroy(keywords); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucollator_get_keywords(i18n_uenumeration_h *keywords); @@ -549,6 +621,7 @@ int i18n_ucollator_get_keywords(i18n_uenumeration_h *keywords); * @brief Given a keyword, create a string enumeration of all values for that keyword that are * currently in use. * @since_tizen 4.0 + * @remarks The @a keywords should be released using i18n_uenumeration_destroy(). * * @param[in] keyword A particular keyword as enumerated by i18n_ucollator_get_keywords(). * If any other keyword is passed in, returns #I18N_ERROR_INVALID_PARAMETER @@ -557,6 +630,23 @@ int i18n_ucollator_get_keywords(i18n_uenumeration_h *keywords); * * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_error_code_e error_code; + * i18n_uenumeration_h keyword; + * + * error_code = i18n_ucollator_get_keyword_values("collation", &keyword); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucollator_get_keyword_values: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_uenumeration_destroy(keyword); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucollator_get_keyword_values(const char *keyword, i18n_uenumeration_h *keywords); @@ -567,6 +657,7 @@ int i18n_ucollator_get_keyword_values(const char *keyword, i18n_uenumeration_h * * the locale formed from the input locale plus input keyword and that value has different * behavior than creation with the input locale alone. * @since_tizen 4.0 + * @remarks The @a keywords should be released using i18n_uenumeration_destroy(). * * @param[in] key One of the keys supported by this service. For now, only "collation" is * supported @@ -578,6 +669,23 @@ int i18n_ucollator_get_keyword_values(const char *keyword, i18n_uenumeration_h * * * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_error_code_e error_code; + * i18n_uenumeration_h keywords; + * + * error_code = i18n_ucollator_get_keyword_values_for_locale("collation", "en_US", false, &keywords); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucollator_get_keyword_values_for_locale: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_uenumeration_destroy(keywords); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucollator_get_keyword_values_for_locale(const char *key, const char *locale, i18n_ubool commonly_used, @@ -616,6 +724,7 @@ int i18n_ucollator_get_functional_equivalent(const char *keyword, const char *lo * @brief Gets the collation tailoring rules from a #i18n_ucollator_h. * @details The rules will follow the rule syntax. * @since_tizen 4.0 + * @remarks The @a rules should not be released. * * @param[in] collator The #i18n_ucollator_h to query * @param[out] length The length of the rules @@ -873,6 +982,7 @@ int i18n_ucollator_get_variable_top(i18n_ucollator_h collator, uint32_t *weight) /** * @brief Clones the given collator, the cloning is thread-safe. * @since_tizen 4.0 + * @remarks The @a clone should be released using i18n_ucollator_destroy(). * * @param[in] collator The collator to be cloned * @param[out] clone The pointer to the new clone @@ -882,6 +992,31 @@ int i18n_ucollator_get_variable_top(i18n_ucollator_h collator, uint32_t *weight) * @see i18n_ucollator_create() * @see i18n_ucollator_create_rules() * @see i18n_ucollator_destroy() + * @code + * #include + * #include + * #include + * int main() { + * i18n_error_code_e error_code; + * i18n_ucollator_h collator = NULL; + * i18n_ucollator_h clone = NULL; + * + * error_code = i18n_ucollator_create("en_US", &collator); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucollator_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * error_code = i18n_ucollator_safe_clone(collator, &clone); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_ucollator_safe_clone: %d\n", error_code); + * i18n_ucollator_destroy(collator); + * return EXIT_FAILURE; + * } + * i18n_ucollator_destroy(clone); + * i18n_ucollator_destroy(collator); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_ucollator_safe_clone(i18n_ucollator_h collator, i18n_ucollator_h *clone); @@ -913,6 +1048,7 @@ int i18n_ucollator_get_rules_ex(i18n_ucollator_h collator, i18n_ucollator_rule_o * @brief Gets the locale name of the collator. * @details If the collator is instantiated from the rules, then this function returns @c NULL. * @since_tizen 4.0 + * @remarks The @a locale should not be released. * * @param[in] collator The #i18n_ucollator_h for which the locale is needed * @param[in] type You can choose between requested, valid and actual locale. For description see @@ -930,6 +1066,7 @@ int i18n_ucollator_get_locale_by_type(i18n_ucollator_h collator, i18n_ulocale_da * @brief Gets a Unicode set that contains all the characters and sequences tailored in this collator. * @details The result must be disposed of by using i18n_uset_destroy(). * @since_tizen 4.0 + * @remarks The @a uset should not be released. * * @param[in] collator The #i18n_ucollator_h for which we want to get tailored chars * @param[out] uset A pointer to the newly created #i18n_uset_h. Must be be disposed by using diff --git a/src/include/utils_i18n_udate.h b/src/include/utils_i18n_udate.h index 6d04b60..a1e57d1 100644 --- a/src/include/utils_i18n_udate.h +++ b/src/include/utils_i18n_udate.h @@ -254,6 +254,7 @@ int i18n_udate_to_calendar_date_field(i18n_udate_format_field_e field, i18n_ucal * @brief Creates a copy of an #i18n_udate_format_h. * @details This function performs a deep copy. * @since_tizen 2.3.1 + * @remarks The @a format_clone should be released using i18n_udate_destroy(). * * @param[in] format The format to copy. * @param[out] format_clone A pointer to clone of @a format. @@ -261,6 +262,38 @@ int i18n_udate_to_calendar_date_field(i18n_udate_format_field_e field, i18n_ucal * @return Error code. Error codes not listed below are described in #i18n_error_code_e * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_error_code_e error_code; + * i18n_udate_format_h format = NULL; + * i18n_udate_format_style_e time_style = I18N_UDATE_DEFAULT, date_style = I18N_UDATE_DEFAULT; + * const char *locale = I18N_ULOCALE_US; + * const i18n_uchar *tz_id = 0; // use the default timezone + * int32_t tz_id_length = -1; + * const i18n_uchar *pattern = NULL; + * int32_t pattern_length = 0; + * i18n_udate_format_h format_clone = NULL; + * + * error_code = i18n_udate_create(time_style, date_style, locale, tz_id, tz_id_length, pattern, pattern_length, &format); + * if(error_code != I18N_ERROR_NONE) { + * printf("Error i18n_udate_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * error_code = i18n_udate_clone(format, &format_clone); + * if(error_code != I18N_ERROR_NONE) { + * printf("Error i18n_udate_clone : %d\n", error_code); + * i18n_udate_destroy(format); + * return EXIT_FAILURE; + * } + * i18n_udate_destroy(format_clone); + * i18n_udate_destroy(format); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_udate_clone(const i18n_udate_format_h format, i18n_udate_format_h *format_clone); @@ -354,6 +387,7 @@ int i18n_udate_set_lenient(i18n_udate_format_h format, i18n_ubool is_lenient); * @brief Gets the #i18n_ucalendar_h associated with an #i18n_udate_format_h. * @details An #i18n_udate_format_h uses an #i18n_ucalendar_h to convert a raw value to, for example, the day of the week. * @since_tizen 2.3.1 + * @remarks The @a calendar should not be released. * * @param[in] format The #i18n_udate_format_h to query. * @param[out] calendar A pointer to the #i18n_ucalendar_h used by format. @@ -386,6 +420,7 @@ int i18n_udate_set_calendar(i18n_udate_format_h format, const i18n_ucalendar_h c * @brief Gets the #i18n_unumber_format_h associated with an #i18n_udate_format_h. * @details An #i18n_udate_format_h uses an #i18n_unumber_format_h to format numbers within a date, for example the day number. * @since_tizen 2.3.1 + * @remarks The @a number_format should not be released. * * @param[in] format The formatter to query. * @param[out] number_format A pointer to the #i18n_unumber_format_h used by @a format to format numbers. diff --git a/src/include/utils_i18n_udatepg.h b/src/include/utils_i18n_udatepg.h index a38726a..09a3503 100644 --- a/src/include/utils_i18n_udatepg.h +++ b/src/include/utils_i18n_udatepg.h @@ -220,18 +220,36 @@ int i18n_udatepg_get_best_pattern(i18n_udatepg_h dtpg, const i18n_uchar *skeleto /** * @brief Creates an empty generator, to be constructed with i18n_udatepg_add_pattern() etc. * @since_tizen 2.3.1 + * @remarks The @a dtpg should be released using i18n_udatepg_destroy(). * * @param[out] dtpg A pointer to the #i18n_udatepg_h handle. * * @return The obtained error code. * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_error_code_e error_code; + * i18n_udatepg_h dtpg = NULL; + * error_code = i18n_udatepg_create_empty(&dtpg); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_udatepg_create_empty: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_udatepg_destroy(dtpg); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_udatepg_create_empty(i18n_udatepg_h *dtpg); /** * @brief Creates a copy of a generator. * @since_tizen 2.3.1 + * @remarks The @a dtpg should be released using i18n_udatepg_destroy(). * * @param[in] dtpg An #i18n_udatepg_h handle to be copied. Must not be @c NULL. * @param[out] dtpg_clone A pointer to clone of @a dtpg handle. @@ -239,6 +257,30 @@ int i18n_udatepg_create_empty(i18n_udatepg_h *dtpg); * @return The obtained error code. * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_error_code_e error_code; + * i18n_udatepg_h dtpg = NULL; + * i18n_udatepg_h dtpg_clone = NULL; + * error_code = i18n_udatepg_create_empty(&dtpg); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_udatepg_create_empty: %d\n", error_code); + * return EXIT_FAILURE; + * } + * error_code = i18n_udatepg_clone(dtpg, &dtpg_clone); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_udatepg_clone: %d\n", error_code); + * i18n_udatepg_destroy(dtpg); + * return EXIT_FAILURE; + * } + * i18n_udatepg_destroy(dtpg_clone); + * i18n_udatepg_destroy(dtpg); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_udatepg_clone(const i18n_udatepg_h dtpg, i18n_udatepg_h *dtpg_clone); @@ -587,6 +629,7 @@ int32_t i18n_udatepg_replace_field_types_with_options(i18n_udatepg_h dtpg, const * @brief Creates an #i18n_uenumeration_h for list of all the skeletons in canonical form. * @details Call i18n_udatepg_get_pattern_for_skeleton() to get the corresponding pattern. * @since_tizen 2.3.1 + * @remarks The @a enumeration should be released using i18n_uenumeration_destroy(). * * @param[in] dtpg An #i18n_udate_format_h handle. Must not be @c NULL. * @param[out] enumeration A pointer to the #i18n_uenumeration_h for list of all the skeletons. The caller must destroy the object. @@ -594,12 +637,37 @@ int32_t i18n_udatepg_replace_field_types_with_options(i18n_udatepg_h dtpg, const * @return The obtained error code. * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_error_code_e error_code; + * i18n_uenumeration_h skeletons = NULL; + * i18n_udatepg_h dtpg = NULL; + * error_code = i18n_udatepg_create_empty(&dtpg); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_udatepg_create_empty: %d\n", error_code); + * return EXIT_FAILURE; + * } + * error_code = i18n_udatepg_skeletons_create(dtpg, &skeletons); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_udatepg_skeletons_create: %d\n", error_code); + * i18n_udatepg_destroy(dtpg); + * return EXIT_FAILURE; + * } + * i18n_uenumeration_destroy(skeletons); + * i18n_udatepg_destroy(dtpg); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_udatepg_skeletons_create(const i18n_udatepg_h dtpg, i18n_uenumeration_h *enumeration); /** * @brief Creates an #i18n_uenumeration_h for list of all the base skeletons in canonical form. * @since_tizen 2.3.1 + * @remarks The @a enumeration should be released using i18n_uenumeration_destroy(). * * @param[in] dtpg An #i18n_udate_format_h handle. Must not be @c NULL. * @param[out] enumeration A pointer to the #i18n_uenumeration_h for list of all the base skeletons. The caller must destroy the object. @@ -607,6 +675,30 @@ int i18n_udatepg_skeletons_create(const i18n_udatepg_h dtpg, i18n_uenumeration_h * @return The obtained error code. * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_error_code_e error_code; + * i18n_uenumeration_h skeletons = NULL; + * i18n_udatepg_h dtpg = NULL; + * error_code = i18n_udatepg_create_empty(&dtpg); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_udatepg_create_empty: %d\n", error_code); + * return EXIT_FAILURE; + * } + * error_code = i18n_udatepg_base_skeletons_create(dtpg, &skeletons); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_udatepg_base_skeletons_create: %d\n", error_code); + * i18n_udatepg_destroy(dtpg); + * return EXIT_FAILURE; + * } + * i18n_uenumeration_destroy(skeletons); + * i18n_udatepg_destroy(dtpg); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_udatepg_base_skeletons_create(const i18n_udatepg_h dtpg, i18n_uenumeration_h *enumeration); diff --git a/src/include/utils_i18n_ulocale.h b/src/include/utils_i18n_ulocale.h index 195d283..65f2d43 100644 --- a/src/include/utils_i18n_ulocale.h +++ b/src/include/utils_i18n_ulocale.h @@ -179,6 +179,7 @@ extern "C" { * and unchanged even when i18n_ulocale_set_default() is called. * The returned storage is owned by I18N, and must not be altered or deleted by the caller. * @since_tizen 2.3 + * @remarks The @a locale should not be released. * * @param[out] locale The I18N default locale * diff --git a/src/include/utils_i18n_unormalization.h b/src/include/utils_i18n_unormalization.h index eda02cc..0e37a14 100644 --- a/src/include/utils_i18n_unormalization.h +++ b/src/include/utils_i18n_unormalization.h @@ -70,6 +70,7 @@ extern "C" { /** * @brief Gets a i18n_unormalizer_h which uses the specified data file and composes or decomposes text according to the specified mode. * @since_tizen 2.3 + * @remarks The @a normalizer should not be released. * * @param[in] package_name @c NULL for ICU built-in data, otherwise application data package name. * @param[in] name "nfc" or "nfkc" or "nfkc_cf" or the name of the custom data file. @@ -105,6 +106,7 @@ int i18n_unormalization_normalize(i18n_unormalizer_h normalizer, const i18n_ucha * @details Same as #i18n_unormalization_get_instance(NULL, "nfc", I18N_UNORM2_COMPOSE, n2). * Returns an unmodifiable singleton instance. Do not delete it. * @since_tizen 6.0 + * @remarks The @a normalizer should not be released. * @param[out] normalizer The requested #i18n_unormalizer_h, if successful * @return @c 0 on success, otherwise a negative error value * @retval #I18N_ERROR_NONE Successful @@ -119,6 +121,7 @@ int i18n_unormalization_get_nfc_instance(i18n_unormalizer_h* normalizer); * @details Same as #i18n_unormalization_get_instance(NULL, "nfc", I18N_UNORMALIZATION_DECOMPOSE, n2). * Returns an unmodifiable singleton instance. Do not delete it. * @since_tizen 6.0 + * @remarks The @a normalizer should not be released. * @param[out] normalizer The requested #i18n_unormalizer_h, if successful * @return @c 0 on success, otherwise a negative error value * @retval #I18N_ERROR_NONE Successful @@ -133,6 +136,7 @@ int i18n_unormalization_get_nfd_instance(i18n_unormalizer_h* normalizer); * @details Same as #i18n_unormalization_get_instance(NULL, "nfkc", I18N_UNORM2_COMPOSE, n2). * Returns an unmodifiable singleton instance. Do not delete it. * @since_tizen 6.0 + * @remarks The @a normalizer should not be released. * @param[out] normalizer The requested #i18n_unormalizer_h, if successful * @return @c 0 on success, otherwise a negative error value * @retval #I18N_ERROR_NONE Successful @@ -147,6 +151,7 @@ int i18n_unormalization_get_nfkc_instance(i18n_unormalizer_h* normalizer); * @details Same as #i18n_unormalization_get_instance(NULL, "nfkc", I18N_UNORMALIZATION_DECOMPOSE, n2). * Returns an unmodifiable singleton instance. Do not delete it. * @since_tizen 6.0 + * @remarks The @a normalizer should not be released. * @param[out] normalizer The requested #i18n_unormalizer_h, if successful * @return @c 0 on success, otherwise a negative error value * @retval #I18N_ERROR_NONE Successful @@ -161,6 +166,7 @@ int i18n_unormalization_get_nfkd_instance(i18n_unormalizer_h* normalizer); * @details Same as #i18n_unormalization_get_instance(NULL, "nfkc_cf", I18N_UNORM2_COMPOSE, n2). * Returns an unmodifiable singleton instance. Do not delete it. * @since_tizen 6.0 + * @remarks The @a normalizer should not be released. * @param[out] normalizer The requested #i18n_unormalizer_h, if successful * @return @c 0 on success, otherwise a negative error value * @retval #I18N_ERROR_NONE Successful diff --git a/src/include/utils_i18n_unumber.h b/src/include/utils_i18n_unumber.h index 62e3f78..70dd8e1 100644 --- a/src/include/utils_i18n_unumber.h +++ b/src/include/utils_i18n_unumber.h @@ -145,7 +145,8 @@ int i18n_unumber_get_symbol(const i18n_unumber_format_h fmt, i18n_unumber_format /** * @brief Creates a copy of an #i18n_unumber_format_h. * @details This function performs a deep copy. - * @remarks Error codes are described in #i18n_error_code_e description. + * @remarks Error codes are described in #i18n_error_code_e description.\n + * The @a fmt_clone should be released using i18n_unumber_destroy(). * @since_tizen 2.3.1 * * @param[in] fmt The format to copy. @@ -153,6 +154,31 @@ int i18n_unumber_get_symbol(const i18n_unumber_format_h fmt, i18n_unumber_format * @return The obtained error code. * @retval #I18N_ERROR_NONE Successful. * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_error_code_e error_code; + * i18n_unumber_format_h fmt = NULL; + * i18n_unumber_format_h fmt_clone = NULL; + * + * error_code = i18n_unumber_create(I18N_UNUMBER_DECIMAL, NULL, -1, I18N_ULOCALE_US, NULL, &fmt); + * if(error_code != I18N_ERROR_NONE) { + * printf("Error i18n_unumber_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * + * error_code = i18n_unumber_clone(fmt, &fmt_clone); + * if(error_code != I18N_ERROR_NONE) { + * printf("Error i18n_unumber_clone: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_unumber_destroy(fmt_clone); + * i18n_unumber_destroy(fmt); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_unumber_clone(const i18n_unumber_format_h fmt, i18n_unumber_format_h *fmt_clone); diff --git a/src/include/utils_i18n_unumsys.h b/src/include/utils_i18n_unumsys.h index 2d6cb6d..a23c257 100644 --- a/src/include/utils_i18n_unumsys.h +++ b/src/include/utils_i18n_unumsys.h @@ -72,12 +72,29 @@ int i18n_unumsys_create(const char *locale, i18n_unumsys_h *unumsys); * @brief Creates an #i18n_unumsys_h using the name of one of the predefined numbering systems specified by CLDR and known to ICU, * such as "latn", "arabext", or "hanidec"; the full list is returned by #i18n_unumsys_get_available_names. * @since_tizen 6.0 + * @remarks The @a unumsys should be released using i18n_unumsys_destroy(). * @param[in] name The name of the numbering system for which an #i18n_unumsys_h should be created. * @param[out] unumsys An #i18n_unumsys_h handle for the specified name, or NULL if an error occurred. * @return @c 0 on success, otherwise a negative error value * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_NOT_SUPPORTED A numbering system unknown to ICU. * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_unumsys_h unumsys; + * i18n_error_code_e error_code; + * error_code = i18n_unumsys_create("latn", &unumsys); + * if(error_code != I18N_ERROR_NONE) { + * printf("Error i18n_unumsys_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_unumsys_destroy(unumsys); + * return EXIT_SUCCESS; + * } + * @endcode * */ int i18n_unumsys_create_by_name(const char *name, i18n_unumsys_h *unumsys); @@ -95,18 +112,35 @@ void i18n_unumsys_destroy(i18n_unumsys_h unumsys); * @brief Returns an enumeration over the names of all of the predefined numbering systems known to ICU. * @details The numbering system names will be in alphabetical (invariant) order. * @since_tizen 6.0 + * @remarks The @a uenum should be released using i18n_uenumeration_destroy(). * @param[out] uenum A pointer to a #i18n_uenumeration_h that must be closed with #i18n_uenumeration_destroy(), or NULL if an error occurred. * @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 - * + * @code + * #include + * #include + * #include + * int main() { + * i18n_error_code_e error_code; + * i18n_uenumeration_h uenum; + * error_code = i18n_unumsys_get_available_names(&uenum); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_unumsys_get_available_names: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_uenumeration_destroy(uenum); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_unumsys_get_available_names(i18n_uenumeration_h *uenum); /** * @brief Returns the name of the specified #i18n_unumsys_h. * @since_tizen 6.0 + * @remarks The @a name should not be released. * @param[in] unumsys The #i18n_unumsys_h whose name is desired. * @param[out] name A pointer to the name of the specified #i18n_unumsys_h, or NULL if the name is not one of the ICU predefined names. * The pointer is only valid for the lifetime of the #i18n_unumsys_h. diff --git a/src/include/utils_i18n_ures.h b/src/include/utils_i18n_ures.h index 00f0ea8..ffb4295 100644 --- a/src/include/utils_i18n_ures.h +++ b/src/include/utils_i18n_ures.h @@ -139,7 +139,7 @@ int i18n_ures_get_version(i18n_ures_h ures, i18n_uversion_info version_array); * @brief Gets the name of the locale associated with @a ures. * You can choose between requested, valid and real locale. * @since_tizen 6.0 - * @remarks The @a locale is available until @a ures is released. + * @remarks The @a locale is available until @a ures is released. The @a locale should not be released. * @param[in] ures An #i18n_ures_h. * @param[in] type You can choose between requested, valid and actual locale. * For description see the definition of #i18n_ulocale_data_locale_type_e @@ -154,7 +154,7 @@ int i18n_ures_get_locale_by_type(i18n_ures_h ures, i18n_ulocale_data_locale_type /** * @brief Gets a string from an #i18n_ures_h. * @since_tizen 6.0 - * @remarks The @a str_result is available until @a ures is released. + * @remarks The @a str_result is available until @a ures is released. The @a str_result should not be released. * @param[in] ures An #i18n_ures_h. * @param[out] len The length of resulting string * @param[out] str_result The pointer to a zero-terminated #i18n_uchar array which lives in a memory mapped/DLL file. @@ -181,7 +181,7 @@ int i18n_ures_get_string(i18n_ures_h ures, int32_t *len, const i18n_uchar **str_ * If the string is transformed from UTF-16, then a conversion error may occur if an unpaired surrogate is encountered. * If the function is successful, then the output UTF-8 string is always well-formed. * @since_tizen 6.0 - * @remarks The @a str_result is available until @a ures is released. + * @remarks The @a str_result is available until @a ures is released. The @a str_result should not be released. * @param[in] ures Resource bundle. * @param[out] dest Destination buffer. Can be NULL only if capacity=*length==0. * @param[in,out] len Input: Capacity of destination buffer. @@ -207,7 +207,7 @@ int i18n_ures_get_UTF8_string(i18n_ures_h ures, char *dest, int32_t *len, i18n_u /** * @brief Gets a binary data from a binary resource. * @since_tizen 6.0 - * @remarks The @a binary_result is available until @a ures is released. + * @remarks The @a binary_result is available until @a ures is released. The @a binary_result should not be released. * @param[in] ures Resource bundle. * @param[out] len The length of resulting byte chunk * @param[out] binary_result A pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file. @@ -226,7 +226,7 @@ int i18n_ures_get_binary(i18n_ures_h ures, int32_t *len, const uint8_t **binary_ /** * @brief Gets a 32 bit integer array from a resource. * @since_tizen 6.0 - * @remarks The @a int_vector_result is available until @a ures is released. + * @remarks The @a int_vector_result is available until @a ures is released. The @a int_vector_result should not be released. * @param[in] ures Resource bundle. * @param[out] len The length of resulting byte chunk * @param[out] int_vector_result A pointer to a chunk of integers which live in a memory mapped/DLL file. @@ -308,7 +308,7 @@ int i18n_ures_get_type(i18n_ures_h ures, i18n_ures_type_e *type_result); * @brief Gets the key associated with a given resource. * Not all the resources have a key - only those that are members of a table. * @since_tizen 6.0 - * @remarks The @a key_result is available until @a ures is released. + * @remarks The @a key_result is available until @a ures is released. The @a key_result should not be released. * @param[in] ures Resource bundle. * @param[out] key_result A key associated to this resource, or NULL if it doesn't have a key * @return @c 0 on success, otherwise a negative error value @@ -365,8 +365,8 @@ int i18n_ures_get_next_resource(i18n_ures_h ures, i18n_ures_h fill_in, i18n_ures * @brief Gets the next string in a given resource * or NULL if there are no more resources to iterate over. * @since_tizen 6.0 - * @remarks The @a key is available until @a ures is released. - * @remarks The @a str_result is available until @a ures is released. + * @remarks The @a key is available until @a ures is released. The @a key should not be released. + * @remarks The @a str_result is available until @a ures is released. The @a str_result should not be released. * @param[in] ures Resource bundle. * @param[out] len Fill in length of the string * @param[out] key Fill in for key associated with this string. NULL if no key @@ -399,7 +399,7 @@ int i18n_ures_get_by_index(i18n_ures_h ures, int32_t index_r, i18n_ures_h fill_i /** * @brief Gets the string in a given resource at the specified index. * @since_tizen 6.0 - * @remarks The @a str_result is available until @a ures is released. + * @remarks The @a str_result is available until @a ures is released. The @a str_result should not be released. * @param[in] ures Resource bundle. * @param[in] index_s An index to the wanted string * @param[out] len Fill in length of the string @@ -424,7 +424,7 @@ int i18n_ures_get_string_by_index(i18n_ures_h ures, int32_t index_s, int32_t *le * If the string is transformed from UTF-16, then a conversion error may occur if an unpaired surrogate is encountered. * If the function is successful, then the output UTF-8 string is always well-formed. * @since_tizen 6.0 - * @remarks The @a str_result is available until @a ures is released. + * @remarks The @a str_result is available until @a ures is released. The @a str_result should not be released. * @param[in] ures Resource bundle. * @param[in] index_s An index to the wanted string * @param[out] dest Destination buffer. Can be NULL only if capacity=*length==0. @@ -470,7 +470,7 @@ int i18n_ures_get_by_key(i18n_ures_h ures, const char *key, i18n_ures_h fill_in, * @brief Gets a string in a given resource that has a given key. * This procedure works only with table resources. * @since_tizen 6.0 - * @remarks The @a str_result is available until @a ures is released. + * @remarks The @a str_result is available until @a ures is released. The @a str_result should not be released. * @param[in] ures Resource bundle. * @param[in] key A key associated with the wanted resource * @param[out] len Fills in length of the string diff --git a/src/include/utils_i18n_usearch.h b/src/include/utils_i18n_usearch.h index 81bb3ca..d5e09b2 100644 --- a/src/include/utils_i18n_usearch.h +++ b/src/include/utils_i18n_usearch.h @@ -142,6 +142,7 @@ int i18n_usearch_get_matched_text(const i18n_usearch_h search_iter, i18n_uchar * * i18n_usearch_destroy() would cause the string search to fail. * i18n_usearch_destroy() will delete the collator if this search owns it. * @since_tizen 2.3 + * @remarks The @a collator should not be released. * * @param[in] search_iter The search iterator handle * @param[out] collator The collator diff --git a/src/include/utils_i18n_uset.h b/src/include/utils_i18n_uset.h index d341f19..c35a285 100644 --- a/src/include/utils_i18n_uset.h +++ b/src/include/utils_i18n_uset.h @@ -53,12 +53,29 @@ extern "C" { * @details Equivalent to i18n_uset_create(1, 0). * * @since_tizen 2.3.1 + * @remarks The @a set should be released using i18n_uset_destroy(). * @param[out] set A pointer to the newly created #i18n_uset_h. The caller must call i18n_uset_destroy() on * it when done. * * @return Error code. Error codes not listed below are described in #i18n_error_code_e * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter + * @code + * #include + * #include + * #include + * int main() { + * i18n_uset_h uset = NULL; + * i18n_error_code_e error_code; + * error_code = i18n_uset_create_empty(&uset); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_uset_create_empty: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_uset_destroy(uset); + * return EXIT_SUCCESS; + * } + * @endcode * @see i18n_uset_destroy() */ int i18n_uset_create_empty(i18n_uset_h *set); @@ -70,6 +87,7 @@ int i18n_uset_create_empty(i18n_uset_h *set); * then an empty set is created (same as using i18n_uset_empty_create()). * * @since_tizen 2.3.1 + * @remarks The @a set should be released using i18n_uset_destroy(). * @param[in] start First character of the range, inclusive * @param[in] end Last character of the range, inclusive * @param[out] set A pointer to the newly created #i18n_uset_h object. The caller must call i18n_uset_destroy() on @@ -78,6 +96,25 @@ int i18n_uset_create_empty(i18n_uset_h *set); * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter * @see i18n_uset_destroy() + * @code + * #include + * #include + * #include + * int main() { + * i18n_uset_h set = NULL; + * i18n_uchar32 start = 0x41; + * i18n_uchar32 end = 0x50; + * + * i18n_error_code_e error_code; + * error_code = i18n_uset_create(start, end, &set); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_uset_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_uset_destroy(set); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_uset_create(i18n_uchar32 start, i18n_uchar32 end, i18n_uset_h *set); @@ -87,6 +124,7 @@ int i18n_uset_create(i18n_uchar32 start, i18n_uchar32 end, i18n_uset_h *set); * of the pattern language. * * @since_tizen 2.3.1 + * @remarks The @a set should be released using i18n_uset_destroy(). * @param[in] pattern A string specifying what characters are in the set * @param[in] pattern_length The length of the pattern, >= 0, or -1 if NULL-terminated. * @param[out] set A pointer to the newly created #i18n_uset_h object. The caller must call i18n_uset_destroy() on @@ -95,6 +133,29 @@ int i18n_uset_create(i18n_uchar32 start, i18n_uchar32 end, i18n_uset_h *set); * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter * @see i18n_uset_destroy() + * @code + * #include + * #include + * #include + * int main() { + * const char *pattern_ascii = "[:Hyphen:]"; + * i18n_uchar *pattern = NULL; + * i18n_uset_h set = NULL; + * i18n_error_code_e error_code; + * + * pattern = (i18n_uchar *)calloc(strlen(pattern_ascii), sizeof(i18n_uchar)); + * i18n_ustring_copy_ua(pattern, pattern_ascii); + * + * error_code = i18n_uset_create_pattern(pattern, 10, &set); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_uset_create_pattern: %d\n", error_code); + * return EXIT_FAILURE; + * } + * free(pattern); + * i18n_uset_destroy(set); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_uset_create_pattern(const i18n_uchar *pattern, int32_t pattern_length, i18n_uset_h *set); @@ -103,6 +164,7 @@ int i18n_uset_create_pattern(const i18n_uchar *pattern, int32_t pattern_length, * @details See the UnicodeSet class description for the syntax of the pattern language. * * @since_tizen 2.3.1 + * @remarks The @a set should be released using i18n_uset_destroy(). * @param[in] pattern A string specifying what characters are in the set * @param[in] pattern_length The length of the pattern, >= 0, or -1 if NULL-terminated * @param[in] options Bitmask for options to apply to the pattern. @@ -114,6 +176,30 @@ int i18n_uset_create_pattern(const i18n_uchar *pattern, int32_t pattern_length, * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter * @see i18n_uset_destroy() + * @code + * #include + * #include + * #include + * #include + * int main() { + * const char *pattern_ascii = "[:Hyphen:]"; + * i18n_uchar *pattern = NULL; + * i18n_uset_h set = NULL; + * i18n_error_code_e error_code; + * + * pattern = (i18n_uchar *)calloc(strlen(pattern_ascii) + 1, sizeof(i18n_uchar)); + * i18n_ustring_copy_ua(pattern, pattern_ascii); + * + * error_code = i18n_uset_create_pattern_options(pattern, strlen(pattern_ascii), I18N_USET_IGNORE_SPACE, &set); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_uset_create_pattern: %d\n", error_code); + * return EXIT_FAILURE; + * } + * free(pattern); + * i18n_uset_destroy(set); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_uset_create_pattern_options(const i18n_uchar *pattern, int32_t pattern_length, uint32_t options, i18n_uset_h *set); @@ -136,6 +222,7 @@ int i18n_uset_destroy(i18n_uset_h set); * Uses i18n_uset_clone_as_thawed() for a mutable clone of a frozen set. * * @since_tizen 2.3.1 + * @remarks The @a set_clone should be released using i18n_uset_destroy(). * @param[in] set The original set. Must not be @c NULL. * @param[out] set_clone The newly allocated copy of the set * @@ -143,6 +230,33 @@ int i18n_uset_destroy(i18n_uset_h set); * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter * @see i18n_uset_clone_as_thawed() + * @code + * #include + * #include + * #include + * int main() { + * i18n_uset_h uset = NULL; + * i18n_uset_h uset_c = NULL; + * i18n_uchar32 start = 0x41; + * i18n_uchar32 end = 0x50; + * i18n_error_code_e error_code; + * + * error_code = i18n_uset_create(start, end, &uset); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_uset_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * error_code = i18n_uset_clone(uset, &uset_c); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_uset_clone: %d\n", error_code); + * i18n_uset_destroy(uset); + * return EXIT_FAILURE; + * } + * i18n_uset_destroy(uset); + * i18n_uset_destroy(uset_c); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_uset_clone(const i18n_uset_h set, i18n_uset_h *set_clone); @@ -189,7 +303,7 @@ int i18n_uset_freeze(i18n_uset_h set); * @brief Clones the set and make the clone mutable. * @details See the ICU4J Freezable interface for details. * @since_tizen 2.3.1 - * + * @remarks The @a set_copy should be released using i18n_uset_destroy(). * @param[in] set The set. Must not be @c NULL. * @param[out] set_copy The mutable clone * @@ -199,6 +313,33 @@ int i18n_uset_freeze(i18n_uset_h set); * @see i18n_uset_freeze() * @see i18n_uset_is_frozen() * @see i18n_uset_clone() + * @code + * #include + * #include + * #include + * int main() { + * i18n_uset_h uset = NULL; + * i18n_uset_h uset_c = NULL; + * i18n_uchar32 start = 0x41; + * i18n_uchar32 end = 0x50; + * i18n_error_code_e error_code; + * + * error_code = i18n_uset_create(start, end, &uset); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_uset_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * error_code = i18n_uset_clone_as_thawed(uset, &uset_c); + * if (error_code!= I18N_ERROR_NONE) { + * printf("Error i18n_uset_clone_as_thawed: %d\n", error_code); + * i18n_uset_destroy(uset); + * return EXIT_FAILURE; + * } + * i18n_uset_destroy(uset); + * i18n_uset_destroy(uset_c); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_uset_clone_as_thawed(const i18n_uset_h set, i18n_uset_h *set_copy); diff --git a/src/include/utils_i18n_ustring.h b/src/include/utils_i18n_ustring.h index b5b7aaa..487a5f4 100644 --- a/src/include/utils_i18n_ustring.h +++ b/src/include/utils_i18n_ustring.h @@ -396,6 +396,7 @@ int32_t i18n_ustring_spn(const i18n_uchar *string, const i18n_uchar *match_set); * @details Works just like C's strspn but with Unicode. * @remarks The specific error code can be obtained using the get_last_result() method. * Error codes are described in Exceptions section. + * @remarks The @a save_state should not be released. * @since_tizen 2.3 * * @param[in] src String containing token(s). This string will be modified. After the first call to #i18n_ustring_tokenizer_r(), this argument must be NULL to get to the next token. diff --git a/src/include/utils_i18n_utext.h b/src/include/utils_i18n_utext.h index cc57863..7b83126 100644 --- a/src/include/utils_i18n_utext.h +++ b/src/include/utils_i18n_utext.h @@ -164,7 +164,23 @@ int i18n_utext_create_for_UTF8(i18n_utext_h uta, const char *s, int64_t length, * @retval #I18N_ERROR_NONE Successful * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter * @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory - * + * @code + * #include + * #include + * #include + * int main() { + * i18n_utext_h utb; + * i18n_error_code_e error_code; + * i18n_uchar uString[] = {0x41, 0x42, 0x43, 0}; + * error_code = i18n_utext_create_for_uchars(NULL, uString, -1, &utb); + * if (error_code != I18N_ERROR_NONE) { + * printf("Error i18n_uset_create: %d\n", error_code); + * return EXIT_FAILURE; + * } + * i18n_utext_destroy(utb); + * return EXIT_SUCCESS; + * } + * @endcode */ int i18n_utext_create_for_uchars(i18n_utext_h uta, const i18n_uchar *s, int64_t length, i18n_utext_h *utb); diff --git a/tests/utc-capi-base-utils-timezone.c b/tests/utc-capi-base-utils-timezone.c index 4dea1b2..1ef0f02 100644 --- a/tests/utc-capi-base-utils-timezone.c +++ b/tests/utc-capi-base-utils-timezone.c @@ -894,6 +894,7 @@ int utc_capi_base_utils_i18n_timezone_get_display_name_p(void) ret = i18n_timezone_get_display_name(timezone, &displayname); assert_eq(ret, I18N_ERROR_NONE); + free(displayname); ret = i18n_timezone_destroy(timezone); timezone = NULL; -- 2.34.1