Main Page | Class Hierarchy | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

uloc.h File Reference

C API: Locale. More...

#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_SCRIPT_CAPACITY   6
 Useful constant for the maximum size of the script part of a locale ID (including the terminating NULL).

#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_KEYWORDS_CAPACITY   50
 Useful constant for the maximum size of keywords in a locale ICU 2.8.

#define ULOC_KEYWORD_AND_VALUES_CAPACITY   100
 Useful constant for the maximum size of keywords in a locale ICU 2.8.

#define ULOC_KEYWORD_SEPARATOR   '@'
 Character separating keywords from the locale string different for EBCDIC - TODO ICU 2.8.

#define ULOC_KEYWORD_ASSIGN   '='
 Character for assigning value to a keyword ICU 2.8.

#define ULOC_KEYWORD_ITEM_SEPARATOR   ';'
 Character separating keywords ICU 2.8.


Enumerations

enum  ULocDataLocaleType { ULOC_ACTUAL_LOCALE = 0, ULOC_VALID_LOCALE = 1, ULOC_REQUESTED_LOCALE = 2, ULOC_DATA_LOCALE_TYPE_LIMIT }
 Constants for *_getLocale() Allow user to select whether she wants information on requested, valid or actual locale. More...


Functions

U_CAPI const char *U_EXPORT2 uloc_getDefault (void)
 Gets ICU's default locale.

U_CAPI void U_EXPORT2 uloc_setDefault (const char *localeID, UErrorCode *status)
 Sets ICU's default locale.

U_CAPI int32_t U_EXPORT2 uloc_getLanguage (const char *localeID, char *language, int32_t languageCapacity, UErrorCode *err)
 Gets the language code for the specified locale.

U_CAPI int32_t U_EXPORT2 uloc_getScript (const char *localeID, char *script, int32_t scriptCapacity, UErrorCode *err)
 Gets the script code for the specified locale.

U_CAPI int32_t U_EXPORT2 uloc_getCountry (const char *localeID, char *country, int32_t countryCapacity, UErrorCode *err)
 Gets the country code for the specified locale.

U_CAPI int32_t U_EXPORT2 uloc_getVariant (const char *localeID, char *variant, int32_t variantCapacity, UErrorCode *err)
 Gets the variant code for the specified locale.

