* @defgroup CAPI_BASE_UTILS_I18N_TIMEZONE_MODULE Timezone
* @brief The Timezone module represents a time zone offset, and also figures out daylight savings.
* @section CAPI_BASE_UTILS_I18N_TIMEZONE_MODULE_HEADER Required Header
- * \#include <utils_i18n.h>
+ * \#include <utils_i18n.h>
*
* @section CAPI_BASE_UTILS_I18N_TIMEZONE_MODULE_OVERVIEW Overview
* @details The Timezone module represents a time zone offset, and also figures out daylight savings.\n
* @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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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);
* @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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ *
+ * 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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ *
+ * 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);
* 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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @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)
* @param[out] equivalent_timezone_id the ID of the index-th zone in the equivalency group containing 'timezone_id',
- * or an empty string if 'timezone_id' is not a valid system ID or 'index' is out of range
+ * or an empty string if 'timezone_id' is not a valid system ID or 'index' is out of range
*
* @retval #I18N_ERROR_NONE Successful
* @see i18n_timezone_count_equivalent_ids()
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ *
+ * 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);
* To query the system for the current timezone, use i18n_timezone_detect_host_timezone().
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ *
+ * 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);
/**
* @brief Returns the timezone data version currently used by I18N.
* @remarks The specific error code can be obtained using the get_last_result()
- * method. Error codes are described in #i18n_error_code_e description.
+ * method. Error codes are described in #i18n_error_code_e description.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @return the version string, such as "2007f"
* @param[out] region Output buffer for receiving the region code.
* @param[out] region_len The length of the region code.
* @param[in] region_capacity The size of the output buffer. If it is lower than required @a region buffer size,
- * then I18N_ERROR_BUFFER_OVERFLOW error is returned.
+ * then I18N_ERROR_BUFFER_OVERFLOW error is returned.
*
* @return the version string, such as "2007f"
*/
/**
* @brief Sets the i18n_timezone_h's raw GMT offset
- * (i.e., the number of milliseconds to add to GMT to get local time, before taking daylight savings time into account).
+ * (i.e., the number of milliseconds to add to GMT to get local time, before taking daylight savings time into account).
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @param[in] timezone The i18n_timezone_h to set a raw offset.
/**
* @brief Fills in "timezone_id" with the i18n_timezone_h's ID.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ *
+ * 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<code>
- * i18n_timezone_h timezone = NULL;\n
- * i18n_timezone_create ( &timezone, "America/New_York" );\n
- * i18n_timezone_set_id ( "America/Los_Angeles" );\n
- * </code>\n
+ * \n<code>
+ * i18n_timezone_h timezone = NULL;\n
+ * i18n_timezone_create ( &timezone, "America/New_York" );\n
+ * i18n_timezone_set_id ( "America/Los_Angeles" );\n
+ * </code>\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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
* @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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ *
+ * int main()
+ * {
+ * char *displayname;
+ * 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, &displayname);
+ * 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 displayname: %s\n", timezone_id, displayname);
+ * free(displayname);
+ * i18n_timezone_destroy(timezone);
+ * timezone = NULL;
+ * }
+ *
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
*/
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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @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.
* @param[out] display_name The human-readable name of this time zone in the default locale.
*
* @retval #I18N_ERROR_NONE Successful
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ *
+ * int main()
+ * {
+ * const char *language = I18N_ULOCALE_ENGLISH;
+ * const char *country = "US";
+ * char *displayname;
+ * 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, &displayname);
+ * 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 displayname: %s\n", timezone_id, displayname);
+ * free(displayname);
+ *
+ * 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;
* @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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @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.
* @param[out] display_name The human-readable name of this time zone in the default locale.
*
* @retval #I18N_ERROR_NONE Successful
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ *
+ * 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 *displayname;
+ * 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, &displayname);
+ * 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 displayname: %s\n", timezone_id, displayname);
+ * free(displayname);
+ * }
+ *
+ * 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);
* @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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @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.
* @param[out] display_name The human-readable name of this time zone in the default locale.
*
* @retval #I18N_ERROR_NONE Successful
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ *
+ * 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 *displayname;
+ *
+ * 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, &displayname);
+ * 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 displayname: %s\n", timezone_id, displayname);
+ *
+ * i18n_timezone_destroy(timezone);
+ * free(displayname);
+ * 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;
* @brief Clones i18n_timezone_h polymorphically.
* @details Clients are responsible for deleting the i18n_timezone_h cloned.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ *
+ * 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);
* 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
*
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ *
+ * 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);
/**
* @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.
* 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
* @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_itr 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
* @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.
* @brief Creates a copy of a #i18n_ucalendar_h.
* This function performs a deep copy.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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);
/**
* @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
* @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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.
* @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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);
* @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
*
* @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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);
* 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
* @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ *
+ * 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);
* @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.
* 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
* "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
* <code>#I18N_UCHAR_BINARY_START <= @a property < #I18N_UCHAR_BINARY_LIMIT</code> or
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
* @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ *
+ * int main() {
+ * i18n_error_code_e error_code;
+ * i18n_uchar_iter_h uchar_iter = NULL;
+ * error_code = i18n_uchar_iter_create(&uchar_iter);
+ * if (error_code != I18N_ERROR_NONE) {
+ * printf("Error i18n_uchar_iter_create: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ * i18n_uchar_iter_destroy(uchar_iter);
+ * return EXIT_SUCCESS;
+ * }
+ *
+ * @endcode
*/
int i18n_uchar_iter_create(i18n_uchar_iter_h *iter);
* @see i18n_ucnv_get_default_name()
* @see i18n_ucnv_destroy()
* @see i18n_ucnv_compare_names()
- *
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * int main() {
+ * i18n_ucnv_h cnv;
+ * i18n_error_code_e error_code;
+ * error_code = i18n_ucnv_create("ibm-949", &cnv);
+ * if (error_code!= I18N_ERROR_NONE) {
+ * printf("Error i18n_ucnv_create: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ * i18n_ucnv_destroy(cnv);
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
*/
int i18n_ucnv_create(const char *converter_name, i18n_ucnv_h *converter);
* @see i18n_ucnv_destroy()
* @see i18n_ucnv_compare_names()
*
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * int main() {
+ * i18n_ucnv_h cnv;
+ * i18n_error_code_e error_code;
+ * i18n_uchar converter_name[] = {0x0069, 0x0062, 0x006d, 0x002d, 0x0039, 0x0034, 0x0033, 0x0000};
+ * error_code = i18n_ucnv_create_unicode(converter_name, &cnv);
+ * if (error_code!= I18N_ERROR_NONE) {
+ * printf("Error i18n_ucnv_create: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ * i18n_ucnv_destroy(cnv);
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
*/
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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * int main() {
+ * i18n_ucnv_h cnv;
+ * 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, &cnv);
+ * if (error_code!= I18N_ERROR_NONE) {
+ * printf("Error i18n_ucnv_create_ccsid: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ * i18n_ucnv_destroy(cnv);
+ * }
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
*/
int i18n_ucnv_create_ccsid(int32_t codepage, i18n_ucnv_platform_e platform, i18n_ucnv_h *converter);
* @see i18n_ucnv_create()
* @see i18n_ucnv_safe_clone()
*
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * int main() {
+ * i18n_ucnv_h cnv;
+ * i18n_error_code_e error_code;
+ * error_cod e= i18n_ucnv_create_package("", "", &cnv);
+ * if (error_code!= I18N_ERROR_NONE) {
+ * printf("Error i18n_ucnv_create_package: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ * i18n_ucnv_destroy(cnv);
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
*/
int i18n_ucnv_create_package(const char *package_name, const char *converter_name, i18n_ucnv_h *converter);
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * int main() {
+ * i18n_ucnv_h cnv;
+ * i18n_ucnv_h cnv2;
+ * i18n_error_code_e error_code;
+ * error_code= i18n_ucnv_create("iso-8859-3", &cnv);
+ * if (error_code!= I18N_ERROR_NONE) {
+ * printf("Error i18n_ucnv_create: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ * error_code= i18n_ucnv_safe_clone(cnv, &cnv2);
+ * if (error_code!= I18N_ERROR_NONE) {
+ * printf("Error i18n_ucnv_safe_clone: %d\n", error_code);
+ * i18n_ucnv_destroy(cnv);
+ * return EXIT_FAILURE;
+ * }
+ * i18n_ucnv_destroy(cnv);
+ * i18n_ucnv_destroy(cnv2);
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
*/
int i18n_ucnv_safe_clone(i18n_ucnv_h converter, i18n_ucnv_h *cloned_converter);
* @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 len;
+ *
+ * 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_ustring_from_UTF8((i18n_uchar *)string, I18N_UPRV_LENGTHOF(string), &len, 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);
+ * i18n_uenumeration_destroy(enumeration);
+ * return EXIT_FAILURE;
+ * }
+ *
+ * error_code = i18n_ucnvsel_select_for_string(sel, string, len, &enumeration);
+ * if (error_code!= I18N_ERROR_NONE) {
+ * printf("Error i18n_ucnvsel_select_for_string: %d\n", error_code);
+ * i18n_uenumeration_destroy(enumeration);
+ * 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);
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
*
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * #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, 5, &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);
* 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
* @see i18n_ucollator_create()
* @see i18n_ucollator_safe_clone()
* @see i18n_ucollator_destroy()
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * int main() {
+ * i18n_error_code_e error_code;
+ * i18n_ucollator_h coll = NULL;
+ * i18n_uparse_error_s parse_error;
+ * i18n_uchar uchar_rules[128];
+ *
+ * i18n_ustring_copy_ua(uchar_rules, rules);
+ * error_code = i18n_ucollator_create_rules(uchar_rules, -1, I18N_UCOLLATOR_ON, I18N_UCOLLATOR_DEFAULT_STRENGTH,
+ * &parse_error, &coll);
+ * if (error_code!= I18N_ERROR_NONE) {
+ * printf("Error i18n_ucollator_create_rules: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ * i18n_ucollator_destroy(coll);
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
*/
int i18n_ucollator_create_rules(const i18n_uchar *rules,
int32_t rules_length,
* @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
+ * const char *locale = NULL;
+ * int32_t locale_index = 0;
+ *
+ * i18n_ucollator_get_available(locale_index, &locale);
+ * @endcode
*/
int i18n_ucollator_get_available(int32_t locale_index, const char **locale);
/**
* @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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);
* @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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);
* @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
*
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * int main() {
+ * i18n_error_code_e error_code;
+ * i18n_uenumeration_h keyword_values;
+ *
+ * error_code = i18n_ucollator_get_keyword_values("collation", &keyword_values);
+ * if (error_code!= I18N_ERROR_NONE) {
+ * printf("Error i18n_ucollator_get_keyword_values: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ * i18n_uenumeration_destroy(keyword_values);
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
*/
int i18n_ucollator_get_keyword_values(const char *keyword, i18n_uenumeration_h *keywords);
* 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
*
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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,
* @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
/**
* @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
* @see i18n_ucollator_create()
* @see i18n_ucollator_create_rules()
* @see i18n_ucollator_destroy()
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * int main() {
+ * i18n_error_code_e error_code;
+ * i18n_ucollator_h coll = NULL;
+ * i18n_ucollator_h clone_coll = NULL;
+ *
+ * error_code = i18n_ucollator_create("en_US", &coll );
+ * if (error_code!= I18N_ERROR_NONE) {
+ * printf("Error i18n_ucollator_create: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ * error_code = i18n_ucollator_safe_clone(coll, &clone_coll);
+ * if (error_code!= I18N_ERROR_NONE) {
+ * printf("Error i18n_ucollator_safe_clone: %d\n", error_code);
+ * i18n_ucollator_destroy(coll);
+ * return EXIT_FAILURE;
+ * }
+ * i18n_ucollator_destroy(coll);
+ * i18n_ucollator_destroy(clone_coll);
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
*/
int i18n_ucollator_safe_clone(i18n_ucollator_h collator, i18n_ucollator_h *clone);
* @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
* @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
* @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.
* @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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 clone = NULL;
+ *
+ * error_code = i18n_udate_create(time_style, date_style, locale, tz_id, tz_id_length, pattern, pattern_length, &format);
+ * if(I18N_ERROR_NONE != error_code) {
+ * printf("Error i18n_udate_create: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ *
+ * error_code = i18n_udate_clone(format, &clone);
+ * if(I18N_ERROR_NONE != error_code) {
+ * printf("Error i18n_udate_clone : %d\n", error_code);
+ * i18n_udate_destroy(format);
+ * return EXIT_FAILURE;
+ * }
+ * i18n_udate_destroy(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);
* @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.
* @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.
/**
* @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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.
* @return The obtained error code.
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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);
+ * i18n_udatepg_destroy(dtpg_clone);
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
*/
int i18n_udatepg_clone(const i18n_udatepg_h dtpg, i18n_udatepg_h *dtpg_clone);
* @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.
* @return The obtained error code.
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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.
* @return The obtained error code.
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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);
* 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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @remarks The @a locale should not be released.
*
* @param[out] locale The I18N default locale
*
/**
* @brief Gets a i18n_unormalizer_h which uses the specified data file and composes or decomposes text according to the specified mode.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @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.
* @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
* @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
* @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
* @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
* @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
/**
* @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.
* @return The obtained error code.
* @retval #I18N_ERROR_NONE Successful.
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * int main() {
+ * i18n_error_code_e error_code;
+ * i18n_unumber_format_h num_format = NULL;
+ * i18n_unumber_format_h num_format_clone = NULL;
+ *
+ * error_code = i18n_unumber_create(I18N_UNUMBER_DECIMAL, NULL, -1, I18N_ULOCALE_US, NULL, &num_format);
+ * if(I18N_ERROR_NONE != error_code) {
+ * printf("Error i18n_unumber_create: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ *
+ * error_code = i18n_unumber_clone(num_format, &num_format_clone);
+ * if(I18N_ERROR_NONE != error_code) {
+ * printf("Error i18n_unumber_clone: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ * i18n_unumber_destroy(num_format_clone);
+ * i18n_unumber_destroy(num_format);
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
*/
int i18n_unumber_clone(const i18n_unumber_format_h fmt, i18n_unumber_format_h *fmt_clone);
* @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * int main() {
+ * i18n_unumsys_h unumsys;
+ * i18n_error_code_e error_code;
+ * error_code = i18n_unumsys_create("latn", &unumsys);
+ * if(I18N_ERROR_NONE != error_code) {
+ * 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);
* @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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.
* @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
/**
* @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.
* 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.
/**
* @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.
/**
* @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.
* @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
* @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
/**
* @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
* 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.
* @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
* i18n_usearch_destroy() would cause the string search to fail.
* i18n_usearch_destroy() will delete the collator if this search owns it.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @remarks The @a collator should not be released.
*
* @param[in] search_iter The search iterator handle
* @param[out] collator The collator
* @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 <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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);
* 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
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
* @see i18n_uset_destroy()
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * int main() {
+ * i18n_uset_h uset = 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;
+ * }
+ * i18n_uset_destroy(uset);
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
*/
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
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
* @see i18n_uset_destroy()
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * int main() {
+ * const char *pattern = "[:Hyphen:]";
+ * i18n_uchar *_pattern = NULL;
+ * i18n_uset_h uset = NULL;
+ * i18n_error_code_e error_code;
+ *
+ * _pattern = (i18n_uchar *)calloc(strlen(pattern) + 1, sizeof(i18n_uchar));
+ * i18n_ustring_copy_ua(_pattern, pattern);
+ *
+ * error_code = i18n_uset_create_pattern(_pattern, 10, &uset);
+ * if (error_code!= I18N_ERROR_NONE) {
+ * printf("Error i18n_uset_create_pattern: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ * free(_pattern);
+ * i18n_uset_destroy(uset);
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
*/
int i18n_uset_create_pattern(const i18n_uchar *pattern, int32_t pattern_length, i18n_uset_h *set);
* @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.
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
* @see i18n_uset_destroy()
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * int main() {
+ * const char *pattern = "[:Hyphen:]";
+ * i18n_uchar *_pattern = NULL;
+ * i18n_uset_h uset = NULL;
+ * i18n_error_code_e error_code;
+ *
+ * _pattern = (i18n_uchar *)calloc(strlen(pattern) + 1, sizeof(i18n_uchar));
+ * i18n_ustring_copy_ua(_pattern, pattern);
+ *
+ * error_code = i18n_uset_create_pattern_options(_pattern, 10, I18N_USET_IGNORE_SPACE, &uset);
+ * if (error_code!= I18N_ERROR_NONE) {
+ * printf("Error i18n_uset_create_pattern: %d\n", error_code);
+ * return EXIT_FAILURE;
+ * }
+ * free(_pattern);
+ * i18n_uset_destroy(uset);
+ * 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);
* 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
*
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
* @see i18n_uset_clone_as_thawed()
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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);
* @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
*
* @see i18n_uset_freeze()
* @see i18n_uset_is_frozen()
* @see i18n_uset_clone()
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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);
* @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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @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.
* @retval #I18N_ERROR_NONE Successful
* @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
* @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
- *
+ * @code
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <utils_i18n.h>
+ * 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);
ret = i18n_timezone_get_display_name(timezone, &displayname);
assert_eq(ret, I18N_ERROR_NONE);
+ free(displayname);
ret = i18n_timezone_destroy(timezone);
timezone = NULL;
projects / platform / core / api / base-utils.git / commitdiff