Logo Search packages:      
Sourcecode: icu version File versions  Download package

Defines | Enumerations | Functions

uloc.h File Reference

C API: Locale. More...

#include "unicode/utypes.h"
#include "unicode/uenum.h"
Include dependency graph for uloc.h:

Go to the source code of this file.

Defines

#define ULOC_CANADA   "en_CA"
#define ULOC_CANADA_FRENCH   "fr_CA"
#define ULOC_CHINA   "zh_CN"
#define ULOC_CHINESE   "zh"
#define ULOC_COUNTRY_CAPACITY   4
#define ULOC_ENGLISH   "en"
#define ULOC_FRANCE   "fr_FR"
#define ULOC_FRENCH   "fr"
#define ULOC_FULLNAME_CAPACITY   157
#define ULOC_GERMAN   "de"
#define ULOC_GERMANY   "de_DE"
#define ULOC_ITALIAN   "it"
#define ULOC_ITALY   "it_IT"
#define ULOC_JAPAN   "ja_JP"
#define ULOC_JAPANESE   "ja"
#define ULOC_KEYWORD_AND_VALUES_CAPACITY   100
#define ULOC_KEYWORD_ASSIGN   '='
#define ULOC_KEYWORD_ITEM_SEPARATOR   ';'
#define ULOC_KEYWORD_SEPARATOR   '@'
#define ULOC_KEYWORDS_CAPACITY   50
#define ULOC_KOREA   "ko_KR"
#define ULOC_KOREAN   "ko"
#define ULOC_LANG_CAPACITY   12
#define ULOC_PRC   "zh_CN"
#define ULOC_SCRIPT_CAPACITY   6
#define ULOC_SIMPLIFIED_CHINESE   "zh_CN"
#define ULOC_TAIWAN   "zh_TW"
#define ULOC_TRADITIONAL_CHINESE   "zh_TW"
#define ULOC_UK   "en_GB"
#define ULOC_US   "en_US"

Enumerations

enum  UAcceptResult { ULOC_ACCEPT_FAILED = 0, ULOC_ACCEPT_VALID = 1, ULOC_ACCEPT_FALLBACK = 2 }
enum  ULayoutType {
  ULOC_LAYOUT_LTR = 0, ULOC_LAYOUT_RTL = 1, ULOC_LAYOUT_TTB = 2, ULOC_LAYOUT_BTT = 3,
  ULOC_LAYOUT_UNKNOWN
}
enum  ULocDataLocaleType { ULOC_ACTUAL_LOCALE = 0, ULOC_VALID_LOCALE = 1, ULOC_REQUESTED_LOCALE = 2, ULOC_DATA_LOCALE_TYPE_LIMIT = 3 }

Functions

