Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   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 Methods

 Locale ()
 Construct an empty locale. More...

 Locale ( const char * language, const char * country = 0, const char * variant = 0)
 Construct a locale from language, country, variant. 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...

UBool operator== (const Locale& other) const
 Checks if two locale keys are the same. More...

UBool operator!= (const Locale& other) const
 Checks if two locale keys are not the same. More...

const char* getLanguage ( ) const
 Returns the locale's two-letter ISO-639 language code. More...

const char* getCountry ( ) const
 Returns the locale's two-letter ISO-3166 country code. More...

const char* getVariant ( ) const
 Returns the locale's variant code. More...

const char* getName () const
 Returns the programmatic name of the entire locale, with the language, country and variant separated by underbars. More...

const char* getISO3Language () const
 returns the locale's three-letter language code, as specified in ISO draft standard ISO-639-2.. More...

const char* getISO3Country () const
 Fills in "name" with the locale's three-letter ISO-3166 country code. More...

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


Static Public Methods

Locale& getDefault (void)
 Common methods of getting the current default Locale. More...

void setDefault (const Locale& newLocale, UErrorCode& success)
 Sets the default. More...

Locale createFromName (const char *name)
 Creates a locale which has had minimal canonicalization as per uloc_getName(). More...

const Locale* getAvailableLocales (int32_t& count)
 Returns a list of all installed locales. More...

const char* const* getISOCountries ()
 Gets a list of all available 2-letter country codes defined in ISO 639. More...

const char* const* getISOLanguages ()
 Gets a list of all available language codes defined in ISO 639. More...


Static Public Attributes

const Locale ENGLISH
 Useful constants for language. More...

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

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 Methods

void setFromPOSIXID (const char *posixID)

Static Protected Methods

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


Private Methods

Locale& init (const char* cLocaleID)
 Initialize the locale object with a new name. More...


Private Attributes

char language [ULOC_LANG_CAPACITY]
char country [ULOC_COUNTRY_CAPACITY]
char* variant
char* fullName
char fullNameBuffer [ULOC_FULLNAME_CAPACITY]

Static Private Attributes

Locale* localeList
int32_t localeListCount
UnicodeStringisoLanguages
int32_t isoLanguagesCount
UnicodeStringisoCountries
int32_t isoCountriesCount
UHashtablectry2LangMapping
const UnicodeString compressedCtry2LangMapping
Locale fgDefaultLocale

Friends

void locale_set_default_internal (const char *)


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

Definition at line 177 of file locid.h.


Constructor & Destructor Documentation

Locale::Locale ( )
 

Construct an empty locale.

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

Stable:

Locale::Locale ( const char * language,
const char * country = 0,
const char * variant = 0 )
 

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)
Draft:

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:


Member Function Documentation

Locale Locale::createFromName ( const char * name ) [static]
 

Creates a locale which has had minimal canonicalization as per uloc_getName().

Parameters:
name   The name to create from
Returns:
new locale object
Draft:
See also:
uloc_getName

