ICU 72.1 72.1
Macros | Typedefs | Enumerations | Functions
uloc.h File Reference

C API: Locale ID functionality similar to C++ class Locale. More...

#include "unicode/utypes.h"
#include "unicode/uenum.h"

Go to the source code of this file.

Macros

#define ULOC_CHINESE   "zh"
 Useful constant for this language. More...
 
#define ULOC_ENGLISH   "en"
 Useful constant for this language. More...
 
#define ULOC_FRENCH   "fr"
 Useful constant for this language. More...
 
#define ULOC_GERMAN   "de"
 Useful constant for this language. More...
 
#define ULOC_ITALIAN   "it"
 Useful constant for this language. More...
 
#define ULOC_JAPANESE   "ja"
 Useful constant for this language. More...
 
#define ULOC_KOREAN   "ko"
 Useful constant for this language. More...
 
#define ULOC_SIMPLIFIED_CHINESE   "zh_CN"
 Useful constant for this language. More...
 
#define ULOC_TRADITIONAL_CHINESE   "zh_TW"
 Useful constant for this language. More...
 
#define ULOC_CANADA   "en_CA"
 Useful constant for this country/region. More...
 
#define ULOC_CANADA_FRENCH   "fr_CA"
 Useful constant for this country/region. More...
 
#define ULOC_CHINA   "zh_CN"
 Useful constant for this country/region. More...
 
#define ULOC_PRC   "zh_CN"
 Useful constant for this country/region. More...
 
#define ULOC_FRANCE   "fr_FR"
 Useful constant for this country/region. More...
 
#define ULOC_GERMANY   "de_DE"
 Useful constant for this country/region. More...
 
#define ULOC_ITALY   "it_IT"
 Useful constant for this country/region. More...
 
#define ULOC_JAPAN   "ja_JP"
 Useful constant for this country/region. More...
 
#define ULOC_KOREA   "ko_KR"
 Useful constant for this country/region. More...
 
#define ULOC_TAIWAN   "zh_TW"
 Useful constant for this country/region. More...
 
#define ULOC_UK   "en_GB"
 Useful constant for this country/region. More...
 
#define ULOC_US   "en_US"
 Useful constant for this country/region. More...
 
#define ULOC_LANG_CAPACITY   12
 Useful constant for the maximum size of the language part of a locale ID. More...
 
#define ULOC_COUNTRY_CAPACITY   4
 Useful constant for the maximum size of the country part of a locale ID (including the terminating NULL). More...
 
#define ULOC_FULLNAME_CAPACITY   157
 Useful constant for the maximum size of the whole locale ID (including the terminating NULL and all keywords). More...
 
#define ULOC_SCRIPT_CAPACITY   6
 Useful constant for the maximum size of the script part of a locale ID (including the terminating NULL). More...
 
#define ULOC_KEYWORDS_CAPACITY   96
 Useful constant for the maximum size of keywords in a locale. More...
 
#define ULOC_KEYWORD_AND_VALUES_CAPACITY   100
 Useful constant for the maximum total size of keywords and their values in a locale. More...
 
#define ULOC_KEYWORD_SEPARATOR   '@'
 Invariant character separating keywords from the locale string. More...
 
#define ULOC_KEYWORD_SEPARATOR_UNICODE   0x40
 Unicode code point for '@' separating keywords from the locale string. More...
 
#define ULOC_KEYWORD_ASSIGN   '='
 Invariant character for assigning value to a keyword. More...
 
#define ULOC_KEYWORD_ASSIGN_UNICODE   0x3D
 Unicode code point for '=' for assigning value to a keyword. More...
 
#define ULOC_KEYWORD_ITEM_SEPARATOR   ';'
 Invariant character separating keywords. More...
 
#define ULOC_KEYWORD_ITEM_SEPARATOR_UNICODE   0x3B
 Unicode code point for ';' separating keywords. More...
 

Typedefs

typedef enum ULocAvailableType ULocAvailableType
 Types for uloc_getAvailableByType and uloc_countAvailableByType. More...
 

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  ULocAvailableType { ULOC_AVAILABLE_DEFAULT , ULOC_AVAILABLE_ONLY_LEGACY_ALIASES , ULOC_AVAILABLE_WITH_LEGACY_ALIASES , ULOC_AVAILABLE_COUNT }
 Types for uloc_getAvailableByType and uloc_countAvailableByType. 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 }
 Output values which uloc_acceptLanguage() writes to the 'outResult' parameter. More...
 

Functions

U_CAPI const char * uloc_getDefault (void)
 Gets ICU's default locale. More...
 
U_CAPI void uloc_setDefault (const char *localeID, UErrorCode *status)
 Sets ICU's default locale. More...
 
U_CAPI int32_t uloc_getLanguage (const char *localeID, char *language, int32_t languageCapacity, UErrorCode *err)
 Gets the language code for the specified locale. More...
 
U_CAPI int32_t uloc_getScript (const char *localeID, char *script, int32_t scriptCapacity, UErrorCode *err)
 Gets the script code for the specified locale. More...
 
U_CAPI int32_t uloc_getCountry (const char *localeID, char *country, int32_t countryCapacity, UErrorCode *err)
 Gets the country code for the specified locale. More...
 