U_CAPI int32_t U_EXPORT2 uloc_getName (const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
 Gets the full name for the specified locale.

U_CAPI int32_t U_EXPORT2 uloc_canonicalize (const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
 Gets the full name for the specified locale.

U_CAPI const char *U_EXPORT2 uloc_getISO3Language (const char *localeID)
 Gets the ISO language code for the specified locale.

U_CAPI const char *U_EXPORT2 uloc_getISO3Country (const char *localeID)
 Gets the ISO country code for the specified locale.

U_CAPI uint32_t U_EXPORT2 uloc_getLCID (const char *localeID)
 Gets the Win32 LCID value for the specified locale.

U_CAPI int32_t U_EXPORT2 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.

U_CAPI int32_t U_EXPORT2 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.

U_CAPI int32_t U_EXPORT2 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.

U_CAPI int32_t U_EXPORT2 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.

U_CAPI int32_t U_EXPORT2 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.

U_CAPI int32_t U_EXPORT2 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.

U_CAPI int32_t U_EXPORT2 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.

U_CAPI const char *U_EXPORT2 uloc_getAvailable (int32_t n)
 Gets the specified locale from a list of all available locales.

U_CAPI int32_t U_EXPORT2 uloc_countAvailable (void)
 Gets the size of the all available locale list.

U_CAPI const char *const
*U_EXPORT2 
uloc_getISOLanguages (void)
 Gets a list of all available language codes defined in ISO 639.

U_CAPI const char *const
*U_EXPORT2 
uloc_getISOCountries (void)
 Gets a list of all available 2-letter country codes defined in ISO 639.

U_CAPI int32_t U_EXPORT2 uloc_getParent (const char *localeID, char *parent, int32_t parentCapacity, UErrorCode *err)
 Truncate the locale ID string to get the parent locale ID.

U_CAPI int32_t U_EXPORT2 uloc_getBaseName (const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
 Gets the full name for the specified locale.

U_CAPI UEnumeration *U_EXPORT2 uloc_openKeywords (const char *localeID, UErrorCode *status)
 Gets an enumeration of keywords for the specified locale.

U_CAPI int32_t U_EXPORT2 uloc_getKeywordValue (const char *localeID, const char *keywordName, char *buffer, int32_t bufferCapacity, UErrorCode *status)
 Get the value for a keyword.


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. <blockquote>

 
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: <blockquote>

 

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. <blockquote>

 
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. <blockquote>
 
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: <blockquote>

 
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 and if there is not an ICU-stype variant, uloc_getVariant() for example will return the one listed after the 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 as an argument to resourcebundle.

See also:
UResourceBundle

Define Documentation

#define ULOC_CANADA   "en_CA"
 

Useful constant for this country/region.

ICU 2.0

#define ULOC_CANADA_FRENCH   "fr_CA"
 

Useful constant for this country/region.

ICU 2.0

#define ULOC_CHINA   "zh_CN"
 

Useful constant for this country/region.

ICU 2.0

#define ULOC_CHINESE   "zh"
 

Useful constant for this language.

ICU 2.0

#define ULOC_COUNTRY_CAPACITY   4
 

Useful constant for the maximum size of the country part of a locale ID (including the terminating NULL).

ICU 2.0

#define ULOC_ENGLISH   "en"
 

Useful constant for this language.

ICU 2.0

#define ULOC_FRANCE   "fr_FR"
 

Useful constant for this country/region.

ICU 2.0

#define ULOC_FRENCH   "fr"
 

Useful constant for this language.

ICU 2.0

#define ULOC_FULLNAME_CAPACITY   56
 

Useful constant for the maximum size of the whole locale ID (including the terminating NULL).

ICU 2.0

#define ULOC_GERMAN   "de"
 

Useful constant for this language.

ICU 2.0

#define ULOC_GERMANY   "de_DE"
 

Useful constant for this country/region.

ICU 2.0

#define ULOC_ITALIAN   "it"
 

Useful constant for this language.

ICU 2.0

#define ULOC_ITALY   "it_IT"
 

Useful constant for this country/region.

ICU 2.0

#define ULOC_JAPAN   "ja_JP"
 

Useful constant for this country/region.

ICU 2.0

#define ULOC_JAPANESE   "ja"
 

Useful constant for this language.

ICU 2.0

#define ULOC_KOREA   "ko_KR"
 

Useful constant for this country/region.

ICU 2.0

#define ULOC_KOREAN   "ko"
 

Useful constant for this language.

ICU 2.0

#define ULOC_LANG_CAPACITY   12
 

Useful constant for the maximum size of the language part of a locale ID.

(including the terminating NULL). ICU 2.0

#define ULOC_PRC   "zh_CN"
 

Useful constant for this country/region.

ICU 2.0

#define ULOC_SCRIPT_CAPACITY   6
 

Useful constant for the maximum size of the script part of a locale ID (including the terminating NULL).

ICU 2.8

#define ULOC_SIMPLIFIED_CHINESE   "zh_CN"
 

Useful constant for this language.

ICU 2.0

#define ULOC_TAIWAN   "zh_TW"
 

Useful constant for this country/region.

ICU 2.0

#define ULOC_TRADITIONAL_CHINESE   "zh_TW"
 

Useful constant for this language.

ICU 2.0

#define ULOC_UK   "en_GB"
 

Useful constant for this country/region.

ICU 2.0

#define ULOC_US   "en_US"
 

Useful constant for this country/region.

ICU 2.0


Enumeration Type Documentation

enum ULocDataLocaleType
 

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). ICU 2.1

Enumeration values:
ULOC_ACTUAL_LOCALE  This is locale the data actually comes from ICU 2.1.
ULOC_VALID_LOCALE  This is the most specific locale supported by ICU ICU 2.1.
ULOC_REQUESTED_LOCALE  This is the requested locale.

Deprecated:
ICU 2.8


Function Documentation

U_CAPI int32_t U_EXPORT2 uloc_canonicalize const char *  localeID,
char *  name,
int32_t  nameCapacity,
UErrorCode err
 

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.

Parameters:
localeID the locale to get the full name with
name the full name for localeID
nameCapacity the size of the name buffer to store the full name with
err error information if retrieving the full name failed
Returns:
the actual buffer size needed for the full name. If it's greater than nameCapacity, the returned full name will be truncated. ICU 2.0

U_CAPI int32_t U_EXPORT2 uloc_countAvailable void   ) 
 

Gets the size of the all available locale list.

Returns:
the size of the locale list ICU 2.0

U_CAPI const char* U_EXPORT2 uloc_getAvailable int32_t  n  ) 
 

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.

