From: Damian Pietruchowski Date: Wed, 28 Jun 2017 10:14:16 +0000 (+0200) Subject: [Base-utils][Ulocale] Add missing module description X-Git-Tag: accepted/tizen/unified/20170710.154206^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F81%2F136181%2F3;p=platform%2Fcore%2Fapi%2Fbase-utils.git [Base-utils][Ulocale] Add missing module description Change-Id: I57f5a43c45ac449d8991822ea7a4992ab0bc1f9d Signed-off-by: Damian Pietruchowski --- diff --git a/src/include/utils_i18n_ulocale.h b/src/include/utils_i18n_ulocale.h index b4078cf..90c8416 100644 --- a/src/include/utils_i18n_ulocale.h +++ b/src/include/utils_i18n_ulocale.h @@ -36,12 +36,79 @@ * \#include * * @section CAPI_BASE_UTILS_I18N_ULOCALE_MODULE_OVERVIEW Overview - * @details A Locale represents a specific geographical, political, or cultural region. - * An operation that requires a Locale to perform its task is called locale-sensitive + * @details An operation that requires a Locale to perform its task is called locale-sensitive * and uses the Locale to tailor information for the user. For example, displaying * a number is a locale-sensitive operation. The number should be formatted according * to the customs/conventions of the user's native country, region, or culture. - * In the C APIs, a locale is simply a const char string. + * A locale is simply a const char string.\n + * You create a Locale with one of the three options listed below. Each of the component is + * separated by '_' in the locale string. + * + * newLanguage + * newLanguage + newCountry + * newLanguage + newCountry + newVariant + * + * The first option is a valid ISO Language Code. These codes are the lower-case two-letter + * codes as defined by ISO-639. + * The second option includes an additional ISO Country Code. These codes are the + * upper-case two-letter codes as defined by ISO-3166. You can find a full list of these + * codes at a number of sites, such as: http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html + * The third option requires another additional information–the Variant. The Variant codes + * are vendor and browser-specific. For example, use WIN for Windows, MAC for Macintosh, + * and POSIX for POSIX. Where there are two variants, separate them with an underscore, + * and put the most important one first. For example, a Traditional Spanish collation + * might be referenced, with "ES", "ES", "Traditional_WIN". + * Because a Locale is just an identifier for a region, no validity check is performed + * when you specify a Locale. If you want to see whether particular resources are available + * for the Locale you asked for, you must query those resources. For example, + * to create #i18n_ucollator_h object use i18n_ucollator_get_available() function for + * supported locales. Note: When you ask for a resource for a particular locale, + * you get back the best available match, not necessarily precisely what you asked for.\n + * The Locale provides a number of convenient constants that you can use to specify the + * commonly used locales. For example, the following refers to a locale for the United States: + * #I18N_ULOCALE_US\n + * Once you've specified a locale you can query it for information about itself. + * Use i18n_ulocale_get_country() to get the ISO Country Code and i18n_ulocale_get_language() + * to get the ISO Language Code. You can use i18n_ulocale_get_display_country() to get + * the name of the country suitable for displaying to the user. Similarly, you can use + * i18n_ulocale_get_display_language() to get the name of the language suitable for + * displaying to the user. Interestingly, the i18n_ulocale_get_display_xxx() methods are + * themselves locale-sensitive and have two versions: one that uses the default locale + * and one that takes a locale as an argument and displays the name or country in a language + * appropriate to that locale.\n + * The ICU provides a number of services that perform locale-sensitive operations. + * For example, the i18n_unumber_xxx functions format numbers, currency, or percentages + * in a locale-sensitive manner. Each of these functions has two variants; + * one with an explicit locale and one without:\n + * + * i18n_unumber_format_h num_format = NULL; + * int error_code = i18n_unumber_create(I18N_UNUMBER_CURRENCY, NULL, -1, "fr_FR", NULL, &num_format); + * \n + * the latter using the default locale:\n + * + * i18n_unumber_format_h num_format = NULL; + * int error_code = i18n_unumber_create(I18N_UNUMBER_CURRENCY, NULL, -1, NULL, NULL, &num_format); + * \n + * A Locale is the mechanism for identifying the kind of services that you would like + * to get. The locale is just a mechanism for identifying these services.\n + * Each international service that performs locale-sensitive operations allows you to get + * all the available objects of that type. You can sift through these objects by language, + * country, or variant, and use the display names to present a menu to the user. + * For example, you can create a menu of all the collation objects suitable for a given + * language. Such modules implement these two functions: i18n_xxx_get_available(), + * i18n_xxx_count_available(). Some of them has also i18n_xxx_get_display_name().\n + * Concerning POSIX/RFC1766 Locale IDs, the + * i18n_locale_get_language()/i18n_ulocale_get_country()/i18n_ulocale_get_variant()/i18n_ulocale_get_name() + * functions do understand the POSIX type form of language_COUNTRY.ENCODING@VARIANT and + * if there is not an ICU-stype variant, i18n_ulocale_get_variant() for example will return + * the one listed after the @at sign. As well, the hyphen "-" is recognized as + * a country/variant separator similarly to RFC1766. So for example, "en-us" will be + * interpreted as en_US. As a result, i18n_ulocale_get_name() is far from a no-op, + * and will have the effect of converting POSIX/RFC1766 IDs into ICU form, although it + * does NOT map any of the actual codes (i.e. russian->ru) in any way. Applications should + * call i18n_ulocale_get_name() at the point where a locale ID is coming from an external + * source (user entry, OS, web browser) and pass the resulting string to other ICU + * functions. For example, don't use de-de@EURO as an argument to resourcebundle. * * @section CAPI_BASE_UTILS_I18N_ULOCALE_MODULE_SAMPLE_CODE_1 Sample Code 1 * @brief Gets a default locale and a full name for the locale