U_CAPI int32_t uloc_getVariant (const char *localeID, char *variant, int32_t variantCapacity, UErrorCode *err)
 Gets the variant code for the specified locale. More...
 
U_CAPI int32_t uloc_getName (const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
 Gets the full name for the specified locale. More...
 
U_CAPI int32_t uloc_canonicalize (const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
 Gets the full name for the specified locale. More...
 
U_CAPI const char * uloc_getISO3Language (const char *localeID)
 Gets the ISO language code for the specified locale. More...
 
U_CAPI const char * uloc_getISO3Country (const char *localeID)
 Gets the ISO country code for the specified locale. More...
 
U_CAPI uint32_t uloc_getLCID (const char *localeID)
 Gets the Win32 LCID value for the specified locale. More...
 
U_CAPI 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. More...
 
U_CAPI 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. More...
 
U_CAPI 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. More...
 
U_CAPI 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. More...
 
U_CAPI 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. More...
 
U_CAPI 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. More...
 
U_CAPI 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. More...
 
U_CAPI const char * uloc_getAvailable (int32_t n)
 Gets the specified locale from a list of available locales. More...
 
U_CAPI int32_t uloc_countAvailable (void)
 Gets the size of the all available locale list. More...
 
U_CAPI UEnumerationuloc_openAvailableByType (ULocAvailableType type, UErrorCode *status)
 Gets a list of available locales according to the type argument, allowing the user to access different sets of supported locales in ICU. More...
 
U_CAPI const char *const * uloc_getISOLanguages (void)
 Gets a list of all available 2-letter language codes defined in ISO 639, plus additional 3-letter codes determined to be useful for locale generation as defined by Unicode CLDR. More...
 
U_CAPI const char *const * uloc_getISOCountries (void)
 Gets a list of all available 2-letter country codes defined in ISO 639. More...
 
U_CAPI 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. More...
 
U_CAPI int32_t uloc_getBaseName (const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
 Gets the full name for the specified locale, like uloc_getName(), but without keywords. More...
 
U_CAPI UEnumerationuloc_openKeywords (const char *localeID, UErrorCode *status)
 Gets an enumeration of keywords for the specified locale. More...
 
U_CAPI int32_t uloc_getKeywordValue (const char *localeID, const char *keywordName, char *buffer, int32_t bufferCapacity, UErrorCode *status)
 Get the value for a keyword. More...
 
U_CAPI int32_t uloc_setKeywordValue (const char *keywordName, const char *keywordValue, char *buffer, int32_t bufferCapacity, UErrorCode *status)
 Sets or removes the value of the specified keyword. More...
 
U_CAPI UBool uloc_isRightToLeft (const char *locale)
 Returns whether the locale's script is written right-to-left. More...
 
U_CAPI ULayoutType uloc_getCharacterOrientation (const char *localeId, UErrorCode *status)
 Get the layout character orientation for the specified locale. More...
 
U_CAPI ULayoutType uloc_getLineOrientation (const char *localeId, UErrorCode *status)
 Get the layout line orientation for the specified locale. More...
 
U_CAPI 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. More...
 
U_CAPI 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. More...
 
U_CAPI 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. More...
 
U_CAPI 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: More...
 
U_CAPI 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: More...
 
U_CAPI int32_t uloc_forLanguageTag (const char *langtag, char *localeID, int32_t localeIDCapacity, int32_t *parsedLength, UErrorCode *err)
 Returns a locale ID for the specified BCP47 language tag string. More...
 
U_CAPI int32_t uloc_toLanguageTag (const char *localeID, char *langtag, int32_t langtagCapacity, UBool strict, UErrorCode *err)
 Returns a well-formed language tag for this locale ID. More...
 
U_CAPI const char * uloc_toUnicodeLocaleKey (const char *keyword)
 Converts the specified keyword (legacy key, or BCP 47 Unicode locale extension key) to the equivalent BCP 47 Unicode locale extension key. More...
 
U_CAPI const char * uloc_toUnicodeLocaleType (const char *keyword, const char *value)
 Converts the specified keyword value (legacy type, or BCP 47 Unicode locale extension type) to the well-formed BCP 47 Unicode locale extension type for the specified keyword (category). More...
 
U_CAPI const char * uloc_toLegacyKey (const char *keyword)
 Converts the specified keyword (BCP 47 Unicode locale extension key, or legacy key) to the legacy key. More...
 
U_CAPI const char * uloc_toLegacyType (const char *keyword, const char *value)
 Converts the specified keyword value (BCP 47 Unicode locale extension type, or legacy type or type alias) to the canonical legacy type. More...
 

Detailed Description

C API: Locale ID functionality similar to C++ class 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 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, 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:

#define ULOC_US
Useful constant for this country/region.
Definition: uloc.h:244

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.

const char* myLocale = "fr_FR";
nf = unum_open( UNUM_DEFAULT, NULL, success );
nf = unum_open( UNUM_CURRENCY, NULL, success );
nf = unum_open( UNUM_PERCENT, NULL, success );
@ UNUM_CURRENCY
Currency format (generic).
Definition: unum.h:168
@ UNUM_PERCENT
Percent format.
Definition: unum.h:173
@ UNUM_DEFAULT
Default format.
Definition: unum.h:266
U_CAPI UNumberFormat * unum_open(UNumberFormatStyle style, const UChar *pattern, int32_t patternLength, const char *locale, UParseError *parseErr, UErrorCode *status)
Create and return a new UNumberFormat for formatting and parsing numbers.
void * UNumberFormat
A number formatter.
Definition: unum.h:144
U_CAPI void unum_close(UNumberFormat *fmt)
Close a UNumberFormat.
#define NULL
Define NULL if necessary, to nullptr for C++ and to ((void *)0) for C.
Definition: utypes.h:188
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
@ U_ZERO_ERROR
No error, no warning.
Definition: utypes.h:449

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 );
nf = unum_open( UNUM_CURRENCY, myLocale, success );
nf = unum_open( UNUM_PERCENT, myLocale, success );

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 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 classes implement these three class methods:

const char* uloc_getAvailable(int32_t index);
int32_t
uloc_getDisplayName(const char* localeID,
const char* inLocaleID,
UChar* result,
int32_t maxResultSize,
UErrorCode* err);
U_CAPI 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.
U_CAPI const char * uloc_getAvailable(int32_t n)
Gets the specified locale from a list of available locales.
U_CAPI int32_t uloc_countAvailable(void)
Gets the size of the all available locale list.
char16_t UChar
The base type for UTF-16 code units and pointers.
Definition: umachine.h:412

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.

Macro Definition Documentation

◆ ULOC_CANADA

#define ULOC_CANADA   "en_CA"

Useful constant for this country/region.

Stable:
ICU 2.0

Definition at line 222 of file uloc.h.

◆ ULOC_CANADA_FRENCH

#define ULOC_CANADA_FRENCH   "fr_CA"

Useful constant for this country/region.

Stable:
ICU 2.0

Definition at line 224 of file uloc.h.

◆ ULOC_CHINA

#define ULOC_CHINA   "zh_CN"

Useful constant for this country/region.

Stable:
ICU 2.0

Definition at line 226 of file uloc.h.

◆ ULOC_CHINESE

#define ULOC_CHINESE   "zh"

Useful constant for this language.

Stable:
ICU 2.0

Definition at line 203 of file uloc.h.

◆ ULOC_COUNTRY_CAPACITY

#define ULOC_COUNTRY_CAPACITY   4

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

Stable:
ICU 2.0

Definition at line 258 of file uloc.h.

◆ ULOC_ENGLISH

#define ULOC_ENGLISH   "en"

Useful constant for this language.

Stable:
ICU 2.0

Definition at line 205 of file uloc.h.

◆ ULOC_FRANCE

#define ULOC_FRANCE   "fr_FR"

Useful constant for this country/region.

Stable:
ICU 2.0

Definition at line 230 of file uloc.h.

◆ ULOC_FRENCH

#define ULOC_FRENCH   "fr"

Useful constant for this language.

Stable:
ICU 2.0

Definition at line 207 of file uloc.h.

◆ ULOC_FULLNAME_CAPACITY

#define ULOC_FULLNAME_CAPACITY   157

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

Stable:
ICU 2.0

Definition at line 264 of file uloc.h.

◆ ULOC_GERMAN

#define ULOC_GERMAN   "de"

Useful constant for this language.

Stable:
ICU 2.0

Definition at line 209 of file uloc.h.

◆ ULOC_GERMANY

#define ULOC_GERMANY   "de_DE"

Useful constant for this country/region.

Stable:
ICU 2.0

Definition at line 232 of file uloc.h.

◆ ULOC_ITALIAN

#define ULOC_ITALIAN   "it"

Useful constant for this language.

Stable:
ICU 2.0

Definition at line 211 of file uloc.h.

◆ ULOC_ITALY

#define ULOC_ITALY   "it_IT"

Useful constant for this country/region.

Stable:
ICU 2.0

Definition at line 234 of file uloc.h.

◆ ULOC_JAPAN

#define ULOC_JAPAN   "ja_JP"

Useful constant for this country/region.

Stable:
ICU 2.0

Definition at line 236 of file uloc.h.

◆ ULOC_JAPANESE

#define ULOC_JAPANESE   "ja"

Useful constant for this language.

Stable:
ICU 2.0

Definition at line 213 of file uloc.h.

◆ ULOC_KEYWORD_AND_VALUES_CAPACITY

#define ULOC_KEYWORD_AND_VALUES_CAPACITY   100

Useful constant for the maximum total size of keywords and their values in a locale.

Stable:
ICU 2.8

Definition at line 283 of file uloc.h.

◆ ULOC_KEYWORD_ASSIGN

#define ULOC_KEYWORD_ASSIGN   '='

Invariant character for assigning value to a keyword.

Stable:
ICU 2.8

Definition at line 302 of file uloc.h.

◆ ULOC_KEYWORD_ASSIGN_UNICODE

#define ULOC_KEYWORD_ASSIGN_UNICODE   0x3D

Unicode code point for '=' for assigning value to a keyword.

See also
ULOC_KEYWORD_ASSIGN
Stable:
ICU 4.6

Definition at line 309 of file uloc.h.

◆ ULOC_KEYWORD_ITEM_SEPARATOR

#define ULOC_KEYWORD_ITEM_SEPARATOR   ';'

Invariant character separating keywords.

Stable:
ICU 2.8

Definition at line 315 of file uloc.h.

◆ ULOC_KEYWORD_ITEM_SEPARATOR_UNICODE

#define ULOC_KEYWORD_ITEM_SEPARATOR_UNICODE   0x3B

Unicode code point for ';' separating keywords.

See also
ULOC_KEYWORD_ITEM_SEPARATOR
Stable:
ICU 4.6

Definition at line 322 of file uloc.h.

◆ ULOC_KEYWORD_SEPARATOR

#define ULOC_KEYWORD_SEPARATOR   '@'

Invariant character separating keywords from the locale string.

Stable:
ICU 2.8

Definition at line 289 of file uloc.h.

◆ ULOC_KEYWORD_SEPARATOR_UNICODE

#define ULOC_KEYWORD_SEPARATOR_UNICODE   0x40

Unicode code point for '@' separating keywords from the locale string.

See also
ULOC_KEYWORD_SEPARATOR
Stable:
ICU 4.6

Definition at line 296 of file uloc.h.

◆ ULOC_KEYWORDS_CAPACITY

#define ULOC_KEYWORDS_CAPACITY   96

Useful constant for the maximum size of keywords in a locale.

Stable:
ICU 2.8

Definition at line 277 of file uloc.h.

◆ ULOC_KOREA

#define ULOC_KOREA   "ko_KR"

Useful constant for this country/region.

Stable:
ICU 2.0

Definition at line 238 of file uloc.h.

◆ ULOC_KOREAN

#define ULOC_KOREAN   "ko"

Useful constant for this language.

Stable:
ICU 2.0

Definition at line 215 of file uloc.h.

◆ ULOC_LANG_CAPACITY

#define ULOC_LANG_CAPACITY   12

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

(including the terminating NULL).

Stable:
ICU 2.0

Definition at line 251 of file uloc.h.

◆ ULOC_PRC

#define ULOC_PRC   "zh_CN"

Useful constant for this country/region.

Stable:
ICU 2.0

Definition at line 228 of file uloc.h.

◆ ULOC_SCRIPT_CAPACITY

#define ULOC_SCRIPT_CAPACITY   6

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

Stable:
ICU 2.8

Definition at line 271 of file uloc.h.

◆ ULOC_SIMPLIFIED_CHINESE

#define ULOC_SIMPLIFIED_CHINESE   "zh_CN"

Useful constant for this language.

Stable:
ICU 2.0

Definition at line 217 of file uloc.h.

◆ ULOC_TAIWAN

#define ULOC_TAIWAN   "zh_TW"

Useful constant for this country/region.

Stable:
ICU 2.0

Definition at line 240 of file uloc.h.

◆ ULOC_TRADITIONAL_CHINESE

#define ULOC_TRADITIONAL_CHINESE   "zh_TW"

Useful constant for this language.

Stable:
ICU 2.0

Definition at line 219 of file uloc.h.

◆ ULOC_UK

#define ULOC_UK   "en_GB"

Useful constant for this country/region.

Stable:
ICU 2.0

Definition at line 242 of file uloc.h.

◆ ULOC_US

#define ULOC_US   "en_US"

Useful constant for this country/region.

Stable:
ICU 2.0

Definition at line 244 of file uloc.h.

Typedef Documentation

◆ ULocAvailableType

Types for uloc_getAvailableByType and uloc_countAvailableByType.

Stable:
ICU 65

Enumeration Type Documentation

◆ UAcceptResult

Output values which uloc_acceptLanguage() writes to the 'outResult' parameter.

See also
uloc_acceptLanguageFromHTTP
uloc_acceptLanguage
Stable:
ICU 3.2
Enumerator
ULOC_ACCEPT_FAILED 

No exact match was found.

Stable:
ICU 3.2
ULOC_ACCEPT_VALID 

An exact match was found.

Stable:
ICU 3.2
ULOC_ACCEPT_FALLBACK 

A fallback was found.

For example, the Accept-Language list includes 'ja_JP' and is matched with available locale 'ja'.

Stable:
ICU 3.2

Definition at line 1067 of file uloc.h.

◆ ULayoutType

enums for the return value for the character and line orientation functions.

Stable:
ICU 4.0

Definition at line 1028 of file uloc.h.

◆ ULocAvailableType

Types for uloc_getAvailableByType and uloc_countAvailableByType.

Stable:
ICU 65
Enumerator
ULOC_AVAILABLE_DEFAULT 

Locales that return data when passed to ICU APIs, but not including legacy or alias locales.

Stable:
ICU 65
ULOC_AVAILABLE_ONLY_LEGACY_ALIASES 

Legacy or alias locales that return data when passed to ICU APIs.

Examples of supported legacy or alias locales:

  • iw (alias to he)
  • mo (alias to ro)
  • zh_CN (alias to zh_Hans_CN)
  • sr_BA (alias to sr_Cyrl_BA)
  • ars (alias to ar_SA)

The locales in this set are disjoint from the ones in ULOC_AVAILABLE_DEFAULT. To get both sets at the same time, use ULOC_AVAILABLE_WITH_LEGACY_ALIASES.

Stable:
ICU 65
ULOC_AVAILABLE_WITH_LEGACY_ALIASES 

The union of the locales in ULOC_AVAILABLE_DEFAULT and ULOC_AVAILABLE_ONLY_LEGACY_ALIAS.

Stable:
ICU 65
ULOC_AVAILABLE_COUNT 
Internal:
Do not use. This API is for internal use only.

Definition at line 804 of file uloc.h.

◆ 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).

Stable:
ICU 2.1
Enumerator
ULOC_ACTUAL_LOCALE 

This is locale the data actually comes from.

Stable:
ICU 2.1
ULOC_VALID_LOCALE 

This is the most specific locale supported by ICU.

Stable:
ICU 2.1
ULOC_REQUESTED_LOCALE 

This is the requested locale.

Deprecated:
ICU 2.8
ULOC_DATA_LOCALE_TYPE_LIMIT 

One more than the highest normal ULocDataLocaleType value.

Deprecated:
ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 338 of file uloc.h.

Function Documentation

◆ uloc_acceptLanguage()

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

This is a thin wrapper over C++ class LocaleMatcher.

Parameters
result- buffer to accept the result locale
resultAvailablethe size of the result buffer.
outResult- An out parameter that contains the fallback status
acceptList- list of acceptable languages
acceptListCount- count of acceptList items
availableLocales- list of available locales to match
statusICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)
Returns
length needed for the locale.
Stable:
ICU 3.2