U_STABLE int32_t U_EXPORT2 uloc_acceptLanguage (char *result, int32_t resultAvailable, UAcceptResult *outResult, const char **acceptList, int32_t acceptListCount, UEnumeration *availableLocales, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 uloc_acceptLanguageFromHTTP (char *result, int32_t resultAvailable, UAcceptResult *outResult, const char *httpAcceptLanguage, UEnumeration *availableLocales, UErrorCode *status)
U_DRAFT int32_t U_EXPORT2 uloc_addLikelySubtags (const char *localeID, char *maximizedLocaleID, int32_t maximizedLocaleIDCapacity, UErrorCode *err)
U_STABLE int32_t U_EXPORT2 uloc_canonicalize (const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
U_STABLE int32_t U_EXPORT2 uloc_countAvailable (void)
U_DRAFT int32_t U_EXPORT2 uloc_forLanguageTag (const char *langtag, char *localeID, int32_t localeIDCapacity, int32_t *parsedLength, UErrorCode *err)
U_STABLE const char *U_EXPORT2 uloc_getAvailable (int32_t n)
U_STABLE int32_t U_EXPORT2 uloc_getBaseName (const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
U_DRAFT ULayoutType U_EXPORT2 uloc_getCharacterOrientation (const char *localeId, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 uloc_getCountry (const char *localeID, char *country, int32_t countryCapacity, UErrorCode *err)
U_STABLE const char *U_EXPORT2 uloc_getDefault (void)
U_STABLE int32_t U_EXPORT2 uloc_getDisplayCountry (const char *locale, const char *displayLocale, UChar *country, int32_t countryCapacity, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 uloc_getDisplayKeyword (const char *keyword, const char *displayLocale, UChar *dest, int32_t destCapacity, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 uloc_getDisplayKeywordValue (const char *locale, const char *keyword, const char *displayLocale, UChar *dest, int32_t destCapacity, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 uloc_getDisplayLanguage (const char *locale, const char *displayLocale, UChar *language, int32_t languageCapacity, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 uloc_getDisplayName (const char *localeID, const char *inLocaleID, UChar *result, int32_t maxResultSize, UErrorCode *err)
U_STABLE int32_t U_EXPORT2 uloc_getDisplayScript (const char *locale, const char *displayLocale, UChar *script, int32_t scriptCapacity, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 uloc_getDisplayVariant (const char *locale, const char *displayLocale, UChar *variant, int32_t variantCapacity, UErrorCode *status)
U_STABLE const char *U_EXPORT2 uloc_getISO3Country (const char *localeID)
U_STABLE const char *U_EXPORT2 uloc_getISO3Language (const char *localeID)
U_STABLE const char *const
U_EXPORT2 
uloc_getISOCountries (void)
U_STABLE const char *const
U_EXPORT2 
uloc_getISOLanguages (void)
U_STABLE int32_t U_EXPORT2 uloc_getKeywordValue (const char *localeID, const char *keywordName, char *buffer, int32_t bufferCapacity, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 uloc_getLanguage (const char *localeID, char *language, int32_t languageCapacity, UErrorCode *err)
U_STABLE uint32_t U_EXPORT2 uloc_getLCID (const char *localeID)
U_DRAFT ULayoutType U_EXPORT2 uloc_getLineOrientation (const char *localeId, UErrorCode *status)
U_DRAFT int32_t U_EXPORT2 uloc_getLocaleForLCID (uint32_t hostID, char *locale, int32_t localeCapacity, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 uloc_getName (const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
U_STABLE int32_t U_EXPORT2 uloc_getParent (const char *localeID, char *parent, int32_t parentCapacity, UErrorCode *err)
U_STABLE int32_t U_EXPORT2 uloc_getScript (const char *localeID, char *script, int32_t scriptCapacity, UErrorCode *err)
U_STABLE int32_t U_EXPORT2 uloc_getVariant (const char *localeID, char *variant, int32_t variantCapacity, UErrorCode *err)
U_DRAFT int32_t U_EXPORT2 uloc_minimizeSubtags (const char *localeID, char *minimizedLocaleID, int32_t minimizedLocaleIDCapacity, UErrorCode *err)
U_STABLE UEnumeration *U_EXPORT2 uloc_openKeywords (const char *localeID, UErrorCode *status)
U_STABLE void U_EXPORT2 uloc_setDefault (const char *localeID, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 uloc_setKeywordValue (const char *keywordName, const char *keywordValue, char *buffer, int32_t bufferCapacity, UErrorCode *status)
U_DRAFT int32_t U_EXPORT2 uloc_toLanguageTag (const char *localeID, char *langtag, int32_t langtagCapacity, UBool strict, UErrorCode *err)

Detailed Description

C API: Locale.

ULoc C API for Locale

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.

 
       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. You can find a full list of these codes at a number of sites, such as:
http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt

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.

 
     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);
Each of these methods has two variants; one with an explicit locale and one without; the latter using the default locale.
 
     nf = 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);
A 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.

See also:
UResourceBundle

Definition in file uloc.h.


Generated by  Doxygen 1.6.0   Back to index