Logo Search packages:      
Sourcecode: icu version File versions  Download package

Locale Class Reference

#include <locid.h>

Inheritance diagram for Locale:

UObject UMemory

List of all members.


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.

The Locale class is not suitable for subclassing.

You can create a Locale object using the constructor in this class:

       Locale( const   char*  language,
               const   char*  country,
               const   char*  variant);
 
The first argument to the constructors is a valid ISO Language Code. These codes are the lower-case two-letter codes as defined by ISO-639. You can find a full list of these codes at:
http://www.loc.gov/standards/iso639-2/

The second argument to the constructors is a valid ISO Country Code. These codes are the upper-case two-letter codes as defined by ISO-3166. You can find a full list of these codes at a number of sites, such as:
http://www.iso.org/iso/en/prods-services/iso3166ma/index.html

The third constructor requires a third argument--the Variant. The Variant codes are vendor and browser-specific. For example, use REVISED for a langauge's revised script orthography, and POSIX for POSIX. Where there are two variants, separate them with an underscore, and put the most important one first. For example, a Traditional Spanish collation might be referenced, with "ES", "ES", "Traditional_POSIX".

Because a Locale object is just an identifier for a region, no validity check is performed when you construct a Locale. If you want to see whether particular resources are available for the Locale you construct, you must query those resources. For example, ask the NumberFormat for the locales it supports using its getAvailableLocales method.
Note: When you ask for a resource for a particular locale, you get back the best available match, not necessarily precisely what you asked for. For more information, look at ResourceBundle.

The Locale class provides a number of convenient constants that you can use to create Locale objects for commonly used locales. For example, the following refers to a Locale object for the United States:

       Locale::getUS()
 

Once you've created a Locale you can query it for information about itself. Use getCountry to get the ISO Country Code and getLanguage to get the ISO Language Code. You can use getDisplayCountry to get the name of the country suitable for displaying to the user. Similarly, you can use getDisplayLanguage to get the name of the language suitable for displaying to the user. Interestingly, the getDisplayXXX methods are themselves locale-sensitive and have two versions: one that uses the default locale and one that takes a locale as an argument and displays the name or country in a language appropriate to that locale.

ICU provides a number of classes that perform locale-sensitive operations. For example, the NumberFormat class formats numbers, currency, or percentages in a locale-sensitive manner. Classes such as NumberFormat have a number of convenience methods for creating a default object of that type. For example, the NumberFormat class provides these three convenience methods for creating a default NumberFormat object:

     UErrorCode success = U_ZERO_ERROR;
     Locale myLocale;
     NumberFormat *nf;

     nf = NumberFormat::createInstance( success );          delete nf;
     nf = NumberFormat::createCurrencyInstance( success );  delete nf;
     nf = NumberFormat::createPercentInstance( success );   delete nf;
 
Each of these methods has two variants; one with an explicit locale and one without; the latter using the default locale.
     nf = NumberFormat::createInstance( myLocale, success );          delete nf;
     nf = NumberFormat::createCurrencyInstance( myLocale, success );  delete nf;
     nf = NumberFormat::createPercentInstance( myLocale, success );   delete nf;
 
A Locale is the mechanism for identifying the kind of object (NumberFormat) that you would like to get. The locale is 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)
 

ICU 2.0

See also:
ResourceBundle

Definition at line 181 of file locid.h.


Public Member Functions