◆ uloc_acceptLanguageFromHTTP()

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

This is a thin wrapper over C++ class LocaleMatcher.

Parameters
result- buffer to accept the result locale
resultAvailablethe size of the result buffer.
outResult- An out parameter that contains the fallback status
httpAcceptLanguage- "Accept-Language:" header as per HTTP.
availableLocales- list of available locales to match
statusICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)
Returns
length needed for the locale.
Stable:
ICU 3.2

◆ uloc_addLikelySubtags()

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

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

Parameters
localeIDThe locale to maximize
maximizedLocaleIDThe maximized locale
maximizedLocaleIDCapacityThe capacity of the maximizedLocaleID buffer
errError information if maximizing the locale failed. If the length of the localeID and the null-terminator is greater than the maximum allowed size, or the localeId is not well-formed, the error code is U_ILLEGAL_ARGUMENT_ERROR.
Returns
The actual buffer size needed for the maximized locale. If it's greater than maximizedLocaleIDCapacity, the returned ID will be truncated. On error, the return value is -1.
Stable:
ICU 4.0

◆ uloc_canonicalize()

U_CAPI int32_t 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
localeIDthe locale to get the full name with
namethe full name for localeID
nameCapacitythe size of the name buffer to store the full name with
errerror 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.
Stable:
ICU 2.8

