#include "unicode/utypes.h"
#include "unicode/uenum.h"
Go to the source code of this file.
Defines | |
#define | ULOC_CHINESE "zh" |
Useful constant for this language. | |
#define | ULOC_ENGLISH "en" |
Useful constant for this language. | |
#define | ULOC_FRENCH "fr" |
Useful constant for this language. | |
#define | ULOC_GERMAN "de" |
Useful constant for this language. | |
#define | ULOC_ITALIAN "it" |
Useful constant for this language. | |
#define | ULOC_JAPANESE "ja" |
Useful constant for this language. | |
#define | ULOC_KOREAN "ko" |
Useful constant for this language. | |
#define | ULOC_SIMPLIFIED_CHINESE "zh_CN" |
Useful constant for this language. | |
#define | ULOC_TRADITIONAL_CHINESE "zh_TW" |
Useful constant for this language. | |
#define | ULOC_CANADA "en_CA" |
Useful constant for this country/region. | |
#define | ULOC_CANADA_FRENCH "fr_CA" |
Useful constant for this country/region. | |
#define | ULOC_CHINA "zh_CN" |
Useful constant for this country/region. | |
#define | ULOC_PRC "zh_CN" |
Useful constant for this country/region. | |
#define | ULOC_FRANCE "fr_FR" |
Useful constant for this country/region. | |
#define | ULOC_GERMANY "de_DE" |
Useful constant for this country/region. | |
#define | ULOC_ITALY "it_IT" |
Useful constant for this country/region. | |
#define | ULOC_JAPAN "ja_JP" |
Useful constant for this country/region. | |
#define | ULOC_KOREA "ko_KR" |
Useful constant for this country/region. | |
#define | ULOC_TAIWAN "zh_TW" |
Useful constant for this country/region. | |
#define | ULOC_UK "en_GB" |
Useful constant for this country/region. | |
#define | ULOC_US "en_US" |
Useful constant for this country/region. | |
#define | ULOC_LANG_CAPACITY 12 |
Useful constant for the maximum size of the language part of a locale ID. | |
#define | ULOC_COUNTRY_CAPACITY 4 |
Useful constant for the maximum size of the country part of a locale ID (including the terminating NULL). | |
#define | ULOC_FULLNAME_CAPACITY 56 |
Useful constant for the maximum size of the whole locale ID (including the terminating NULL). | |
#define | ULOC_SCRIPT_CAPACITY 6 |
Useful constant for the maximum size of the script part of a locale ID (including the terminating NULL). | |
#define | ULOC_KEYWORDS_CAPACITY 50 |
Useful constant for the maximum size of keywords in a locale. | |
#define | ULOC_KEYWORD_AND_VALUES_CAPACITY 100 |
Useful constant for the maximum SIZE of keywords in a locale. | |
#define | ULOC_KEYWORD_SEPARATOR '@' |
Character separating keywords from the locale string different for EBCDIC - TODO. | |
#define | ULOC_KEYWORD_ASSIGN '=' |
Character for assigning value to a keyword. | |
#define | ULOC_KEYWORD_ITEM_SEPARATOR ';' |
Character separating keywords. | |
Enumerations | |
enum | ULocDataLocaleType { ULOC_ACTUAL_LOCALE = 0, ULOC_VALID_LOCALE = 1, ULOC_REQUESTED_LOCALE = 2, ULOC_DATA_LOCALE_TYPE_LIMIT = 3 } |
Constants for *_getLocale() Allow user to select whether she wants information on requested, valid or actual locale. More... | |
enum | ULayoutType { ULOC_LAYOUT_LTR = 0, ULOC_LAYOUT_RTL = 1, ULOC_LAYOUT_TTB = 2, ULOC_LAYOUT_BTT = 3, ULOC_LAYOUT_UNKNOWN } |
enums for the return value for the character and line orientation functions. More... | |
enum | UAcceptResult { ULOC_ACCEPT_FAILED = 0, ULOC_ACCEPT_VALID = 1, ULOC_ACCEPT_FALLBACK = 2 } |
enums for the 'outResult' parameter return value More... | |
Functions | |
const char * | uloc_getDefault (void) |
Gets ICU's default locale. | |
void | uloc_setDefault (const char *localeID, UErrorCode *status) |
Sets ICU's default locale. | |
int32_t | uloc_getLanguage (const char *localeID, char *language, int32_t languageCapacity, UErrorCode *err) |
Gets the language code for the specified locale. | |
int32_t | uloc_getScript (const char *localeID, char *script, int32_t scriptCapacity, UErrorCode *err) |
Gets the script code for the specified locale. | |
int32_t | uloc_getCountry (const char *localeID, char *country, int32_t countryCapacity, UErrorCode *err) |
Gets the country code for the specified locale. | |
int32_t | uloc_getVariant (const char *localeID, char *variant, int32_t variantCapacity, UErrorCode *err) |
Gets the variant code for the specified locale. | |
int32_t | uloc_getName (const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err) |
Gets the full name for the specified locale. | |
int32_t | uloc_canonicalize (const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err) |
Gets the full name for the specified locale. | |
const char * | uloc_getISO3Language (const char *localeID) |
Gets the ISO language code for the specified locale. | |
const char * | uloc_getISO3Country (const char *localeID) |
Gets the ISO country code for the specified locale. | |
uint32_t | uloc_getLCID (const char *localeID) |
Gets the Win32 LCID value for the specified locale. | |
int32_t | uloc_getDisplayLanguage (const char *locale, const char *displayLocale, UChar *language, int32_t languageCapacity, UErrorCode *status) |
Gets the language name suitable for display for the specified locale. | |
int32_t | uloc_getDisplayScript (const char *locale, const char *displayLocale, UChar *script, int32_t scriptCapacity, UErrorCode *status) |
Gets the script name suitable for display for the specified locale. | |
int32_t | uloc_getDisplayCountry (const char *locale, const char *displayLocale, UChar *country, int32_t countryCapacity, UErrorCode *status) |
Gets the country name suitable for display for the specified locale. | |
int32_t | uloc_getDisplayVariant (const char *locale, const char *displayLocale, UChar *variant, int32_t variantCapacity, UErrorCode *status) |
Gets the variant name suitable for display for the specified locale. | |
int32_t | uloc_getDisplayKeyword (const char *keyword, const char *displayLocale, UChar *dest, int32_t destCapacity, UErrorCode *status) |
Gets the keyword name suitable for display for the specified locale. | |
int32_t | uloc_getDisplayKeywordValue (const char *locale, const char *keyword, const char *displayLocale, UChar *dest, int32_t destCapacity, UErrorCode *status) |
Gets the value of the keyword suitable for display for the specified locale. | |
int32_t | uloc_getDisplayName (const char *localeID, const char *inLocaleID, UChar *result, int32_t maxResultSize, UErrorCode *err) |
Gets the full name suitable for display for the specified locale. | |
const char * | uloc_getAvailable (int32_t n) |
Gets the specified locale from a list of all available locales. | |
int32_t | uloc_countAvailable (void) |
Gets the size of the all available locale list. | |
const char *const * | uloc_getISOLanguages (void) |
Gets a list of all available language codes defined in ISO 639. | |
const char *const * | uloc_getISOCountries (void) |
Gets a list of all available 2-letter country codes defined in ISO 639. | |
int32_t | uloc_getParent (const char *localeID, char *parent, int32_t parentCapacity, UErrorCode *err) |
Truncate the locale ID string to get the parent locale ID. | |
int32_t | uloc_getBaseName (const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err) |
Gets the full name for the specified locale. | |
UEnumeration * | uloc_openKeywords (const char *localeID, UErrorCode *status) |
Gets an enumeration of keywords for the specified locale. | |
int32_t | uloc_getKeywordValue (const char *localeID, const char *keywordName, char *buffer, int32_t bufferCapacity, UErrorCode *status) |
Get the value for a keyword. | |
int32_t | uloc_setKeywordValue (const char *keywordName, const char *keywordValue, char *buffer, int32_t bufferCapacity, UErrorCode *status) |
Set the value of the specified keyword. | |
ULayoutType | uloc_getCharacterOrientation (const char *localeId, UErrorCode *status) |
Get the layout character orientation for the specified locale. | |
ULayoutType | uloc_getLineOrientation (const char *localeId, UErrorCode *status) |
Get the layout line orientation for the specified locale. | |
int32_t | uloc_acceptLanguageFromHTTP (char *result, int32_t resultAvailable, UAcceptResult *outResult, const char *httpAcceptLanguage, UEnumeration *availableLocales, UErrorCode *status) |
Based on a HTTP header from a web browser and a list of available locales, determine an acceptable locale for the user. | |
int32_t | uloc_acceptLanguage (char *result, int32_t resultAvailable, UAcceptResult *outResult, const char **acceptList, int32_t acceptListCount, UEnumeration *availableLocales, UErrorCode *status) |
Based on a list of available locales, determine an acceptable locale for the user. | |
int32_t | uloc_getLocaleForLCID (uint32_t hostID, char *locale, int32_t localeCapacity, UErrorCode *status) |
Gets the ICU locale ID for the specified Win32 LCID value. | |
int32_t | uloc_addLikelySubtags (const char *localeID, char *maximizedLocaleID, int32_t maximizedLocaleIDCapacity, UErrorCode *err) |
Add the likely subtags for a provided locale ID, per the algorithm described in the following CLDR technical report:. | |
int32_t | uloc_minimizeSubtags (const char *localeID, char *minimizedLocaleID, int32_t minimizedLocaleIDCapacity, UErrorCode *err) |
Minimize the subtags for a provided locale ID, per the algorithm described in the following CLDR technical report:. |
A Locale
represents a specific geographical, political, or cultural region. 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 locales is simply a const char string.
You create a Locale
with one of the three options listed below. Each of the component is separated by '_' in the locale string.
The first option is a valid ISO Language Code. These codes are the lower-case two-letter codes as defined by ISO-639. You can find a full list of these codes at a number of sites, such as:newLanguage newLanguage + newCountry newLanguage + newCountry + newVariant
The second option includes an additonal 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 additonal 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, ask the UNumberFormat
for the locales it supports using its getAvailable
method.
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. For more information, look at UResourceBundle
.
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:
Once you've specified a locale you can query it for information about itself. Use uloc_getCountry
to get the ISO Country Code and uloc_getLanguage
to get the ISO Language Code. You can use uloc_getDisplayCountry
to get the name of the country suitable for displaying to the user. Similarly, you can use uloc_getDisplayLanguage
to get the name of the language suitable for displaying to the user. Interestingly, the uloc_getDisplayXXX
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.
The ICU provides a number of services that perform locale-sensitive operations. For example, the unum_xxx
functions format numbers, currency, or percentages in a locale-sensitive manner.
Each of these methods has two variants; one with an explicit locale and one without; the latter using the default locale.UErrorCode success = U_ZERO_ERROR; UNumberFormat *nf; const char* myLocale = "fr_FR"; nf = unum_open( UNUM_DEFAULT, NULL, success ); unum_close(nf); nf = unum_open( UNUM_CURRENCY, NULL, success ); unum_close(nf); nf = unum_open( UNUM_PERCENT, NULL, success ); unum_close(nf);
Anf = unum_open( UNUM_DEFAULT, myLocale, success ); unum_close(nf); nf = unum_open( UNUM_CURRENCY, myLocale, success ); unum_close(nf); nf = unum_open( UNUM_PERCENT, myLocale, success ); unum_close(nf);
Locale
is the mechanism for identifying the kind of services (UNumberFormat
) that you would like to get. The locale is just a mechanism for identifying these services.Each international serivce 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 classes implement these three class methods:
const char* uloc_getAvailable(int32_t index); int32_t uloc_countAvailable(); int32_t uloc_getDisplayName(const char* localeID, const char* inLocaleID, UChar* result, int32_t maxResultSize, UErrorCode* err);
Concerning POSIX/RFC1766 Locale IDs, the getLanguage/getCountry/getVariant/getName functions do understand the POSIX type form of language_COUNTRY.ENCODING@VARIANT and if there is not an ICU-stype variant, uloc_getVariant() 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, uloc_getName() 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 uloc_getName() 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.
Definition in file uloc.h.
|
Useful constant for this country/region.
|
|
Useful constant for this country/region.
|
|
Useful constant for this country/region.
|
|
Useful constant for this language.
|
|
Useful constant for the maximum size of the country part of a locale ID (including the terminating NULL).
|
|
Useful constant for this language.
|
|
Useful constant for this country/region.
|
|
Useful constant for this language.
|
|
Useful constant for the maximum size of the whole locale ID (including the terminating NULL).
|
|
Useful constant for this language.
|
|
Useful constant for this country/region.
|
|
Useful constant for this language.
|
|
Useful constant for this country/region.
|
|
Useful constant for this country/region.
|
|
Useful constant for this language.
|
|
Useful constant for the maximum SIZE of keywords in a locale.
|
|
Character for assigning value to a keyword.
|
|
Character separating keywords.
|
|
Character separating keywords from the locale string different for EBCDIC - TODO.
|
|
Useful constant for the maximum size of keywords in a locale.
|
|
Useful constant for this country/region.
|
|
Useful constant for this language.
|
|
Useful constant for the maximum size of the language part of a locale ID. (including the terminating NULL).
|
|
Useful constant for this country/region.
|
|
Useful constant for the maximum size of the script part of a locale ID (including the terminating NULL).
|
|
Useful constant for this language.
|
|
Useful constant for this country/region.
|
|
Useful constant for this language.
|
|
Useful constant for this country/region.
|
|
Useful constant for this country/region.
|
|
enums for the 'outResult' parameter return value
|
|
enums for the return value for the character and line orientation functions.
|
|
Constants for *_getLocale() Allow user to select whether she wants information on requested, valid or actual locale. For example, a collator for "en_US_CALIFORNIA" was requested. In the current state of ICU (2.0), the requested locale is "en_US_CALIFORNIA", the valid locale is "en_US" (most specific locale supported by ICU) and the actual locale is "root" (the collation data comes unmodified from the UCA) The locale is considered supported by ICU if there is a core ICU bundle for that locale (although it may be empty).
|
|
Based on a list of available locales, determine an acceptable locale for the user.
|
|
Based on a HTTP header from a web browser and a list of available locales, determine an acceptable locale for the user.
|
|
Add the likely subtags for a provided locale ID, per the algorithm described in the following CLDR technical report:. http://www.unicode.org/reports/tr35/#Likely_Subtags If localeID is already in the maximal form, or there is no data available for maximization, it will be copied to the output buffer. For example, "und-Zzzz" cannot be maximized, since there is no reasonable maximization. Examples: "en" maximizes to "en_Latn_US" "de" maximizes to "de_Latn_US" "sr" maximizes to "sr_Cyrl_RS" "sh" maximizes to "sr_Latn_RS" (Note this will not reverse.) "zh_Hani" maximizes to "zh_Hans_CN" (Note this will not reverse.)
|
|
Gets the full name for the specified locale. Note: This has the effect of 'canonicalizing' the string to a certain extent. Upper and lower case are set as needed, and if the components were in 'POSIX' format they are changed to ICU format. It does NOT map aliased names in any way. See the top of this header file.
|
|
Gets the size of the all available locale list.
|
|
Gets the specified locale from a list of all available locales. The return value is a pointer to an item of a locale name array. Both this array and the pointers it contains are owned by ICU and should not be deleted or written through by the caller. The locale name is terminated by a null pointer.
|
|
Gets the full name for the specified locale. Note: This has the effect of 'canonicalizing' the string to a certain extent. Upper and lower case are set as needed, and if the components were in 'POSIX' format they are changed to ICU format. It does NOT map aliased names in any way. See the top of this header file. This API strips off the keyword part, so "de_DE\@collation=phonebook" will become "de_DE". This API supports preflighting.
|
|
Get the layout character orientation for the specified locale.
|
|
Gets the country code for the specified locale.
|
|
Gets ICU's default locale. The returned string is a snapshot in time, and will remain valid and unchanged even when uloc_setDefault() is called. The returned storage is owned by ICU, and must not be altered or deleted by the caller.
|
|
Gets the country name suitable for display for the specified locale.
|
|
Gets the keyword name suitable for display for the specified locale.
E.g: for the locale string de_DE@collation=PHONEBOOK, this API gets the display string for the keyword collation. Usage:
|
|
Gets the value of the keyword suitable for display for the specified locale. E.g: for the locale string de_DE@collation=PHONEBOOK, this API gets the display string for PHONEBOOK, in the display locale, when "collation" is specified as the keyword.
|
|
Gets the language name suitable for display for the specified locale.
|
|
Gets the full name suitable for display for the specified locale.
|
|
Gets the script name suitable for display for the specified locale.
|
|
Gets the variant name suitable for display for the specified locale.
|
|
Gets the ISO country code for the specified locale.
|
|
Gets the ISO language code for the specified locale.
|
|
Gets a list of all available 2-letter country codes defined in ISO 639. This is a pointer to an array of pointers to arrays of char. All of these pointers are owned by ICU-- do not delete them, and do not write through them. The array is terminated with a null pointer.
|
|
Gets a list of all available language codes defined in ISO 639. This is a pointer to an array of pointers to arrays of char. All of these pointers are owned by ICU-- do not delete them, and do not write through them. The array is terminated with a null pointer.
|
|
Get the value for a keyword. Locale name does not need to be normalized.
|
|
Gets the language code for the specified locale.
|
|
Gets the Win32 LCID value for the specified locale. If the ICU locale is not recognized by Windows, 0 will be returned.
|
|
Get the layout line orientation for the specified locale.
|
|
Gets the ICU locale ID for the specified Win32 LCID value.
|
|
Gets the full name for the specified locale. Note: This has the effect of 'canonicalizing' the ICU locale ID to a certain extent. Upper and lower case are set as needed. It does NOT map aliased names in any way. See the top of this header file. This API supports preflighting.
|
|
Truncate the locale ID string to get the parent locale ID. Copies the part of the string before the last underscore. The parent locale ID will be an empty string if there is no underscore, or if there is only one underscore at localeID[0].
|
|
Gets the script code for the specified locale.
|
|
Gets the variant code for the specified locale.
|
|
Minimize the subtags for a provided locale ID, per the algorithm described in the following CLDR technical report:. http://www.unicode.org/reports/tr35/#Likely_Subtags If localeID is already in the minimal form, or there is no data available for minimization, it will be copied to the output buffer. Since the minimization algorithm relies on proper maximization, see the comments for uloc_addLikelySubtags for reasons why there might not be any data. Examples: "en_Latn_US" minimizes to "en" "de_Latn_US" minimizes to "de" "sr_Cyrl_RS" minimizes to "sr" "zh_Hant_TW" minimizes to "zh_TW" (The region is preferred to the script, and minimizing to "zh" would imply "zh_Hans_CN".)
|
|
Gets an enumeration of keywords for the specified locale. Enumeration must get disposed of by the client using uenum_close function.
|
|
Sets ICU's default locale. By default (without calling this function), ICU's default locale will be based on information obtained from the underlying system environment. Changes to ICU's default locale do not propagate back to the system environment. Changes to ICU's default locale to not affect any ICU services that may already be open based on the previous default locale value.
|
|
Set the value of the specified keyword. NOTE: Unlike almost every other ICU function which takes a buffer, this function will NOT truncate the output text. If a BUFFER_OVERFLOW_ERROR is received, it means that the original buffer is untouched. This is done to prevent incorrect or possibly even malformed locales from being generated and used.
|