Parameters:
n the specific locale name index of the available locale list
Returns:
a specified locale name of all available locales ICU 2.0

U_CAPI int32_t U_EXPORT2 uloc_getBaseName const char *  localeID,
char *  name,
int32_t  nameCapacity,
UErrorCode err
 

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.

Parameters:
localeID the locale to get the full name with
name fill in buffer for the name without keywords.
nameCapacity capacity of the fill in buffer.
err error information if retrieving the full name failed
Returns:
the actual buffer size needed for the full name. If it's greater than nameCapacity, the returned full name will be truncated. ICU 2.8

U_CAPI int32_t U_EXPORT2 uloc_getCountry const char *  localeID,
char *  country,
int32_t  countryCapacity,
UErrorCode err
 

Gets the country code for the specified locale.

Parameters:
localeID the locale to get the country code with
country the country code for localeID
countryCapacity the size of the country buffer to store the country code with
err error information if retrieving the country code failed
Returns:
the actual buffer size needed for the country code. If it's greater than countryCapacity, the returned country code will be truncated. ICU 2.0

U_CAPI const char* U_EXPORT2 uloc_getDefault void   ) 
 

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.

Returns:
the ICU default locale ICU 2.0

U_CAPI int32_t U_EXPORT2 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.

Parameters:
locale the locale to get the displayable country code with. NULL may be used to specify the default.
displayLocale Specifies the locale to be used to display the name. In other words, if the locale's language code is "en", passing Locale::getFrench() for inLocale would result in "Anglais", while passing Locale::getGerman() for inLocale would result in "Englisch". NULL may be used to specify the default.
country the displayable country code for localeID
countryCapacity the size of the country buffer to store the displayable country code with
status error information if retrieving the displayable country code failed
Returns:
the actual buffer size needed for the displayable country code. If it's greater than countryCapacity, the returned displayable country code will be truncated. ICU 2.0

U_CAPI int32_t U_EXPORT2 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.