◆ uloc_countAvailable()

U_CAPI int32_t uloc_countAvailable ( void  )

Gets the size of the all available locale list.

Returns
the size of the locale list
Stable:
ICU 2.0

◆ uloc_forLanguageTag()

U_CAPI int32_t uloc_forLanguageTag ( const char *  langtag,
char *  localeID,
int32_t  localeIDCapacity,
int32_t *  parsedLength,
UErrorCode err 
)

Returns a locale ID for the specified BCP47 language tag string.

If the specified language tag contains any ill-formed subtags, the first such subtag and all following subtags are ignored.

This implements the 'Language-Tag' production of BCP 47, and so supports legacy language tags (marked as “Type: grandfathered” in BCP 47) (regular and irregular) as well as private use language tags.

Private use tags are represented as 'x-whatever', and legacy tags are converted to their canonical replacements where they exist.

Note that a few legacy tags have no modern replacement; these will be converted using the fallback described in the first paragraph, so some information might be lost.

Parameters
langtagthe input BCP47 language tag.
localeIDthe output buffer receiving a locale ID for the specified BCP47 language tag.
localeIDCapacitythe size of the locale ID output buffer.
parsedLengthif not NULL, successfully parsed length for the input language tag is set.
errerror information if receiving the locald ID failed.
Returns
the length of the locale ID.
Stable:
ICU 4.2