const Locale * Locale::getAvailableLocales ( int32_t & numLocales ) [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 char * Locale::getCountry ( ) const
 

Returns the locale's two-letter ISO-3166 country code.

Returns:
An alias to the code
Draft:

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:

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

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

const char * Locale::getISO3Country ( ) const
 

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

Returns:
An alias to the code, or NULL
Draft:

const char * Locale::getISO3Language ( ) const
 

returns the locale's three-letter language code, as specified in ISO draft standard ISO-639-2..

Returns:
An alias to the code, or NULL
Draft:

const char *const * Locale::getISOCountries ( ) [static]
 

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

const char *const * Locale::getISOLanguages ( ) [static]
 

Gets a list of all available language codes defined in ISO 639.

This is a pointer to an array of pointers to arrays of char. All of these pointers are owned by ICU-- do not delete them, and do not write through them. The array is terminated with a null pointer.

Returns:
a list of all available language codes
Draft:

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:

const char * Locale::getLanguage ( ) const
 

Returns the locale's two-letter ISO-639 language code.

Returns:
An alias to the code
Draft:

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.

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, up to two leading underbars will occur. Example: "en", "de_DE", "en_US_WIN", "de__POSIX", "fr__MAC", "__MAC", "_MT", "_FR_EURO"

Returns:
A pointer to "name".

Referenced by RuleBasedCollator::setUCollator().

const char * Locale::getVariant ( ) const
 

Returns the locale's variant code.

Returns:
An alias to the code
Draft:

int32_t Locale::hashCode ( void ) const
 

Generates a hash code for the locale.

Stable:

Locale & Locale::init ( const char * cLocaleID ) [private]
 

Initialize the locale object with a new name.

Was deprecated - used in implementation - moved internal

Parameters:
cLocaleID   The new locale name.

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

Definition at line 681 of file locid.h.

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:

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

Referenced by operator!=().

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:

void Locale::setFromPOSIXID ( const char * posixID ) [protected]
 


Friends And Related Function Documentation

void locale_set_default_internal ( const char * ) [friend]
 


Member Data Documentation

const Locale Locale::CANADA [static]
 

Definition at line 206 of file locid.h.

const Locale Locale::CANADA_FRENCH [static]
 

Definition at line 207 of file locid.h.

const Locale Locale::CHINA [static]
 

Definition at line 201 of file locid.h.

const Locale Locale::CHINESE [static]
 

Definition at line 189 of file locid.h.

const Locale Locale::ENGLISH [static]
 

Useful constants for language.

Definition at line 183 of file locid.h.

const Locale Locale::FRANCE [static]
 

Useful constants for country.

Definition at line 196 of file locid.h.

const Locale Locale::FRENCH [static]
 

Definition at line 184 of file locid.h.

const Locale Locale::GERMAN [static]
 

Definition at line 185 of file locid.h.

const Locale Locale::GERMANY [static]
 

Definition at line 197 of file locid.h.

const Locale Locale::ITALIAN [static]
 

Definition at line 186 of file locid.h.

const Locale Locale::ITALY [static]
 

Definition at line 198 of file locid.h.

const Locale Locale::JAPAN [static]
 

Definition at line 199 of file locid.h.

const Locale Locale::JAPANESE [static]
 

Definition at line 187 of file locid.h.

const Locale Locale::KOREA [static]
 

Definition at line 200 of file locid.h.

const Locale Locale::KOREAN [static]
 

Definition at line 188 of file locid.h.

const Locale Locale::PRC [static]
 

Definition at line 202 of file locid.h.

const Locale Locale::SIMPLIFIED_CHINESE [static]
 

Definition at line 190 of file locid.h.

const Locale Locale::TAIWAN [static]
 

Definition at line 203 of file locid.h.

const Locale Locale::TRADITIONAL_CHINESE [static]
 

Definition at line 191 of file locid.h.

const Locale Locale::UK [static]
 

Definition at line 204 of file locid.h.

const Locale Locale::US [static]
 

Definition at line 205 of file locid.h.

const UnicodeString Locale::compressedCtry2LangMapping [static, private]
 

Definition at line 672 of file locid.h.

char Locale::country[ULOC_COUNTRY_CAPACITY] [private]
 

Definition at line 656 of file locid.h.

UHashtable * Locale::ctry2LangMapping [static, private]
 

Definition at line 671 of file locid.h.

Locale Locale::fgDefaultLocale [static, private]
 

Definition at line 674 of file locid.h.

char * Locale::fullName [private]
 

Definition at line 658 of file locid.h.

char Locale::fullNameBuffer[ULOC_FULLNAME_CAPACITY] [private]
 

Definition at line 659 of file locid.h.

UnicodeString * Locale::isoCountries [static, private]
 

Definition at line 667 of file locid.h.

int32_t Locale::isoCountriesCount [static, private]
 

Definition at line 668 of file locid.h.

UnicodeString * Locale::isoLanguages [static, private]
 

Definition at line 665 of file locid.h.

int32_t Locale::isoLanguagesCount [static, private]
 

Definition at line 666 of file locid.h.

char Locale::language[ULOC_LANG_CAPACITY] [private]
 

Definition at line 655 of file locid.h.

Locale * Locale::localeList [static, private]
 

Definition at line 661 of file locid.h.

int32_t Locale::localeListCount [static, private]
 

Definition at line 662 of file locid.h.

char * Locale::variant [private]
 

Definition at line 657 of file locid.h.


The documentation for this class was generated from the following file:
Generated at Thu Mar 22 16:13:14 2001 for ICU 1.8 by doxygen1.2.3 written by Dimitri van Heesch, © 1997-2000