E.g: for the locale string de_DE=PHONEBOOK, this API gets the display string for the keyword collation. Usage: UErrorCode status = U_ZERO_ERROR; const char* keyword =NULL; int32_t keywordLen = 0; int32_t keywordCount = 0; UChar displayKeyword[256]; int32_t displayKeywordLen = 0; UEnumeration* keywordEnum = uloc_getKeywords("de_DE@collation=PHONEBOOK;calendar=TRADITIONAL", &status); for(keywordCount = uenum_count(keywordEnum, &status); keywordCount > 0 ; keywordCount--){ if(U_FAILURE(status)){ ...something went wrong so handle the error... break; } // the uenum_next returns NUL terminated string keyword = uenum_next(keywordEnum, &keywordLen, &status); displayKeywordLen = uloc_getDisplayKeyword(keyword, "en_US", displayKeyword, 256); ... do something interesting ..... } uenum_close(keywordEnum);

Parameters:
keyword The keyword whose display string needs to be returned.
displayLocale Specifies the locale to be used to display the name. In other words, if the locale's language code is "en", passing Locale::getFrench() for inLocale would result in "Anglais", while passing Locale::getGerman() for inLocale would result in "Englisch". NULL may be used to specify the default.
dest the buffer to which the displayable keyword should be written.
destCapacity The size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
status error information if retrieving the displayable string failed. Should not be NULL and should not indicate failure on entry.
Returns:
the actual buffer size needed for the displayable variant code.
See also:
#uloc_getKeywords ICU 2.8

U_CAPI int32_t U_EXPORT2 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.

E.g: for the locale string de_DE=PHONEBOOK, this API gets the display string for PHONEBOOK, in the display locale, when "collation" is specified as the keyword.

Parameters:
locale The locale to get the displayable variant code with. NULL may be used to specify the default.
keyword The keyword for whose value should be used.
displayLocale Specifies the locale to be used to display the name. In other words, if the locale's language code is "en", passing Locale::getFrench() for inLocale would result in "Anglais", while passing Locale::getGerman() for inLocale would result in "Englisch". NULL may be used to specify the default.
dest the buffer to which the displayable keyword should be written.
destCapacity The size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
status error information if retrieving the displayable string failed. Should not be NULL and must not indicate failure on entry.
Returns:
the actual buffer size needed for the displayable variant code. ICU 2.8

U_CAPI int32_t U_EXPORT2 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.

Parameters:
locale the locale to get the ISO language code with
displayLocale Specifies the locale to be used to display the name. In other words, if the locale's language code is "en", passing Locale::getFrench() for inLocale would result in "Anglais", while passing Locale::getGerman() for inLocale would result in "Englisch".
language the displayable language code for localeID
languageCapacity the size of the language buffer to store the displayable language code with
status error information if retrieving the displayable language code failed
Returns:
the actual buffer size needed for the displayable language code. If it's greater than languageCapacity, the returned language code will be truncated. ICU 2.0

U_CAPI int32_t U_EXPORT2 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.

Parameters:
localeID the locale to get the displayable name with. NULL may be used to specify the default.
inLocaleID Specifies the locale to be used to display the name. In other words, if the locale's language code is "en", passing Locale::getFrench() for inLocale would result in "Anglais", while passing Locale::getGerman() for inLocale would result in "Englisch". NULL may be used to specify the default.
result the displayable name for localeID
maxResultSize the size of the name buffer to store the displayable full name with
err error information if retrieving the displayable name failed
Returns:
the actual buffer size needed for the displayable name. If it's greater than variantCapacity, the returned displayable name will be truncated. ICU 2.0

U_CAPI int32_t U_EXPORT2 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.

Parameters:
locale the locale to get the displayable script code with. NULL may be used to specify the default.
displayLocale Specifies the locale to be used to display the name. In other words, if the locale's language code is "en", passing Locale::getFrench() for inLocale would result in "", while passing Locale::getGerman() for inLocale would result in "". NULL may be used to specify the default.
script the displayable country code for localeID
scriptCapacity the size of the script buffer to store the displayable script code with
status error information if retrieving the displayable script code failed
Returns:
the actual buffer size needed for the displayable script code. If it's greater than scriptCapacity, the returned displayable script code will be truncated. ICU 2.8

U_CAPI int32_t U_EXPORT2 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.

Parameters:
locale the locale to get the displayable variant code with. NULL may be used to specify the default.
displayLocale Specifies the locale to be used to display the name. In other words, if the locale's language code is "en", passing Locale::getFrench() for inLocale would result in "Anglais", while passing Locale::getGerman() for inLocale would result in "Englisch". NULL may be used to specify the default.
variant the displayable variant code for localeID
variantCapacity the size of the variant buffer to store the displayable variant code with
status error information if retrieving the displayable variant code failed
Returns:
the actual buffer size needed for the displayable variant code. If it's greater than variantCapacity, the returned displayable variant code will be truncated. ICU 2.0

U_CAPI const char* U_EXPORT2 uloc_getISO3Country const char *  localeID  ) 
 

Gets the ISO country code for the specified locale.

Parameters:
localeID the locale to get the ISO country code with
Returns:
country the ISO country code for localeID ICU 2.0

U_CAPI const char* U_EXPORT2 uloc_getISO3Language const char *  localeID  ) 
 

Gets the ISO language code for the specified locale.

Parameters:
localeID the locale to get the ISO language code with
Returns:
language the ISO language code for localeID ICU 2.0

U_CAPI const char* const* U_EXPORT2 uloc_getISOCountries void   ) 
 

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.

Returns:
a list of all available country codes ICU 2.0

U_CAPI const char* const* U_EXPORT2 uloc_getISOLanguages void   ) 
 

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.