◆ uloc_getAvailable()

U_CAPI const char * uloc_getAvailable ( int32_t  n)

Gets the specified locale from a list of available locales.

This method corresponds to uloc_openAvailableByType called with the ULOC_AVAILABLE_DEFAULT type argument.

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
nthe specific locale name index of the available locale list; should not exceed the number returned by uloc_countAvailable.
Returns
a specified locale name of all available locales
Stable:
ICU 2.0

◆ uloc_getBaseName()

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

Gets the full name for the specified locale, like uloc_getName(), but without keywords.

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
localeIDthe locale to get the full name with
namefill in buffer for the name without keywords.
nameCapacitycapacity of the fill in buffer.
errerror 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.
Stable:
ICU 2.8

◆ uloc_getCharacterOrientation()

U_CAPI ULayoutType uloc_getCharacterOrientation ( const char *  localeId,
UErrorCode status 
)

Get the layout character orientation for the specified locale.

Parameters
localeIdlocale name
statusError status
Returns
an enum indicating the layout orientation for characters.
Stable:
ICU 4.0

◆ uloc_getCountry()

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

Gets the country code for the specified locale.

Parameters
localeIDthe locale to get the country code with
countrythe country code for localeID
countryCapacitythe size of the country buffer to store the
country code with
errerror 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.
Stable:
ICU 2.0

◆ uloc_getDefault()

U_CAPI const char * 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
System:

Do not use unless you know what you are doing.
Stable:
ICU 2.0

◆ uloc_getDisplayCountry()

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

