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...
|
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...
|
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) |
| set it from a single string.
|
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 |
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
|
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:
-
|
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:
-
|
|
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:
-
|
|
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:
-
|
|
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:
-
|
|
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:
-
|
|
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:
-
|
|
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:
-
|
|
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:
-
|
|
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:
-
|
|
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 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 686 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]
|
|
|
set it from a single string.
|
Friends And Related Function Documentation
void locale_set_default_internal (
|
const char * ) [friend]
|
|
Member Data Documentation
const Locale Locale::CANADA [static]
|
|
const Locale Locale::CANADA_FRENCH [static]
|
|
const Locale Locale::CHINA [static]
|
|
const Locale Locale::CHINESE [static]
|
|
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]
|
|
const Locale Locale::GERMAN [static]
|
|
const Locale Locale::GERMANY [static]
|
|
const Locale Locale::ITALIAN [static]
|
|
const Locale Locale::ITALY [static]
|
|
const Locale Locale::JAPAN [static]
|
|
const Locale Locale::JAPANESE [static]
|
|
const Locale Locale::KOREA [static]
|
|
const Locale Locale::KOREAN [static]
|
|
const Locale Locale::PRC [static]
|
|
const Locale Locale::SIMPLIFIED_CHINESE [static]
|
|
const Locale Locale::TAIWAN [static]
|
|
const Locale Locale::TRADITIONAL_CHINESE [static]
|
|
const Locale Locale::UK [static]
|
|
const Locale Locale::US [static]
|
|
char Locale::country[ULOC_COUNTRY_CAPACITY] [private]
|
|
Locale Locale::fgDefaultLocale [static, private]
|
|
char * Locale::fullName [private]
|
|
char Locale::fullNameBuffer[ULOC_FULLNAME_CAPACITY] [private]
|
|
char Locale::language[ULOC_LANG_CAPACITY] [private]
|
|
Locale * Locale::localeList [static, private]
|
|
int32_t Locale::localeListCount [static, private]
|
|
char * Locale::variant [private]
|
|
The documentation for this class was generated from the following file:
Generated at Tue Jun 12 14:04:35 2001 for ICU 1.8.1 by
1.2.3 written by Dimitri van Heesch,
© 1997-2000