Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Header Files   Compound Members   File Members  

Locale Class Reference

A Locale object represents a specific geographical, political, or cultural region. More...

#include <locid.h>

List of all members.


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

UnicodeStringgetLanguage ( UnicodeString& lang) const
Fills in "lang" with the locale's two-letter ISO-639 language code. More...

UnicodeStringgetCountry ( UnicodeString& cntry) const
Fills in "cntry" with the locale's two-letter ISO-3166 country code. More...

UnicodeStringgetVariant ( UnicodeString& var) const
Fills in "var" with the locale's variant code. More...

UnicodeStringgetName ( 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...

UnicodeStringgetISO3Language (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...

UnicodeStringgetISO3Language (UnicodeString& name) const
UnicodeStringgetISO3Country ( UnicodeString& name, UErrorCode& status) const
Fills in "name" with the locale's three-letter ISO-3166 country code. More...

UnicodeStringgetISO3Country ( UnicodeString& name) const
uint32_t getLCID (void) const
Returns the Windows LCID value corresponding to this locale. More...

UnicodeStringgetDisplayLanguage (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...

UnicodeStringgetDisplayLanguage ( 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...

UnicodeStringgetDisplayCountry ( 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...

UnicodeStringgetDisplayCountry ( 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...

UnicodeStringgetDisplayVariant ( 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...

UnicodeStringgetDisplayVariant ( 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...

UnicodeStringgetDisplayName ( UnicodeString& name) const
Fills in "name" with the name of this locale in a format suitable for user display in the default locale. More...

UnicodeStringgetDisplayName ( 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 UnicodeStringgetISOCountries (int32_t& count)
Returns a list of all 2-letter country codes defined in ISO 3166. More...

const UnicodeStringgetISOLanguages (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 UnicodeStringgetLanguagesForCountry ( 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...


Detailed Description

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.

You create a Locale object using one of the three constructors in this class:

 .      Locale( const   UnicodeString&  newLanguage);
 .
 .      Locale( const   UnicodeString&  language, 
 .              const   UnicodeString&  country);
 .
 .      Locale( const   UnicodeString&  language, 
 .              const   UnicodeString&  country, 
 .              const   UnicodeString&  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 a number of sites, such as:
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:

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

Member Function Documentation

Locale::Locale ()

Construct an empty locale.

It's only used when a fill-in parameter is needed.

Stable:

Locale::Locale (const UnicodeString & language, const UnicodeString & country, const UnicodeString & variant)

Construct a locale from language, country, variant.

Parameters:
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)
Stable:

Locale::Locale (const UnicodeString & language, const UnicodeString & country)

Construct a locale from language, country.

Parameters:
language   Lowercase two-letter ISO-639 code.
country   Uppercase two-letter ISO-3166 code. (optional)
Stable:

Locale::Locale (const UnicodeString & language)

Construct a locale from language.

Parameters:
language   Lowercase two-letter ISO-639 code.
Stable:

Locale::Locale (const Locale & other)

Initializes a Locale object from another Locale object.

Parameters:
other   The Locale object being copied in.
Stable:

Locale::~Locale ()

Destructor.

Stable:

Locale & Locale::operator= (const Locale & other)

Replaces the entire contents of *this with the specified value.

Parameters:
other   The Locale object being copied in.
Returns:
*this
Stable:

bool_t Locale::operator== (const Locale & other) const

Checks if two locale keys are the same.

Parameters:
other   The locale key object to be compared with this.
Returns:
True if the two locale keys are the same, false otherwise.
Stable:

bool_t Locale::operator!= (const Locale & other) const [inline]

Checks if two locale keys are not the same.

Parameters:
other   The locale key object to be compared with this.
Returns:
True if the two locale keys are not the same, false otherwise.
Stable:

UnicodeString & Locale::getLanguage (UnicodeString & lang) const

Fills in "lang" with the locale's two-letter ISO-639 language code.

Parameters:
lang   Receives the language code.
Returns:
A reference to "lang".
Stable:

UnicodeString & Locale::getCountry (UnicodeString & cntry) const

Fills in "cntry" with the locale's two-letter ISO-3166 country code.

Parameters:
cntry   Receives the country code.
Returns:
A reference to "cntry".
Stable:

UnicodeString & Locale::getVariant (UnicodeString & var) const

Fills in "var" with the locale's variant code.

Parameters:
var   Receives the variant code.
Returns:
A reference to "var".
Stable:

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"

Parameters:
var   Receives the programmatic locale name.
Returns:
A reference to "name".
Stable:

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"

Returns:
A pointer to "name".

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

Parameters:
name   Receives the three-letter language code.
status   An UErrorCode to receive any MISSING_RESOURCE_ERRORs
Returns:
A reference to "name".
Stable:

UnicodeString & Locale::getISO3Language (UnicodeString & name) const

Deprecated:
use getISO3Language(UnicodeString&, UErrorCode&) instead

UnicodeString & Locale::getISO3Country (UnicodeString & name, UErrorCode & status) const

Fills in "name" with the locale's three-letter ISO-3166 country code.

Parameters:
name   Receives the three-letter country code.
status   An UErrorCode to receive any MISSING_RESOURCE_ERRORs
Returns:
A reference to "name".
Stable:

UnicodeString & Locale::getISO3Country (UnicodeString & name) const

Deprecated:
use getISO3Country(UnicodeString&, UErrorCode&); instead

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.

Stable:

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

Parameters:
dispLang   Receives the language's display name.
Returns:
A reference to "dispLang".
Stable:

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

Parameters:
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.
Returns:
A reference to "dispLang".
Stable:

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

Parameters:
dispCountry   Receives the country's display name.
Returns:
A reference to "dispCountry".
Stable:

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

Parameters:
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.
Returns:
A reference to "dispCountry".
Stable:

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.

Parameters:
dispVar   Receives the variant's name.
Returns:
A reference to "dispVar".
Stable:

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

Parameters:
inLocale   Specifies the locale to be used to display the name.
dispVar   Receives the variant's display name.
Returns:
A reference to "dispVar".
Stable:

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

Parameters:
name   Receives the locale's display name.
Returns:
A reference to "name".
Stable:

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

Parameters:
inLocale   Specifies the locale to be used to display the name.
name   Receives the locale's display name.
Returns:
A reference to "name".
Stable:

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.

Stable:

Locale & Locale::init (const char * cLocaleID)

Initialize the locale object with a new name.

Parameters:
cLocaleID   The new locale name.
Deprecated:

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.

System:
Stable:

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.

Parameters:
newLocale   Locale to set to.
System:
Stable:

const Locale * Locale::getAvailableLocales (int32_t & count) [static]

Returns a list of all installed locales.

Parameters:
count   Receives the number of locales in the list.
Returns:
A pointer to an array of Locale objects. This array is the list of all locales with installed resource files. The called does NOT get ownership of this list, and must NOT delete it.
Stable:

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.

Parameters:
count   Receives the number of countries in the list.
Returns:
A pointer to an array of UnicodeString objects. The caller does NOT get ownership of this list, and must NOT delete it.
Stable:

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

Parameters:
count   Receives the number of languages in the list.
Returns:
A pointer to an array of UnicodeString objects. The caller does NOT get ownership of this list, and must NOT delete it.
Stable:

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

Returns:
Current data path.
Deprecated:
1999dec14

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.

Parameters:
path   The new data path to be set to.
Deprecated:
1999dec14

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

Parameters:
country   The ISO 2-letter country code of the desired country
count   Receives the number of languages in the list.
Returns:
A pointer to an array of UnicodeString objects. The caller does NOT get ownership of this list, and must NOT delete it.

Member Data Documentation

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]


The documentation for this class was generated from the following file:
Generated at Thu Feb 10 15:30:46 2000 for icu by doxygen 1.0.0 written by Dimitri van Heesch, © 1997-1999