Warning: this is for the region part of a valid locale ID; it cannot just be the region code (like "FR"). To get the display name for a region alone, or for other options, use ULocaleDisplayNames instead.

Parameters
localethe locale to get the displayable country code with. NULL may be used to specify the default.
displayLocaleSpecifies 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.
countrythe displayable country code for localeID.
countryCapacitythe size of the country buffer to store the displayable country code with.
statuserror information if retrieving the displayable country code failed. U_USING_DEFAULT_WARNING indicates that no data was found from the locale resources and a case canonicalized country code is placed into country as fallback.
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.
Stable:
ICU 2.0

◆ uloc_getDisplayKeyword()

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

E.g: for the locale string de_DE@collation=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_openKeywords("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
keywordThe keyword whose display string needs to be returned.
displayLocaleSpecifies 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.
destthe buffer to which the displayable keyword should be written.
destCapacityThe 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).
statuserror information if retrieving the displayable string failed. Should not be NULL and should not indicate failure on entry. U_USING_DEFAULT_WARNING indicates that no data was found from the locale resources and the keyword is placed into dest as fallback.
Returns
the actual buffer size needed for the displayable variant code.
See also
uloc_openKeywords
Stable:
ICU 2.8

◆ uloc_getDisplayKeywordValue()

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

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.

Parameters
localeThe locale to get the displayable variant code with. NULL may be used to specify the default.
keywordThe keyword for whose value should be used.
displayLocaleSpecifies 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.
destthe buffer to which the displayable keyword should be written.
destCapacityThe 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).
statuserror information if retrieving the displayable string failed. Should not be NULL and must not indicate failure on entry. U_USING_DEFAULT_WARNING indicates that no data was found from the locale resources and the value of the keyword is placed into dest as fallback.
Returns
the actual buffer size needed for the displayable variant code.
Stable:
ICU 2.8

◆ uloc_getDisplayLanguage()

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

Parameters
localethe locale to get the ISO language code with
displayLocaleSpecifies 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".
languagethe displayable language code for localeID
languageCapacitythe size of the language buffer to store the displayable language code with.
statuserror information if retrieving the displayable language code failed. U_USING_DEFAULT_WARNING indicates that no data was found from the locale resources and a case canonicalized language code is placed into language as fallback.
Returns
the actual buffer size needed for the displayable language code. If it's greater than languageCapacity, the returned language code will be truncated.
Stable:
ICU 2.0

◆ uloc_getDisplayName()

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

Parameters
localeIDthe locale to get the displayable name with. NULL may be used to specify the default.
inLocaleIDSpecifies 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.
resultthe displayable name for localeID
maxResultSizethe size of the name buffer to store the displayable full name with
errerror information if retrieving the displayable name failed
Returns
the actual buffer size needed for the displayable name. If it's greater than maxResultSize, the returned displayable name will be truncated.
Stable:
ICU 2.0

◆ uloc_getDisplayScript()

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

Parameters
localethe locale to get the displayable script code with. NULL may be used to specify the default.
displayLocaleSpecifies 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.
scriptthe displayable script for the localeID.
scriptCapacitythe size of the script buffer to store the displayable script code with.
statuserror information if retrieving the displayable script code failed. U_USING_DEFAULT_WARNING indicates that no data was found from the locale resources and a case canonicalized script code is placed into script as fallback.
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.
Stable:
ICU 2.8

◆ uloc_getDisplayVariant()

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

Parameters
localethe locale to get the displayable variant code with. NULL may be used to specify the default.
displayLocaleSpecifies 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.
variantthe displayable variant code for localeID.
variantCapacitythe size of the variant buffer to store the displayable variant code with.
statuserror information if retrieving the displayable variant code failed. U_USING_DEFAULT_WARNING indicates that no data was found from the locale resources and a case canonicalized variant code is placed into variant as fallback.
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.
Stable:
ICU 2.0

◆ uloc_getISO3Country()

U_CAPI const char * uloc_getISO3Country ( const char *  localeID)

Gets the ISO country code for the specified locale.

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

◆ uloc_getISO3Language()

U_CAPI const char * uloc_getISO3Language ( const char *  localeID)

Gets the ISO language code for the specified locale.

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

◆ uloc_getISOCountries()

U_CAPI const char *const * 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
Stable:
ICU 2.0

◆ uloc_getISOLanguages()

U_CAPI const char *const * uloc_getISOLanguages ( void  )

Gets a list of all available 2-letter language codes defined in ISO 639, plus additional 3-letter codes determined to be useful for locale generation as defined by Unicode CLDR.

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
Stable:
ICU 2.0

◆ uloc_getKeywordValue()

U_CAPI int32_t 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
localeIDlocale name containing the keyword ("de_DE@currency=EURO;collation=PHONEBOOK")
keywordNamename of the keyword for which we want the value; must not be NULL or empty, and must consist only of [A-Za-z0-9]. Case insensitive.
bufferreceiving buffer
bufferCapacitycapacity of receiving buffer
statuscontaining error code: e.g. buffer not big enough or ill-formed localeID or keywordName parameters.
Returns
the length of keyword value
Stable:
ICU 2.8

◆ uloc_getLanguage()

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

Gets the language code for the specified locale.

Parameters
localeIDthe locale to get the ISO language code with
languagethe language code for localeID
languageCapacitythe size of the language buffer to store the
language code with
errerror 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.
Stable:
ICU 2.0