Localeclone () const
StringEnumerationcreateKeywords (UErrorCode &status) const
const char * getBaseName () const
const char * getCountry () const
UnicodeStringgetDisplayCountry (const Locale &displayLocale, UnicodeString &dispCountry) const
UnicodeStringgetDisplayCountry (UnicodeString &dispCountry) const
UnicodeStringgetDisplayLanguage (const Locale &displayLocale, UnicodeString &dispLang) const
UnicodeStringgetDisplayLanguage (UnicodeString &dispLang) const
UnicodeStringgetDisplayName (const Locale &displayLocale, UnicodeString &name) const
UnicodeStringgetDisplayName (UnicodeString &name) const
UnicodeStringgetDisplayScript (const Locale &displayLocale, UnicodeString &dispScript) const
UnicodeStringgetDisplayScript (UnicodeString &dispScript) const
UnicodeStringgetDisplayVariant (const Locale &displayLocale, UnicodeString &dispVar) const
UnicodeStringgetDisplayVariant (UnicodeString &dispVar) const
virtual UClassID getDynamicClassID () const
const char * getISO3Country () const
const char * getISO3Language () const
int32_t getKeywordValue (const char *keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const
const char * getLanguage () const
uint32_t getLCID (void) const
const char * getName () const
const char * getScript () const
const char * getVariant () const
int32_t hashCode (void) const
UBool isBogus (void) const
 Locale (const Locale &other)
 Locale (const char *language, const char *country=0, const char *variant=0, const char *keywordsAndValues=0)
 Locale ()
UBool operator!= (const Locale &other) const
Localeoperator= (const Locale &other)
UBool operator== (const Locale &other) const
void setToBogus ()
virtual ~Locale ()

Static Public Member Functions

static Locale U_EXPORT2 createCanonical (const char *name)
static Locale U_EXPORT2 createFromName (const char *name)
static const Locale *U_EXPORT2 getAvailableLocales (int32_t &count)
static const Locale &U_EXPORT2 getCanada (void)
static const Locale &U_EXPORT2 getCanadaFrench (void)
static const Locale &U_EXPORT2 getChina (void)
static const Locale &U_EXPORT2 getChinese (void)
static const Locale &U_EXPORT2 getDefault (void)
static const Locale &U_EXPORT2 getEnglish (void)
static const Locale &U_EXPORT2 getFrance (void)
static const Locale &U_EXPORT2 getFrench (void)
static const Locale &U_EXPORT2 getGerman (void)
static const Locale &U_EXPORT2 getGermany (void)
static const char *const *U_EXPORT2 getISOCountries ()
static const char *const *U_EXPORT2 getISOLanguages ()
static const Locale &U_EXPORT2 getItalian (void)
static const Locale &U_EXPORT2 getItaly (void)
static const Locale &U_EXPORT2 getJapan (void)
static const Locale &U_EXPORT2 getJapanese (void)
static const Locale &U_EXPORT2 getKorea (void)
static const Locale &U_EXPORT2 getKorean (void)
static const Locale &U_EXPORT2 getPRC (void)
static const Locale &U_EXPORT2 getSimplifiedChinese (void)
static UClassID U_EXPORT2 getStaticClassID ()
static const Locale &U_EXPORT2 getTaiwan (void)
static const Locale &U_EXPORT2 getTraditionalChinese (void)
static const Locale &U_EXPORT2 getUK (void)
static const Locale &U_EXPORT2 getUS (void)
static void U_EXPORT2 operator delete (void *, void *) U_NO_THROW
static void U_EXPORT2 operator delete (void *p) U_NO_THROW
static void U_EXPORT2 operator delete[] (void *p) U_NO_THROW
static void *U_EXPORT2 operator new (size_t, void *ptr) U_NO_THROW
static void *U_EXPORT2 operator new (size_t size) U_NO_THROW
static void *U_EXPORT2 operator new[] (size_t size) U_NO_THROW
static void U_EXPORT2 setDefault (const Locale &newLocale, UErrorCode &success)

Protected Member Functions

void setFromPOSIXID (const char *posixID)

Private Types

enum  ELocaleType { eBOGUS }

Private Member Functions

Localeinit (const char *cLocaleID, UBool canonicalize)
 Locale (ELocaleType)

Static Private Member Functions

static const LocalegetLocale (int locid)
static LocalegetLocaleCache (void)

Private Attributes

char * baseName
char baseNameBuffer [ULOC_FULLNAME_CAPACITY]
char country [ULOC_COUNTRY_CAPACITY]
UBool fIsBogus
char * fullName
char fullNameBuffer [ULOC_FULLNAME_CAPACITY]
char language [ULOC_LANG_CAPACITY]
char script [ULOC_SCRIPT_CAPACITY]
int32_t variantBegin

Friends

void locale_set_default_internal (const char *)

The documentation for this class was generated from the following files:

Generated by  Doxygen 1.6.0   Back to index