Locale
object represents a specific geographical, political, or cultural region.
More...
#include <locid.h>
Public Members | |||
![]() | ![]() | Locale () | |
![]() | ![]() | Construct an empty locale. More... | |
![]() | ![]() | Locale ( const UnicodeString& language, const UnicodeString& country , const UnicodeString& variant ) | |
![]() | ![]() | Construct a locale from language, country, variant. More... | |
![]() | ![]() | Locale ( const UnicodeString& language, const UnicodeString& country ) | |
![]() | ![]() | Construct a locale from language, country. More... | |
![]() | ![]() | Locale ( const UnicodeString& language) | |
![]() | ![]() | Construct a locale from language. More... | |
![]() | ![]() | Locale (const Locale& other) | |
![]() | ![]() | Initializes a Locale object from another Locale object. More... | |
![]() | ![]() | ~Locale () | |
![]() | ![]() | Destructor. More... | |
![]() | ![]() | Locale& | operator= (const Locale& other) |
![]() | ![]() | Replaces the entire contents of *this with the specified value. More... | |
![]() | ![]() | bool_t | operator== (const Locale& other) const |
![]() | ![]() | Checks if two locale keys are the same. More... | |
![]() | ![]() | bool_t | operator!= (const Locale& other) const |
![]() | ![]() | Checks if two locale keys are not the same. More... | |
![]() | ![]() | UnicodeString& | getLanguage ( UnicodeString& lang) const |
![]() | ![]() | Fills in "lang" with the locale's two-letter ISO-639 language code. More... | |
![]() | ![]() | UnicodeString& | getCountry ( UnicodeString& cntry) const |
![]() | ![]() | Fills in "cntry" with the locale's two-letter ISO-3166 country code. More... | |
![]() | ![]() | UnicodeString& | getVariant ( UnicodeString& var) const |
![]() | ![]() | Fills in "var" with the locale's variant code. More... | |
![]() | ![]() | UnicodeString& | getName ( UnicodeString& name) const |
![]() | ![]() | Fills in "name" the programmatic name of the entire locale, with the language, country and variant separated by underbars. More... | |
![]() | ![]() | const char* | getName () const |
![]() | ![]() | Returns the programmatic name of the entire locale, with the language, country and variant separated by underbars. More... | |
![]() | ![]() | UnicodeString& | getISO3Language (UnicodeString& name, UErrorCode& status) const |
![]() | ![]() | Fills in "name" with the locale's three-letter language code, as specified in ISO draft standard ISO-639-2.. More... | |
![]() | ![]() | UnicodeString& | getISO3Language (UnicodeString& name) const |
![]() | ![]() | UnicodeString& | getISO3Country ( UnicodeString& name, UErrorCode& status) const |
![]() | ![]() | Fills in "name" with the locale's three-letter ISO-3166 country code. More... | |
![]() | ![]() | UnicodeString& | getISO3Country ( UnicodeString& name) const |
![]() | ![]() | uint32_t | getLCID (void) const |
![]() | ![]() | Returns the Windows LCID value corresponding to this locale. More... | |
![]() | ![]() | UnicodeString& | getDisplayLanguage (UnicodeString& dispLang) const |
![]() | ![]() | Fills in "dispLang" with the name of this locale's language in a format suitable for user display in the default locale. More... | |
![]() | ![]() | UnicodeString& | getDisplayLanguage ( const Locale& inLocale, UnicodeString& dispLang) const |
![]() | ![]() | Fills in "dispLang" with the name of this locale's language in a format suitable for user display in the locale specified by "inLocale". More... | |
![]() | ![]() | UnicodeString& | getDisplayCountry ( UnicodeString& dispCountry) const |
![]() | ![]() | Fills in "dispCountry" with the name of this locale's country in a format suitable for user display in the default locale. More... | |
![]() | ![]() | UnicodeString& | getDisplayCountry ( const Locale& inLocale, UnicodeString& dispCountry) const |
![]() | ![]() | Fills in "dispCountry" with the name of this locale's country in a format suitable for user display in the locale specified by "inLocale". More... | |
![]() | ![]() | UnicodeString& | getDisplayVariant ( UnicodeString& dispVar) const |
![]() | ![]() | Fills in "dispVar" with the name of this locale's variant code in a format suitable for user display in the default locale. More... | |
![]() | ![]() | UnicodeString& | getDisplayVariant ( const Locale& inLocale, UnicodeString& dispVar) const |
![]() | ![]() | Fills in "dispVar" with the name of this locale's variant code in a format suitable for user display in the locale specified by "inLocale". More... | |
![]() | ![]() | UnicodeString& | getDisplayName ( UnicodeString& name) const |
![]() | ![]() | Fills in "name" with the name of this locale in a format suitable for user display in the default locale. More... | |
![]() | ![]() | UnicodeString& | getDisplayName ( const Locale& inLocale, UnicodeString& name) const |
![]() | ![]() | Fills in "name" with the name of this locale in a format suitable for user display in the locale specfied by "inLocale". More... | |
![]() | ![]() | int32_t | hashCode (void) const |
![]() | ![]() | Generates a hash code for the locale. More... | |
![]() | ![]() | Locale& | init (const char* cLocaleID) |
![]() | ![]() | Initialize the locale object with a new name. More... | |
Static Public Members | |||
![]() | ![]() | Locale& | getDefault (void) |
![]() | ![]() | Common methods of getting the current default Locale. More... | |
![]() | ![]() | void | setDefault (const Locale& newLocale, UErrorCode& success) |
![]() | ![]() | Sets the default. More... | |
![]() | ![]() | const Locale* | getAvailableLocales (int32_t& count) |
![]() | ![]() | Returns a list of all installed locales. More... | |
![]() | ![]() | const UnicodeString* | getISOCountries (int32_t& count) |
![]() | ![]() | Returns a list of all 2-letter country codes defined in ISO 3166. More... | |
![]() | ![]() | const UnicodeString* | getISOLanguages (int32_t& count) |
![]() | ![]() | Returns a list of all 2-letter language codes defined in ISO 639. More... | |
![]() | ![]() | const char* | getDataDirectory (void) |
![]() | ![]() | Deprecated 1999dec14 - Get the path to the ResourceBundle locale files. More... | |
![]() | ![]() | void | setDataDirectory (const char* path) |
![]() | ![]() | Deprecated 1999dec14 - Set the path to the ResourceBundle locale files. More... | |
![]() | ![]() | const Locale | ENGLISH |
![]() | ![]() | Useful constants for language. | |
![]() | ![]() | const Locale | FRENCH |
![]() | ![]() | const Locale | GERMAN |
![]() | ![]() | const Locale | ITALIAN |
![]() | ![]() | const Locale | JAPANESE |
![]() | ![]() | const Locale | KOREAN |
![]() | ![]() | const Locale | CHINESE |
![]() | ![]() | const Locale | SIMPLIFIED_CHINESE |
![]() | ![]() | const Locale | TRADITIONAL_CHINESE |
![]() | ![]() | const Locale | FRANCE |
![]() | ![]() | Useful constants for country. | |
![]() | ![]() | const Locale | GERMANY |
![]() | ![]() | const Locale | ITALY |
![]() | ![]() | const Locale | JAPAN |
![]() | ![]() | const Locale | KOREA |
![]() | ![]() | const Locale | CHINA |
![]() | ![]() | const Locale | PRC |
![]() | ![]() | const Locale | TAIWAN |
![]() | ![]() | const Locale | UK |
![]() | ![]() | const Locale | US |
![]() | ![]() | const Locale | CANADA |
![]() | ![]() | const Locale | CANADA_FRENCH |
Protected Members | |||
![]() | ![]() | void | setFromPOSIXID (const UnicodeString& posixID) |
![]() | ![]() | void | setFromPOSIXID (const char *posixID) |
Static Protected Members | |||
![]() | ![]() | const UnicodeString* | getLanguagesForCountry ( const UnicodeString& country, int32_t& count) |
![]() | ![]() | Given an ISO country code, returns an array of Strings containing the ISO codes of the languages spoken in that country. More... |
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.
You create a Locale
object using one of the three constructors in this class:
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 a number of sites, such as:. Locale( const UnicodeString& newLanguage); . . Locale( const UnicodeString& language, . const UnicodeString& country); . . Locale( const UnicodeString& language, . const UnicodeString& country, . const UnicodeString& variant);
http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
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.chemie.fu-berlin.de/diverse/doc/ISO_3166.html
The third constructor requires a third argument--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
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::US
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.
The TIFC 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:
Each of these methods has two variants; one with an explicit locale and one without; the latter using the default locale.. UErrorCode success = U_ZERO_ERROR; . Locale myLocale; . NumberFormat *nf; . . nf = NumberFormat::createInstance( success ); delete nf; . nf = NumberFormat::createCurrencyInstance( success ); delete nf; . nf = NumberFormat::createPercentInstance( success ); delete nf;
A. nf = NumberFormat::createInstance( myLocale, success ); delete nf; . nf = NumberFormat::createCurrencyInstance( myLocale, success ); delete nf; . nf = NumberFormat::createPercentInstance( myLocale, success ); delete nf;
Locale
is the mechanism for identifying the kind of object (NumberFormat
) that you would like to get. The locale is just a mechanism for identifying objects, not a 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)
Locale::Locale () |
Construct an empty locale.
It's only used when a fill-in parameter is needed.
Locale::Locale (const UnicodeString & language, const UnicodeString & country, const UnicodeString & variant) |
Construct a locale from language, country, variant.
language | Lowercase two-letter ISO-639 code. |
country | Uppercase two-letter ISO-3166 code. (optional) |
variant | Uppercase vendor and browser specific code. See class description. (optional) |
Locale::Locale (const UnicodeString & language, const UnicodeString & country) |
Construct a locale from language, country.
language | Lowercase two-letter ISO-639 code. |
country | Uppercase two-letter ISO-3166 code. (optional) |
Locale::Locale (const UnicodeString & language) |
Construct a locale from language.
language | Lowercase two-letter ISO-639 code. |
Locale::Locale (const Locale & other) |
Initializes a Locale object from another Locale object.
other | The Locale object being copied in. |
Locale::~Locale () |
Destructor.
Locale & Locale::operator= (const Locale & other) |
Replaces the entire contents of *this with the specified value.
other | The Locale object being copied in. |
bool_t Locale::operator== (const Locale & other) const |
Checks if two locale keys are the same.
other | The locale key object to be compared with this. |
bool_t Locale::operator!= (const Locale & other) const [inline]
|
Checks if two locale keys are not the same.
other | The locale key object to be compared with this. |
UnicodeString & Locale::getLanguage (UnicodeString & lang) const |
Fills in "lang" with the locale's two-letter ISO-639 language code.
lang | Receives the language code. |
UnicodeString & Locale::getCountry (UnicodeString & cntry) const |
Fills in "cntry" with the locale's two-letter ISO-3166 country code.
cntry | Receives the country code. |
UnicodeString & Locale::getVariant (UnicodeString & var) const |
Fills in "var" with the locale's variant code.
var | Receives the variant code. |
UnicodeString & Locale::getName (UnicodeString & name) const |
Fills in "name" the programmatic name of the entire locale, with the language, country and variant separated by underbars.
If a field is missing, at most one underbar will occur. Example: "en", "de_DE", "en_US_WIN", "de_POSIX", "fr_MAC"
var | Receives the programmatic locale name. |
const char * Locale::getName () const |
Returns the programmatic name of the entire locale, with the language, country and variant separated by underbars.
If a field is missing, at most one underbar will occur. Example: "en", "de_DE", "en_US_WIN", "de_POSIX", "fr_MAC"
UnicodeString & Locale::getISO3Language (UnicodeString & name, UErrorCode & status) const |
Fills in "name" with the locale's three-letter language code, as specified in ISO draft standard ISO-639-2..
name | Receives the three-letter language code. |
status | An UErrorCode to receive any MISSING_RESOURCE_ERRORs |
UnicodeString & Locale::getISO3Language (UnicodeString & name) const |
UnicodeString & Locale::getISO3Country (UnicodeString & name, UErrorCode & status) const |
Fills in "name" with the locale's three-letter ISO-3166 country code.
name | Receives the three-letter country code. |
status | An UErrorCode to receive any MISSING_RESOURCE_ERRORs |
UnicodeString & Locale::getISO3Country (UnicodeString & name) const |
uint32_t Locale::getLCID (void) const |
Returns 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.
UnicodeString & Locale::getDisplayLanguage (UnicodeString & dispLang) const |
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".
dispLang | Receives the language's display name. |
UnicodeString & Locale::getDisplayLanguage (const Locale & inLocale, UnicodeString & dispLang) const |
Fills in "dispLang" with the name of this locale's language in a format suitable for user display in the locale specified by "inLocale".
For example, if the locale's language code is "en" and inLocale's language code is "fr", this function would set dispLang to "Anglais".
inLocale | Specifies the locale to be used to display the name. In other words, if the locale's language code is "en", passing Locale::FRENCH for inLocale would result in "Anglais", while passing Locale::GERMAN for inLocale would result in "Englisch". |
dispLang | Receives the language's display name. |
UnicodeString & Locale::getDisplayCountry (UnicodeString & dispCountry) const |
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".
dispCountry | Receives the country's display name. |
UnicodeString & Locale::getDisplayCountry (const Locale & inLocale, UnicodeString & dispCountry) const |
Fills in "dispCountry" with the name of this locale's country in a format suitable for user display in the locale specified by "inLocale".
For example, if the locale's country code is "US" and inLocale's language code is "fr", this function would set dispCountry to "Etats-Unis".
inLocale | Specifies the locale to be used to display the name. In other words, if the locale's country code is "US", passing Locale::FRENCH for inLocale would result in "États-Unis", while passing Locale::GERMAN for inLocale would result in "Vereinigte Staaten". |
dispCountry | Receives the country's display name. |
UnicodeString & Locale::getDisplayVariant (UnicodeString & dispVar) const |
Fills in "dispVar" with the name of this locale's variant code in a format suitable for user display in the default locale.
dispVar | Receives the variant's name. |
UnicodeString & Locale::getDisplayVariant (const Locale & inLocale, UnicodeString & dispVar) const |
Fills in "dispVar" with the name of this locale's variant code in a format suitable for user display in the locale specified by "inLocale".
inLocale | Specifies the locale to be used to display the name. |
dispVar | Receives the variant's display name. |
UnicodeString & Locale::getDisplayName (UnicodeString & name) const |
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)".
name | Receives the locale's display name. |
UnicodeString & Locale::getDisplayName (const Locale & inLocale, UnicodeString & name) const |
Fills in "name" with the name of this locale in a format suitable for user display in the locale specfied by "inLocale".
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 inLocale 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)".
inLocale | Specifies the locale to be used to display the name. |
name | Receives the locale's display name. |
int32_t Locale::hashCode (void) const |
Generates a hash code for the locale.
Since Locales are often used in hashtables, caches the value for speed.
Locale & Locale::init (const char * cLocaleID) |
Initialize the locale object with a new name.
cLocaleID | The new locale name. |
Locale & Locale::getDefault (void) [static]
|
Common 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.
void Locale::setDefault (const Locale & newLocale, UErrorCode & success) [static]
|
Sets the default.
Normally set once at the beginning of applet or application, then never reset. setDefault does NOT reset the host locale.
newLocale | Locale to set to. |
const Locale * Locale::getAvailableLocales (int32_t & count) [static]
|
Returns a list of all installed locales.
count | Receives the number of locales in the list. |
const UnicodeString * Locale::getISOCountries (int32_t & count) [static]
|
Returns a list of all 2-letter country codes defined in ISO 3166.
Can be used to create Locales.
count | Receives the number of countries in the list. |
const UnicodeString * Locale::getISOLanguages (int32_t & count) [static]
|
Returns a list of all 2-letter language codes defined in ISO 639.
Can be used to create Locales. [NOTE: ISO 639 is not a stable standard-- some languages' codes have changed. The list this function returns includes both the new and the old codes for the languages whose codes have changed.]
count | Receives the number of languages in the list. |
const char * Locale::getDataDirectory (void) [static]
|
Deprecated 1999dec14 - Get the path to the ResourceBundle locale files.
This path will be a platform-specific path name ending in a directory separator, so that file names may be concatenated to it. This path may be changed by calling setDataDirectory(). If setDataDirectory() has not been called yet, getDataDirectory() will return a platform-dependent default path as specified by TPlatformUtilities::getDefaultDataDirectory().
void Locale::setDataDirectory (const char * path) [static]
|
Deprecated 1999dec14 - Set the path to the ResourceBundle locale files.
After making this call, all objects in the Unicode Analytics package will read ResourceBundle data files in the specified directory in order to obtain locale data.
path | The new data path to be set to. |
void Locale::setFromPOSIXID (const UnicodeString & posixID) [protected]
|
void Locale::setFromPOSIXID (const char * posixID) [protected]
|
const UnicodeString * Locale::getLanguagesForCountry (const UnicodeString & country, int32_t & count) [static, protected]
|
Given an ISO country code, returns an array of Strings containing the ISO codes of the languages spoken in that country.
Official languages are listed in the returned table before unofficial languages, but other than that, the order of the returned list is indeterminate. If the value the user passes in for "country" is not a valid ISO 316 country code, or if we don't have language information for the specified country, this function returns an empty array.
[This function is not currently part of Locale's API, but is needed in the implementation. We hope to add it to the API in a future release.]
country | The ISO 2-letter country code of the desired country |
count | Receives the number of languages in the list. |
const Locale Locale::ENGLISH [static]
|
Useful constants for language.
const Locale Locale::FRENCH [static]
|
const Locale Locale::GERMAN [static]
|
const Locale Locale::ITALIAN [static]
|
const Locale Locale::JAPANESE [static]
|
const Locale Locale::KOREAN [static]
|
const Locale Locale::CHINESE [static]
|
const Locale Locale::SIMPLIFIED_CHINESE [static]
|
const Locale Locale::TRADITIONAL_CHINESE [static]
|
const Locale Locale::FRANCE [static]
|
Useful constants for country.
const Locale Locale::GERMANY [static]
|
const Locale Locale::ITALY [static]
|
const Locale Locale::JAPAN [static]
|
const Locale Locale::KOREA [static]
|
const Locale Locale::CHINA [static]
|
const Locale Locale::PRC [static]
|
const Locale Locale::TAIWAN [static]
|
const Locale Locale::UK [static]
|
const Locale Locale::US [static]
|
const Locale Locale::CANADA [static]
|
const Locale Locale::CANADA_FRENCH [static]
|