◆ uloc_getLCID()

U_CAPI uint32_t 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.

LCIDs were deprecated with Windows Vista and Microsoft recommends that developers use BCP47 style tags instead (uloc_toLanguageTag).

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

◆ uloc_getLineOrientation()

U_CAPI ULayoutType uloc_getLineOrientation ( const char *  localeId,
UErrorCode status 
)

Get the layout line orientation for the specified locale.

Parameters
localeIdlocale name
statusError status
Returns
an enum indicating the layout orientation for lines.
Stable:
ICU 4.0

◆ uloc_getLocaleForLCID()

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

Parameters
hostIDthe Win32 LCID to translate
localethe output buffer for the ICU locale ID, which will be NUL-terminated if there is room.
localeCapacitythe size of the output buffer
statusan error is returned if the LCID is unrecognized or the output buffer is too small
Returns
actual the actual size of the locale ID, not including NUL-termination
Stable:
ICU 3.8

◆ uloc_getName()

U_CAPI int32_t 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
localeIDthe locale to get the full name with
namefill in buffer for the name without keywords.
nameCapacitycapacity of the fill in buffer.
errerror 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.
Stable:
ICU 2.0

◆ uloc_getParent()

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

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
localeIDInput locale ID string.
parentOutput string buffer for the parent locale ID.
parentCapacitySize of the output buffer.
errA UErrorCode value.
Returns
The length of the parent locale ID.
Stable:
ICU 2.0

◆ uloc_getScript()

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

Gets the script code for the specified locale.

Parameters
localeIDthe locale to get the ISO language code with
scriptthe language code for localeID
scriptCapacitythe size of the language buffer to store the
language code with
errerror 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.
Stable:
ICU 2.8

◆ uloc_getVariant()

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

Gets the variant code for the specified locale.

Parameters
localeIDthe locale to get the variant code with
variantthe variant code for localeID
variantCapacitythe size of the variant buffer to store the variant code with
errerror 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.
Stable:
ICU 2.0

◆ uloc_isRightToLeft()

U_CAPI UBool uloc_isRightToLeft ( const char *  locale)

Returns whether the locale's script is written right-to-left.

If there is no script subtag, then the likely script is used, see uloc_addLikelySubtags(). If no likely script is known, then false is returned.

A script is right-to-left according to the CLDR script metadata which corresponds to whether the script's letters have Bidi_Class=R or AL.

Returns true for "ar" and "en-Hebr", false for "zh" and "fa-Cyrl".

Parameters
localeinput locale ID
Returns
true if the locale's script is written right-to-left
Stable:
ICU 54

◆ uloc_minimizeSubtags()

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

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".)

Parameters
localeIDThe locale to minimize
minimizedLocaleIDThe minimized locale
minimizedLocaleIDCapacityThe capacity of the minimizedLocaleID buffer
errError information if minimizing the locale failed. If the length of the localeID and the null-terminator is greater than the maximum allowed size, or the localeId is not well-formed, the error code is U_ILLEGAL_ARGUMENT_ERROR.
Returns
The actual buffer size needed for the minimized locale. If it's greater than minimizedLocaleIDCapacity, the returned ID will be truncated. On error, the return value is -1.
Stable:
ICU 4.0

◆ uloc_openAvailableByType()

U_CAPI UEnumeration * uloc_openAvailableByType ( ULocAvailableType  type,
UErrorCode status 
)

Gets a list of available locales according to the type argument, allowing the user to access different sets of supported locales in ICU.

The returned UEnumeration must be closed by the caller.

Parameters
typeType choice from ULocAvailableType.
statusSet if an error occurred.
Returns
a UEnumeration owned by the caller, or nullptr on failure.
Stable:
ICU 65

◆ uloc_openKeywords()

U_CAPI UEnumeration * 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
localeIDthe locale to get the variant code with
statuserror information if retrieving the keywords failed
Returns
enumeration of keywords or NULL if there are no keywords.
Stable:
ICU 2.8

◆ uloc_setDefault()

U_CAPI void 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
localeIDthe new ICU default locale. A value of NULL will try to get the system's default locale.
statusthe error information if the setting of default locale fails
System:

Do not use unless you know what you are doing.
Stable:
ICU 2.0

◆ uloc_setKeywordValue()

U_CAPI int32_t uloc_setKeywordValue ( const char *  keywordName,
const char *  keywordValue,
char *  buffer,
int32_t  bufferCapacity,
UErrorCode status 
)

Sets or removes the value of the specified keyword.

For removing all keywords, use uloc_getBaseName().

NOTE: Unlike almost every other ICU function which takes a buffer, this function will NOT truncate the output text, and will not update the buffer with unterminated text setting a status of U_STRING_NOT_TERMINATED_WARNING. If a BUFFER_OVERFLOW_ERROR is received, it means a terminated version of the updated locale ID would not fit in the buffer, and the original buffer is untouched. This is done to prevent incorrect or possibly even malformed locales from being generated and used.

