A Locale
object represents a specific geographical, political, or cultural region. More...
#include <locid.h>
A Locale
object 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.
The Locale class is not suitable for subclassing.
You can create a Locale
object using the constructor in this class:
Locale( const char* language, const char* country, const char* variant);
The first argument to the constructors 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:
The second argument to the constructors is a valid 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.iso.org/iso/en/prods-services/iso3166ma/index.html
The third constructor requires a third argument–the Variant. The Variant codes are vendor and browser-specific. For example, use REVISED for a language's revised script orthography, 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_POSIX".
Because a Locale
object is just an identifier for a region, no validity check is performed when you construct a Locale
. If you want to see whether particular resources are available for the Locale
you construct, you must query those resources. For example, ask the NumberFormat
for the locales it supports using its getAvailableLocales
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 ResourceBundle
.
The Locale
class provides a number of convenient constants that you can use to create Locale
objects for commonly used locales. For example, the following refers to a Locale
object for the United States:
Locale::getUS()
Once you've created a Locale
you can query it for information about itself. Use getCountry
to get the ISO Country Code and getLanguage
to get the ISO Language Code. You can use getDisplayCountry
to get the name of the country suitable for displaying to the user. Similarly, you can use getDisplayLanguage
to get the name of the language suitable for displaying to the user. Interestingly, the 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.
ICU provides a number of classes that perform locale-sensitive operations. For example, the NumberFormat
class formats numbers, currency, or percentages in a locale-sensitive manner. Classes such as NumberFormat
have a number of convenience methods for creating a default object of that type. For example, the NumberFormat
class provides these three convenience methods for creating a default NumberFormat
object:
UErrorCode success = U_ZERO_ERROR; Locale myLocale; NumberFormat *nf; nf = NumberFormat::createInstance( success ); delete nf; nf = NumberFormat::createCurrencyInstance( success ); delete nf; nf = NumberFormat::createPercentInstance( success ); delete nf;
Each of these methods has two variants; one with an explicit locale and one without; the latter using the default locale.
nf = NumberFormat::createInstance( myLocale, success ); delete nf; nf = NumberFormat::createCurrencyInstance( myLocale, success ); delete nf; nf = NumberFormat::createPercentInstance( myLocale, success ); delete nf;
A
Locale
is the mechanism for identifying the kind of object (
NumberFormat
) that you would like to get. The locale is
justa mechanism for identifying objects,
nota container for the objects themselves.
Each class 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:
static Locale* getAvailableLocales(int32_t& numLocales) static UnicodeString& getDisplayName(const Locale& objectLocale, const Locale& displayLocale, UnicodeString& displayName) static UnicodeString& getDisplayName(const Locale& objectLocale, UnicodeString& displayName)
Definition at line 195 of file locid.h.
◆ Locale() [1/4] ◆ Locale() [2/4] icu::Locale::Locale ( const char * language, const char * country =nullptr
, const char * variant = nullptr
, const char * keywordsAndValues = nullptr
)
Construct a locale from language, country, variant.
If an error occurs, then the constructed object will be "bogus" (isBogus() will return true).
Move constructor; might leave source in bogus state.
This locale will have the same contents that the source locale had.
Add the likely subtags for this Locale, per the algorithm described in the following CLDR technical report:
http://www.unicode.org/reports/tr35/#Likely_Subtags
If this Locale is already in the maximal form, or not valid, or there is no data available for maximization, the Locale will be unchanged.
For example, "sh" cannot be maximized, since there is no reasonable maximization.
Examples:
"und_Zzzz" maximizes to "en_Latn_US"
"en" maximizes to "en_Latn_US"
"de" maximizes to "de_Latn_DE"
"sr" maximizes to "sr_Cyrl_RS"
"zh_Hani" maximizes to "zh_Hani_CN"
Canonicalize the locale ID of this object according to CLDR.
Clone this object.
Clones can be used concurrently in multiple threads. If an error occurs, then nullptr is returned. The caller must delete the clone.
Creates a locale from the given string after canonicalizing the string according to CLDR by calling uloc_canonicalize().
Creates a locale which has had minimal canonicalization as per uloc_getName().
This API is for internal use only.
◆ createKeywords()Gets the list of keywords for the specified locale.
Gets the list of Unicode keywords for the specified locale.
Returns a Locale 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.
Returns a list of all installed locales.
Returns the programmatic name of the entire locale as getName() would return, but without keywords.
Useful constant for this country/region.
Useful constant for this country/region.
Useful constant for this country/region.
Useful constant for this language.
Returns the locale's ISO-3166 country code.
Definition at line 1203 of file locid.h.
◆ getDefault() static const Locale& icu::Locale::getDefault ( ) staticCommon methods of getting the current default Locale.
Used for the presentation: menus, dialogs, etc. Generally set once when your applet or application is initialized, then never reset. (If you do reset the default locale, you probably want to reload your GUI, so that the change is reflected in your interface.)
More advanced programs will allow users to use different locales for different fields, e.g. in a spreadsheet.
Note that the initial setting will match the host system.
Fills in "dispCountry" with the name of this locale's country in a format suitable for user display in the locale specified by "displayLocale".
For example, if the locale's country code is "US" and displayLocale's language code is "fr", this function would set dispCountry to "États-Unis".
Fills in "dispCountry" with the name of this locale's country in a format suitable for user display in the default locale.
For example, if the locale's country code is "FR" and the default locale's language code is "en", this function would set dispCountry to "France".
Fills in "dispLang" with the name of this locale's language in a format suitable for user display in the locale specified by "displayLocale".
For example, if the locale's language code is "en" and displayLocale's language code is "fr", this function would set dispLang to "Anglais".
Fills in "dispLang" with the name of this locale's language in a format suitable for user display in the default locale.
For example, if the locale's language code is "fr" and the default locale's language code is "en", this function would set dispLang to "French".
Fills in "name" with the name of this locale in a format suitable for user display in the locale specified by "displayLocale".
This function uses getDisplayLanguage(), getDisplayCountry(), and getDisplayVariant() to do its work, and outputs the display name in the format "language (country[,variant])". For example, if displayLocale is fr_FR, then en_US's display name would be "Anglais (États-Unis)", and no_NO_NY's display name would be "norvégien (Norvège,NY)".
Fills in "name" with the name of this locale in a format suitable for user display in the default locale.
This function uses getDisplayLanguage(), getDisplayCountry(), and getDisplayVariant() to do its work, and outputs the display name in the format "language (country[,variant])". For example, if the default locale is en_US, then fr_FR's display name would be "French (France)", and es_MX_Traditional's display name would be "Spanish (Mexico,Traditional)".
Fills in "dispScript" with the name of this locale's country in a format suitable for user display in the locale specified by "displayLocale".
For example, if the locale's script code is "LATN" and displayLocale's language code is "en", this function would set dispScript to "Latin".
Fills in "dispScript" with the name of this locale's script in a format suitable for user display in the default locale.
For example, if the locale's script code is "LATN" and the default locale's language code is "en", this function would set dispScript to "Latin".
Fills in "dispVar" with the name of this locale's variant code in a format suitable for user display in the locale specified by "displayLocale".
Fills in "dispVar" with the name of this locale's variant code in a format suitable for user display in the default locale.
ICU "poor man's RTTI", returns a UClassID for the actual class.
Reimplemented from icu::UObject.
◆ getEnglish() static const Locale& icu::Locale::getEnglish ( ) staticUseful constant for this language.
Useful constant for this country/region.
Useful constant for this language.
Useful constant for this language.
Useful constant for this country/region.
Fills in "name" with the locale's three-letter ISO-3166 country code.
returns the locale's three-letter language code, as specified in ISO draft standard ISO-639-2.
Gets a list of all available 2-letter country codes defined in ISO 3166.
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 unique language codes defined in ISO 639.
They can be 2 or 3 letter codes, as defined by BCP 47, section 2.2.1. 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.
Useful constant for this language.
Useful constant for this country/region.
Useful constant for this country/region.
Useful constant for this language.
template<typename StringClass , typename OutputIterator >
void icu::Locale::getKeywords ( OutputIterator iterator, UErrorCode & status ) const inlineGets the set of keywords for this Locale.
A wrapper to call createKeywords() and write the resulting keywords as standard strings (or compatible objects) into any kind of container that can be written to by an STL style output iterator.
Definition at line 1233 of file locid.h.
References icu::LocalPointerBase< T >::isNull(), and U_FAILURE.
◆ getKeywordValue() [1/3] int32_t icu::Locale::getKeywordValue ( const char * keywordName, char * buffer, int32_t bufferCapacity, UErrorCode & status ) constGets the value for a keyword.
This uses legacy keyword=value pairs, like "collation=phonebook".
ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).
Gets the value for a keyword.
This uses legacy keyword=value pairs, like "collation=phonebook".
ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).
template<typename StringClass >
Gets the value for a keyword.
This uses legacy keyword=value pairs, like "collation=phonebook".
ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).
Definition at line 1269 of file locid.h.
References U_FAILURE.
◆ getKorea() static const Locale& icu::Locale::getKorea ( ) staticUseful constant for this country/region.
Useful constant for this language.
Returns the locale's ISO-639 language code.
Definition at line 1209 of file locid.h.
◆ getLCID() uint32_t icu::Locale::getLCID ( ) constReturns the Windows LCID value corresponding to this locale.
This value is stored in the resource data for the locale as a one-to-four-digit hexadecimal number. If the resource is missing, in the wrong format, or there is no Windows LCID value that corresponds to this locale, returns 0.
Returns the programmatic name of the entire locale, with the language, country and variant separated by underbars.
If a field is missing, up to two leading underbars will occur. Example: "en", "de_DE", "en_US_WIN", "de__POSIX", "fr__MAC", "__MAC", "_MT", "_FR_EURO"
Definition at line 1227 of file locid.h.
◆ getPRC() static const Locale& icu::Locale::getPRC ( ) staticUseful constant for this country/region.
Useful constant for the Root locale.
Useful constant for this language.
ICU "poor man's RTTI", returns a UClassID for this class.
Useful constant for this country/region.
Useful constant for this language.
Useful constant for this country/region.
template<typename StringClass , typename OutputIterator >
void icu::Locale::getUnicodeKeywords ( OutputIterator iterator, UErrorCode & status ) const inlineGets the set of Unicode keywords for this Locale.
A wrapper to call createUnicodeKeywords() and write the resulting keywords as standard strings (or compatible objects) into any kind of container that can be written to by an STL style output iterator.
Definition at line 1251 of file locid.h.
References icu::LocalPointerBase< T >::isNull(), and U_FAILURE.
◆ getUnicodeKeywordValue() [1/2]Gets the Unicode value for a Unicode keyword.
This uses Unicode key-value pairs, like "co-phonebk".
ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).
template<typename StringClass >
Gets the Unicode value for a Unicode keyword.
This uses Unicode key-value pairs, like "co-phonebk".
ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).
Definition at line 1279 of file locid.h.
References U_FAILURE.
◆ getUS() static const Locale& icu::Locale::getUS ( ) staticUseful constant for this country/region.
Returns the locale's variant code.
Definition at line 1221 of file locid.h.
◆ hashCode() int32_t icu::Locale::hashCode ( ) constGenerates a hash code for the locale.
Gets the bogus state.
Locale object can be bogus if it doesn't exist
Definition at line 1289 of file locid.h.
◆ isRightToLeft() UBool icu::Locale::isRightToLeft ( ) constReturns whether this 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".
Minimize the subtags for this Locale, per the algorithm described.
Minimize the subtags for this Locale, per the algorithm described in the following CLDR technical report:
http://www.unicode.org/reports/tr35/#Likely_Subtags
If this Locale is already in the minimal form, or not valid, or there is no data available for minimization, the Locale will be unchanged.
Since the minimization algorithm relies on proper maximization, see the comments for 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".)
Checks if two locale keys are not the same.
Definition at line 1187 of file locid.h.
References icu::operator==().
◆ operator=() [1/2]Replaces the entire contents of *this with the specified value.
Move assignment operator; might leave source in bogus state.
This locale will have the same contents that the source locale had. The behavior is undefined if *this and the source are the same object.
Checks if two locale keys are the same.
Sets the default.
Normally set once at the beginning of a process, then never reset. setDefault() only changes ICU's default locale ID, not the default locale ID of the runtime environment.
Set this from a single POSIX style locale string.
Sets or removes the value for a keyword.
For removing all keywords, use getBaseName(), and construct a new Locale if it differs from getName().
This uses legacy keyword=value pairs, like "collation=phonebook".
ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).
Definition at line 735 of file locid.h.
◆ setKeywordValue() [2/2]Sets or removes the value for a keyword.
For removing all keywords, use getBaseName(), and construct a new Locale if it differs from getName().
This uses legacy keyword=value pairs, like "collation=phonebook".
ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).
Sets the locale to bogus A bogus locale represents a non-existing locale associated with services that can be instantiated from non-locale data in addition to locale (for example, collation can be instantiated from a locale and from a rule set).
Sets or removes the Unicode value for a Unicode keyword.
For removing all keywords, use getBaseName(), and construct a new Locale if it differs from getName().
This uses Unicode key-value pairs, like "co-phonebk".
ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).
Returns a well-formed language tag for this Locale.
Note: Any locale fields which do not satisfy the BCP47 syntax requirement will be silently omitted from the result.
If this function fails, partial output may have been written to the sink.
template<typename StringClass >
StringClass icu::Locale::toLanguageTag ( UErrorCode & status ) const inlineReturns a well-formed language tag for this Locale.
Note: Any locale fields which do not satisfy the BCP47 syntax requirement will be silently omitted from the result.
Definition at line 1193 of file locid.h.
References U_FAILURE.
◆ locale_available_init void locale_available_init ( ) friendThis API is for internal use only. (private)
This API is for internal use only.
◆ locale_set_default_internalA friend to allow the default locale to be set by either the C or C++ API.
The documentation for this class was generated from the following file:
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4