Returns:
a list of all available language codes ICU 2.0

U_CAPI int32_t U_EXPORT2 uloc_getKeywordValue const char *  localeID,
const char *  keywordName,
char *  buffer,
int32_t  bufferCapacity,
UErrorCode status
 

Get the value for a keyword.

Locale name does not need to be normalized.

Parameters:
localeID locale name containing the keyword ("de_DE@currency=EURO;collation=PHONEBOOK")
keywordName name of the keyword for which we want the value. Case insensitive.
buffer receiving buffer
bufferCapacity capacity of receiving buffer
status containing error code - buffer not big enough.
Returns:
the length of keyword value ICU 2.8

U_CAPI int32_t U_EXPORT2 uloc_getLanguage const char *  localeID,
char *  language,
int32_t  languageCapacity,
UErrorCode err
 

Gets the language code for the specified locale.

Parameters:
localeID the locale to get the ISO language code with
language the language code for localeID
languageCapacity the size of the language buffer to store the language code with
err error information if retrieving the language code failed
Returns:
the actual buffer size needed for the language code. If it's greater than languageCapacity, the returned language code will be truncated. ICU 2.0

U_CAPI uint32_t U_EXPORT2 uloc_getLCID const char *  localeID  ) 
 

Gets the Win32 LCID value for the specified locale.

If the ICU locale is not recognized by Windows, 0 will be returned.

Parameters:
localeID the locale to get the Win32 LCID value with
Returns:
country the Win32 LCID for localeID ICU 2.0

U_CAPI int32_t U_EXPORT2 uloc_getName const char *  localeID,
char *  name,
int32_t  nameCapacity,
UErrorCode err
 

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.

Parameters:
localeID the locale to get the full name with
name fill in buffer for the name without keywords.
nameCapacity capacity of the fill in buffer.
err error information if retrieving the full name failed
Returns:
the actual buffer size needed for the full name. If it's greater than nameCapacity, the returned full name will be truncated. ICU 2.0

U_CAPI int32_t U_EXPORT2 uloc_getParent const char *  localeID,
char *  parent,
int32_t  parentCapacity,
UErrorCode err
 

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].

Parameters:
localeID Input locale ID string.
parent Output string buffer for the parent locale ID.
parentCapacity Size of the output buffer.
err A UErrorCode value.
Returns:
The length of the parent locale ID. ICU 2.0

U_CAPI int32_t U_EXPORT2 uloc_getScript const char *  localeID,
char *  script,
int32_t  scriptCapacity,
UErrorCode err
 

Gets the script code for the specified locale.

Parameters:
localeID the locale to get the ISO language code with
script the language code for localeID
scriptCapacity the size of the language buffer to store the language code with
err error information if retrieving the language code failed
Returns:
the actual buffer size needed for the language code. If it's greater than scriptCapacity, the returned language code will be truncated. ICU 2.8

U_CAPI int32_t U_EXPORT2 uloc_getVariant const char *  localeID,
char *  variant,
int32_t  variantCapacity,
UErrorCode err
 

Gets the variant code for the specified locale.

Parameters:
localeID the locale to get the variant code with
variant the variant code for localeID
variantCapacity the size of the variant buffer to store the variant code with
err error information if retrieving the variant code failed
Returns:
the actual buffer size needed for the variant code. If it's greater than variantCapacity, the returned variant code will be truncated. ICU 2.0

U_CAPI UEnumeration* U_EXPORT2 uloc_openKeywords const char *  localeID,
UErrorCode status
 

Gets an enumeration of keywords for the specified locale.

Enumeration must get disposed of by the client using uenum_close function.

Parameters:
localeID the locale to get the variant code with
status error information if retrieving the keywords failed
Returns:
enumeration of keywords or NULL if there are no keywords. ICU 2.8

U_CAPI void U_EXPORT2 uloc_setDefault const char *  localeID,
UErrorCode status
 

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.

Parameters:
localeID the new ICU default locale. A value of NULL will try to get the system's default locale.
status the error information if the setting of default locale fails ICU 2.0


Generated on Wed Jul 28 09:15:55 2004 for ICU 2.8 by doxygen 1.3.7