Parameters
keywordNamename of the keyword to be set; must not be NULL or empty, and must consist only of [A-Za-z0-9]. Case insensitive.
keywordValuevalue of the keyword to be set. If 0-length or NULL, will result in the keyword being removed; no error is given if that keyword does not exist. Otherwise, must consist only of [A-Za-z0-9] and [/_+-].
bufferinput buffer containing well-formed locale ID to be modified.
bufferCapacitycapacity of receiving buffer
statuscontaining error code: e.g. buffer not big enough or ill-formed keywordName or keywordValue parameters, or ill-formed locale ID in buffer on input.
Returns
the length needed for the buffer
See also
uloc_getKeywordValue
Stable:
ICU 3.2

◆ uloc_toLanguageTag()

U_CAPI int32_t uloc_toLanguageTag ( const char *  localeID,
char *  langtag,
int32_t  langtagCapacity,
UBool  strict,
UErrorCode err 
)

Returns a well-formed language tag for this locale ID.

Note: When strict is false, any locale fields which do not satisfy the BCP47 syntax requirement will be omitted from the result. When strict is true, this function sets U_ILLEGAL_ARGUMENT_ERROR to the err if any locale fields do not satisfy the BCP47 syntax requirement.

Parameters
localeIDthe input locale ID
langtagthe output buffer receiving BCP47 language tag for the locale ID.
langtagCapacitythe size of the BCP47 language tag output buffer.
strictboolean value indicating if the function returns an error for an ill-formed input locale ID.
errerror information if receiving the language tag failed.
Returns
The length of the BCP47 language tag.
Stable:
ICU 4.2

◆ uloc_toLegacyKey()

U_CAPI const char * uloc_toLegacyKey ( const char *  keyword)

Converts the specified keyword (BCP 47 Unicode locale extension key, or legacy key) to the legacy key.

For example, legacy key "collation" is returned for the input BCP 47 Unicode locale extension key "co".

Parameters
keywordthe input locale keyword (either BCP 47 Unicode locale extension key or legacy key).
Returns
the well-formed legacy key, or NULL if the specified keyword cannot be mapped to a well-formed legacy key.
See also
toUnicodeLocaleKey
Stable:
ICU 54

◆ uloc_toLegacyType()

U_CAPI const char * uloc_toLegacyType ( const char *  keyword,
const char *  value 
)

Converts the specified keyword value (BCP 47 Unicode locale extension type, or legacy type or type alias) to the canonical legacy type.

For example, the legacy type "phonebook" is returned for the input BCP 47 Unicode locale extension type "phonebk" with the keyword "collation" (or "co").

When the specified keyword is not recognized, but the specified value satisfies the syntax of legacy key, or when the specified keyword allows 'variable' type and the specified value satisfies the syntax, then the pointer to the input type value itself will be returned. For example, uloc_toLegacyType("Foo", "Bar") returns "Bar", uloc_toLegacyType("vt", "00A4") returns "00A4".

Parameters
keywordthe locale keyword (either legacy keyword such as "collation" or BCP 47 Unicode locale extension key such as "co").
valuethe locale keyword value (either BCP 47 Unicode locale extension type such as "phonebk" or legacy keyword value such as "phonebook").
Returns
the well-formed legacy type, or NULL if the specified keyword value cannot be mapped to a well-formed legacy type.
See also
toUnicodeLocaleType
Stable:
ICU 54

◆ uloc_toUnicodeLocaleKey()

U_CAPI const char * uloc_toUnicodeLocaleKey ( const char *  keyword)

Converts the specified keyword (legacy key, or BCP 47 Unicode locale extension key) to the equivalent BCP 47 Unicode locale extension key.

For example, BCP 47 Unicode locale extension key "co" is returned for the input keyword "collation".

When the specified keyword is unknown, but satisfies the BCP syntax, then the pointer to the input keyword itself will be returned. For example, uloc_toUnicodeLocaleKey("ZZ") returns "ZZ".

Parameters
keywordthe input locale keyword (either legacy key such as "collation" or BCP 47 Unicode locale extension key such as "co").
Returns
the well-formed BCP 47 Unicode locale extension key, or NULL if the specified locale keyword cannot be mapped to a well-formed BCP 47 Unicode locale extension key.
See also
uloc_toLegacyKey
Stable:
ICU 54

◆ uloc_toUnicodeLocaleType()

U_CAPI const char * uloc_toUnicodeLocaleType ( const char *  keyword,
const char *  value 
)

Converts the specified keyword value (legacy type, or BCP 47 Unicode locale extension type) to the well-formed BCP 47 Unicode locale extension type for the specified keyword (category).

For example, BCP 47 Unicode locale extension type "phonebk" is returned for the input keyword value "phonebook", with the keyword "collation" (or "co").

When the specified keyword is not recognized, but the specified value satisfies the syntax of the BCP 47 Unicode locale extension type, or when the specified keyword allows 'variable' type and the specified value satisfies the syntax, then the pointer to the input type value itself will be returned. For example, uloc_toUnicodeLocaleType("Foo", "Bar") returns "Bar", uloc_toUnicodeLocaleType("variableTop", "00A4") returns "00A4".

Parameters
keywordthe locale keyword (either legacy key such as "collation" or BCP 47 Unicode locale extension key such as "co").
valuethe locale keyword value (either legacy type such as "phonebook" or BCP 47 Unicode locale extension type such as "phonebk").
Returns
the well-formed BCP47 Unicode locale extension type, or NULL if the locale keyword value cannot be mapped to a well-formed BCP 47 Unicode locale extension type.
See also
uloc_toLegacyType
Stable:
ICU 54