Locale object represents a specific geographical, political,
michael@0: * or cultural region. An operation that requires a Locale to perform
michael@0: * its task is called locale-sensitive and uses the Locale
michael@0: * to tailor information for the user. For example, displaying a number
michael@0: * is a locale-sensitive operation--the number should be formatted
michael@0: * according to the customs/conventions of the user's native country,
michael@0: * region, or culture.
michael@0: *
michael@0: * The Locale class is not suitable for subclassing.
michael@0: *
michael@0: *
michael@0: * You can create a Locale object using the constructor in
michael@0: * this class:
michael@0: * \htmlonly
\endhtmlonly michael@0: *\endhtmlonly michael@0: * The first argument to the constructors is a valid ISO michael@0: * Language Code. These codes are the lower-case two-letter michael@0: * codes as defined by ISO-639. michael@0: * You can find a full list of these codes at: michael@0: *michael@0: * Locale( const char* language, michael@0: * const char* country, michael@0: * const char* variant); michael@0: *michael@0: * \htmlonly
michael@0: * The second argument to the constructors is a valid ISO Country
michael@0: * Code. These codes are the upper-case two-letter codes
michael@0: * as defined by ISO-3166.
michael@0: * You can find a full list of these codes at a number of sites, such as:
michael@0: *
michael@0: * http://www.iso.org/iso/en/prods-services/iso3166ma/index.html
michael@0: *
michael@0: *
michael@0: * The third constructor requires a third argument--the Variant. michael@0: * The Variant codes are vendor and browser-specific. michael@0: * For example, use REVISED for a langauge's revised script orthography, and POSIX for POSIX. michael@0: * Where there are two variants, separate them with an underscore, and michael@0: * put the most important one first. For michael@0: * example, a Traditional Spanish collation might be referenced, with michael@0: * "ES", "ES", "Traditional_POSIX". michael@0: * michael@0: *
michael@0: * Because a Locale object is just an identifier for a region,
michael@0: * no validity check is performed when you construct a Locale.
michael@0: * If you want to see whether particular resources are available for the
michael@0: * Locale you construct, you must query those resources. For
michael@0: * example, ask the NumberFormat for the locales it supports
michael@0: * using its getAvailableLocales method.
michael@0: *
Note: When you ask for a resource for a particular
michael@0: * locale, you get back the best available match, not necessarily
michael@0: * precisely what you asked for. For more information, look at
michael@0: * ResourceBundle.
michael@0: *
michael@0: *
michael@0: * The Locale class provides a number of convenient constants
michael@0: * that you can use to create Locale objects for commonly used
michael@0: * locales. For example, the following refers to a Locale object
michael@0: * for the United States:
michael@0: * \htmlonly
\endhtmlonly michael@0: *\endhtmlonly michael@0: * michael@0: *michael@0: * Locale::getUS() michael@0: *michael@0: * \htmlonly
michael@0: * Once you've created a Locale you can query it for information about
michael@0: * itself. Use getCountry to get the ISO Country Code and
michael@0: * getLanguage to get the ISO Language Code. You can
michael@0: * use getDisplayCountry to get the
michael@0: * name of the country suitable for displaying to the user. Similarly,
michael@0: * you can use getDisplayLanguage to get the name of
michael@0: * the language suitable for displaying to the user. Interestingly,
michael@0: * the getDisplayXXX methods are themselves locale-sensitive
michael@0: * and have two versions: one that uses the default locale and one
michael@0: * that takes a locale as an argument and displays the name or country in
michael@0: * a language appropriate to that locale.
michael@0: *
michael@0: *
michael@0: * ICU provides a number of classes that perform locale-sensitive
michael@0: * operations. For example, the NumberFormat class formats
michael@0: * numbers, currency, or percentages in a locale-sensitive manner. Classes
michael@0: * such as NumberFormat have a number of convenience methods
michael@0: * for creating a default object of that type. For example, the
michael@0: * NumberFormat class provides these three convenience methods
michael@0: * for creating a default NumberFormat object:
michael@0: * \htmlonly
\endhtmlonly michael@0: *\endhtmlonly michael@0: * Each of these methods has two variants; one with an explicit locale michael@0: * and one without; the latter using the default locale. michael@0: * \htmlonlymichael@0: * UErrorCode success = U_ZERO_ERROR; michael@0: * Locale myLocale; michael@0: * NumberFormat *nf; michael@0: * michael@0: * nf = NumberFormat::createInstance( success ); delete nf; michael@0: * nf = NumberFormat::createCurrencyInstance( success ); delete nf; michael@0: * nf = NumberFormat::createPercentInstance( success ); delete nf; michael@0: *michael@0: * \htmlonly
\endhtmlonly michael@0: *\endhtmlonly michael@0: * Amichael@0: * nf = NumberFormat::createInstance( myLocale, success ); delete nf; michael@0: * nf = NumberFormat::createCurrencyInstance( myLocale, success ); delete nf; michael@0: * nf = NumberFormat::createPercentInstance( myLocale, success ); delete nf; michael@0: *michael@0: * \htmlonly
Locale is the mechanism for identifying the kind of object
michael@0: * (NumberFormat) that you would like to get. The locale is
michael@0: * just a mechanism for identifying objects,
michael@0: * not a container for the objects themselves.
michael@0: *
michael@0: * michael@0: * Each class that performs locale-sensitive operations allows you michael@0: * to get all the available objects of that type. You can sift michael@0: * through these objects by language, country, or variant, michael@0: * and use the display names to present a menu to the user. michael@0: * For example, you can create a menu of all the collation objects michael@0: * suitable for a given language. Such classes implement these michael@0: * three class methods: michael@0: * \htmlonly
\endhtmlonly michael@0: *\endhtmlonly michael@0: * michael@0: * @stable ICU 2.0 michael@0: * @see ResourceBundle michael@0: */ michael@0: class U_COMMON_API Locale : public UObject { michael@0: public: michael@0: /** Useful constant for the Root locale. @stable ICU 4.4 */ michael@0: static const Locale &U_EXPORT2 getRoot(void); michael@0: /** Useful constant for this language. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getEnglish(void); michael@0: /** Useful constant for this language. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getFrench(void); michael@0: /** Useful constant for this language. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getGerman(void); michael@0: /** Useful constant for this language. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getItalian(void); michael@0: /** Useful constant for this language. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getJapanese(void); michael@0: /** Useful constant for this language. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getKorean(void); michael@0: /** Useful constant for this language. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getChinese(void); michael@0: /** Useful constant for this language. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getSimplifiedChinese(void); michael@0: /** Useful constant for this language. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getTraditionalChinese(void); michael@0: michael@0: /** Useful constant for this country/region. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getFrance(void); michael@0: /** Useful constant for this country/region. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getGermany(void); michael@0: /** Useful constant for this country/region. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getItaly(void); michael@0: /** Useful constant for this country/region. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getJapan(void); michael@0: /** Useful constant for this country/region. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getKorea(void); michael@0: /** Useful constant for this country/region. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getChina(void); michael@0: /** Useful constant for this country/region. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getPRC(void); michael@0: /** Useful constant for this country/region. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getTaiwan(void); michael@0: /** Useful constant for this country/region. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getUK(void); michael@0: /** Useful constant for this country/region. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getUS(void); michael@0: /** Useful constant for this country/region. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getCanada(void); michael@0: /** Useful constant for this country/region. @stable ICU 2.0 */ michael@0: static const Locale &U_EXPORT2 getCanadaFrench(void); michael@0: michael@0: michael@0: /** michael@0: * Construct a default locale object, a Locale for the default locale ID. michael@0: * michael@0: * @see getDefault michael@0: * @see uloc_getDefault michael@0: * @stable ICU 2.0 michael@0: */ michael@0: Locale(); michael@0: michael@0: /** michael@0: * Construct a locale from language, country, variant. michael@0: * If an error occurs, then the constructed object will be "bogus" michael@0: * (isBogus() will return TRUE). michael@0: * michael@0: * @param language Lowercase two-letter or three-letter ISO-639 code. michael@0: * This parameter can instead be an ICU style C locale (e.g. "en_US"), michael@0: * but the other parameters must not be used. michael@0: * This parameter can be NULL; if so, michael@0: * the locale is initialized to match the current default locale. michael@0: * (This is the same as using the default constructor.) michael@0: * Please note: The Java Locale class does NOT accept the form michael@0: * 'new Locale("en_US")' but only 'new Locale("en","US")' michael@0: * michael@0: * @param country Uppercase two-letter ISO-3166 code. (optional) michael@0: * @param variant Uppercase vendor and browser specific code. See class michael@0: * description. (optional) michael@0: * @param keywordsAndValues A string consisting of keyword/values pairs, such as michael@0: * "collation=phonebook;currency=euro" michael@0: * michael@0: * @see getDefault michael@0: * @see uloc_getDefault michael@0: * @stable ICU 2.0 michael@0: */ michael@0: Locale( const char * language, michael@0: const char * country = 0, michael@0: const char * variant = 0, michael@0: const char * keywordsAndValues = 0); michael@0: michael@0: /** michael@0: * Initializes a Locale object from another Locale object. michael@0: * michael@0: * @param other The Locale object being copied in. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: Locale(const Locale& other); michael@0: michael@0: michael@0: /** michael@0: * Destructor michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual ~Locale() ; michael@0: michael@0: /** michael@0: * Replaces the entire contents of *this with the specified value. michael@0: * michael@0: * @param other The Locale object being copied in. michael@0: * @return *this michael@0: * @stable ICU 2.0 michael@0: */ michael@0: Locale& operator=(const Locale& other); michael@0: michael@0: /** michael@0: * Checks if two locale keys are the same. michael@0: * michael@0: * @param other The locale key object to be compared with this. michael@0: * @return True if the two locale keys are the same, false otherwise. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UBool operator==(const Locale& other) const; michael@0: michael@0: /** michael@0: * Checks if two locale keys are not the same. michael@0: * michael@0: * @param other The locale key object to be compared with this. michael@0: * @return True if the two locale keys are not the same, false michael@0: * otherwise. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UBool operator!=(const Locale& other) const; michael@0: michael@0: /** michael@0: * Clone this object. michael@0: * Clones can be used concurrently in multiple threads. michael@0: * If an error occurs, then NULL is returned. michael@0: * The caller must delete the clone. michael@0: * michael@0: * @return a clone of this object michael@0: * michael@0: * @see getDynamicClassID michael@0: * @stable ICU 2.8 michael@0: */ michael@0: Locale *clone() const; michael@0: michael@0: #ifndef U_HIDE_SYSTEM_API michael@0: /** michael@0: * Common methods of getting the current default Locale. Used for the michael@0: * presentation: menus, dialogs, etc. Generally set once when your applet or michael@0: * application is initialized, then never reset. (If you do reset the michael@0: * default locale, you probably want to reload your GUI, so that the change michael@0: * is reflected in your interface.) michael@0: * michael@0: * More advanced programs will allow users to use different locales for michael@0: * different fields, e.g. in a spreadsheet. michael@0: * michael@0: * Note that the initial setting will match the host system. michael@0: * @return a reference to the Locale object for the default locale ID michael@0: * @system michael@0: * @stable ICU 2.0 michael@0: */ michael@0: static const Locale& U_EXPORT2 getDefault(void); michael@0: michael@0: /** michael@0: * Sets the default. Normally set once at the beginning of a process, michael@0: * then never reset. michael@0: * setDefault() only changes ICU's default locale ID, not michael@0: * the default locale ID of the runtime environment. michael@0: * michael@0: * @param newLocale Locale to set to. If NULL, set to the value obtained michael@0: * from the runtime environement. michael@0: * @param success The error code. michael@0: * @system michael@0: * @stable ICU 2.0 michael@0: */ michael@0: static void U_EXPORT2 setDefault(const Locale& newLocale, michael@0: UErrorCode& success); michael@0: #endif /* U_HIDE_SYSTEM_API */ michael@0: michael@0: /** michael@0: * Creates a locale which has had minimal canonicalization michael@0: * as per uloc_getName(). michael@0: * @param name The name to create from. If name is null, michael@0: * the default Locale is used. michael@0: * @return new locale object michael@0: * @stable ICU 2.0 michael@0: * @see uloc_getName michael@0: */ michael@0: static Locale U_EXPORT2 createFromName(const char *name); michael@0: michael@0: /** michael@0: * Creates a locale from the given string after canonicalizing michael@0: * the string by calling uloc_canonicalize(). michael@0: * @param name the locale ID to create from. Must not be NULL. michael@0: * @return a new locale object corresponding to the given name michael@0: * @stable ICU 3.0 michael@0: * @see uloc_canonicalize michael@0: */ michael@0: static Locale U_EXPORT2 createCanonical(const char* name); michael@0: michael@0: /** michael@0: * Returns the locale's ISO-639 language code. michael@0: * @return An alias to the code michael@0: * @stable ICU 2.0 michael@0: */ michael@0: inline const char * getLanguage( ) const; michael@0: michael@0: /** michael@0: * Returns the locale's ISO-15924 abbreviation script code. michael@0: * @return An alias to the code michael@0: * @see uscript_getShortName michael@0: * @see uscript_getCode michael@0: * @stable ICU 2.8 michael@0: */ michael@0: inline const char * getScript( ) const; michael@0: michael@0: /** michael@0: * Returns the locale's ISO-3166 country code. michael@0: * @return An alias to the code michael@0: * @stable ICU 2.0 michael@0: */ michael@0: inline const char * getCountry( ) const; michael@0: michael@0: /** michael@0: * Returns the locale's variant code. michael@0: * @return An alias to the code michael@0: * @stable ICU 2.0 michael@0: */ michael@0: inline const char * getVariant( ) const; michael@0: michael@0: /** michael@0: * Returns the programmatic name of the entire locale, with the language, michael@0: * country and variant separated by underbars. If a field is missing, up michael@0: * to two leading underbars will occur. Example: "en", "de_DE", "en_US_WIN", michael@0: * "de__POSIX", "fr__MAC", "__MAC", "_MT", "_FR_EURO" michael@0: * @return A pointer to "name". michael@0: * @stable ICU 2.0 michael@0: */ michael@0: inline const char * getName() const; michael@0: michael@0: /** michael@0: * Returns the programmatic name of the entire locale as getName() would return, michael@0: * but without keywords. michael@0: * @return A pointer to "name". michael@0: * @see getName michael@0: * @stable ICU 2.8 michael@0: */ michael@0: const char * getBaseName() const; michael@0: michael@0: michael@0: /** michael@0: * Gets the list of keywords for the specified locale. michael@0: * michael@0: * @param status the status code michael@0: * @return pointer to StringEnumeration class, or NULL if there are no keywords. michael@0: * Client must dispose of it by calling delete. michael@0: * @stable ICU 2.8 michael@0: */ michael@0: StringEnumeration * createKeywords(UErrorCode &status) const; michael@0: michael@0: /** michael@0: * Gets the value for a keyword. michael@0: * michael@0: * @param keywordName name of the keyword for which we want the value. Case insensitive. michael@0: * @param buffer The buffer to receive the keyword value. michael@0: * @param bufferCapacity The capacity of receiving buffer michael@0: * @param status Returns any error information while performing this operation. michael@0: * @return the length of the keyword value michael@0: * michael@0: * @stable ICU 2.8 michael@0: */ michael@0: int32_t getKeywordValue(const char* keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const; michael@0: michael@0: /** michael@0: * Sets or removes the value for a keyword. michael@0: * michael@0: * For removing all keywords, use getBaseName(), michael@0: * and construct a new Locale if it differs from getName(). michael@0: * michael@0: * @param keywordName name of the keyword to be set. Case insensitive. michael@0: * @param keywordValue value of the keyword to be set. If 0-length or michael@0: * NULL, will result in the keyword being removed. No error is given if michael@0: * that keyword does not exist. michael@0: * @param status Returns any error information while performing this operation. michael@0: * michael@0: * @stable ICU 49 michael@0: */ michael@0: void setKeywordValue(const char* keywordName, const char* keywordValue, UErrorCode &status); michael@0: michael@0: /** michael@0: * returns the locale's three-letter language code, as specified michael@0: * in ISO draft standard ISO-639-2. michael@0: * @return An alias to the code, or an empty string michael@0: * @stable ICU 2.0 michael@0: */ michael@0: const char * getISO3Language() const; michael@0: michael@0: /** michael@0: * Fills in "name" with the locale's three-letter ISO-3166 country code. michael@0: * @return An alias to the code, or an empty string michael@0: * @stable ICU 2.0 michael@0: */ michael@0: const char * getISO3Country() const; michael@0: michael@0: /** michael@0: * Returns the Windows LCID value corresponding to this locale. michael@0: * This value is stored in the resource data for the locale as a one-to-four-digit michael@0: * hexadecimal number. If the resource is missing, in the wrong format, or michael@0: * there is no Windows LCID value that corresponds to this locale, returns 0. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: uint32_t getLCID(void) const; michael@0: michael@0: /** michael@0: * Fills in "dispLang" with the name of this locale's language in a format suitable for michael@0: * user display in the default locale. For example, if the locale's language code is michael@0: * "fr" and the default locale's language code is "en", this function would set michael@0: * dispLang to "French". michael@0: * @param dispLang Receives the language's display name. michael@0: * @return A reference to "dispLang". michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& getDisplayLanguage(UnicodeString& dispLang) const; michael@0: michael@0: /** michael@0: * Fills in "dispLang" with the name of this locale's language in a format suitable for michael@0: * user display in the locale specified by "displayLocale". For example, if the locale's michael@0: * language code is "en" and displayLocale's language code is "fr", this function would set michael@0: * dispLang to "Anglais". michael@0: * @param displayLocale Specifies the locale to be used to display the name. In other words, michael@0: * if the locale's language code is "en", passing Locale::getFrench() for michael@0: * displayLocale would result in "Anglais", while passing Locale::getGerman() michael@0: * for displayLocale would result in "Englisch". michael@0: * @param dispLang Receives the language's display name. michael@0: * @return A reference to "dispLang". michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& getDisplayLanguage( const Locale& displayLocale, michael@0: UnicodeString& dispLang) const; michael@0: michael@0: /** michael@0: * Fills in "dispScript" with the name of this locale's script in a format suitable michael@0: * for user display in the default locale. For example, if the locale's script code michael@0: * is "LATN" and the default locale's language code is "en", this function would set michael@0: * dispScript to "Latin". michael@0: * @param dispScript Receives the scripts's display name. michael@0: * @return A reference to "dispScript". michael@0: * @stable ICU 2.8 michael@0: */ michael@0: UnicodeString& getDisplayScript( UnicodeString& dispScript) const; michael@0: michael@0: /** michael@0: * Fills in "dispScript" with the name of this locale's country in a format suitable michael@0: * for user display in the locale specified by "displayLocale". For example, if the locale's michael@0: * script code is "LATN" and displayLocale's language code is "en", this function would set michael@0: * dispScript to "Latin". michael@0: * @param displayLocale Specifies the locale to be used to display the name. In other michael@0: * words, if the locale's script code is "LATN", passing michael@0: * Locale::getFrench() for displayLocale would result in "", while michael@0: * passing Locale::getGerman() for displayLocale would result in michael@0: * "". michael@0: * @param dispScript Receives the scripts's display name. michael@0: * @return A reference to "dispScript". michael@0: * @stable ICU 2.8 michael@0: */ michael@0: UnicodeString& getDisplayScript( const Locale& displayLocale, michael@0: UnicodeString& dispScript) const; michael@0: michael@0: /** michael@0: * Fills in "dispCountry" with the name of this locale's country in a format suitable michael@0: * for user display in the default locale. For example, if the locale's country code michael@0: * is "FR" and the default locale's language code is "en", this function would set michael@0: * dispCountry to "France". michael@0: * @param dispCountry Receives the country's display name. michael@0: * @return A reference to "dispCountry". michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& getDisplayCountry( UnicodeString& dispCountry) const; michael@0: michael@0: /** michael@0: * Fills in "dispCountry" with the name of this locale's country in a format suitable michael@0: * for user display in the locale specified by "displayLocale". For example, if the locale's michael@0: * country code is "US" and displayLocale's language code is "fr", this function would set michael@0: * dispCountry to "États-Unis". michael@0: * @param displayLocale Specifies the locale to be used to display the name. In other michael@0: * words, if the locale's country code is "US", passing michael@0: * Locale::getFrench() for displayLocale would result in "États-Unis", while michael@0: * passing Locale::getGerman() for displayLocale would result in michael@0: * "Vereinigte Staaten". michael@0: * @param dispCountry Receives the country's display name. michael@0: * @return A reference to "dispCountry". michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& getDisplayCountry( const Locale& displayLocale, michael@0: UnicodeString& dispCountry) const; michael@0: michael@0: /** michael@0: * Fills in "dispVar" with the name of this locale's variant code in a format suitable michael@0: * for user display in the default locale. michael@0: * @param dispVar Receives the variant's name. michael@0: * @return A reference to "dispVar". michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& getDisplayVariant( UnicodeString& dispVar) const; michael@0: michael@0: /** michael@0: * Fills in "dispVar" with the name of this locale's variant code in a format michael@0: * suitable for user display in the locale specified by "displayLocale". michael@0: * @param displayLocale Specifies the locale to be used to display the name. michael@0: * @param dispVar Receives the variant's display name. michael@0: * @return A reference to "dispVar". michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& getDisplayVariant( const Locale& displayLocale, michael@0: UnicodeString& dispVar) const; michael@0: michael@0: /** michael@0: * Fills in "name" with the name of this locale in a format suitable for user display michael@0: * in the default locale. This function uses getDisplayLanguage(), getDisplayCountry(), michael@0: * and getDisplayVariant() to do its work, and outputs the display name in the format michael@0: * "language (country[,variant])". For example, if the default locale is en_US, then michael@0: * fr_FR's display name would be "French (France)", and es_MX_Traditional's display name michael@0: * would be "Spanish (Mexico,Traditional)". michael@0: * @param name Receives the locale's display name. michael@0: * @return A reference to "name". michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& getDisplayName( UnicodeString& name) const; michael@0: michael@0: /** michael@0: * Fills in "name" with the name of this locale in a format suitable for user display michael@0: * in the locale specfied by "displayLocale". This function uses getDisplayLanguage(), michael@0: * getDisplayCountry(), and getDisplayVariant() to do its work, and outputs the display michael@0: * name in the format "language (country[,variant])". For example, if displayLocale is michael@0: * fr_FR, then en_US's display name would be "Anglais (États-Unis)", and no_NO_NY's michael@0: * display name would be "norvégien (Norvège,NY)". michael@0: * @param displayLocale Specifies the locale to be used to display the name. michael@0: * @param name Receives the locale's display name. michael@0: * @return A reference to "name". michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& getDisplayName( const Locale& displayLocale, michael@0: UnicodeString& name) const; michael@0: michael@0: /** michael@0: * Generates a hash code for the locale. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: int32_t hashCode(void) const; michael@0: michael@0: /** michael@0: * Sets the locale to bogus michael@0: * A bogus locale represents a non-existing locale associated michael@0: * with services that can be instantiated from non-locale data michael@0: * in addition to locale (for example, collation can be michael@0: * instantiated from a locale and from a rule set). michael@0: * @stable ICU 2.1 michael@0: */ michael@0: void setToBogus(); michael@0: michael@0: /** michael@0: * Gets the bogus state. Locale object can be bogus if it doesn't exist michael@0: * @return FALSE if it is a real locale, TRUE if it is a bogus locale michael@0: * @stable ICU 2.1 michael@0: */ michael@0: UBool isBogus(void) const; michael@0: michael@0: /** michael@0: * Returns a list of all installed locales. michael@0: * @param count Receives the number of locales in the list. michael@0: * @return A pointer to an array of Locale objects. This array is the list michael@0: * of all locales with installed resource files. The called does NOT michael@0: * get ownership of this list, and must NOT delete it. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count); michael@0: michael@0: /** michael@0: * Gets a list of all available 2-letter country codes defined in ISO 3166. This is a michael@0: * pointer to an array of pointers to arrays of char. All of these pointers are michael@0: * owned by ICU-- do not delete them, and do not write through them. The array is michael@0: * terminated with a null pointer. michael@0: * @return a list of all available country codes michael@0: * @stable ICU 2.0 michael@0: */ michael@0: static const char* const* U_EXPORT2 getISOCountries(); michael@0: michael@0: /** michael@0: * Gets a list of all available language codes defined in ISO 639. This is a pointer michael@0: * to an array of pointers to arrays of char. All of these pointers are owned michael@0: * by ICU-- do not delete them, and do not write through them. The array is michael@0: * terminated with a null pointer. michael@0: * @return a list of all available language codes michael@0: * @stable ICU 2.0 michael@0: */ michael@0: static const char* const* U_EXPORT2 getISOLanguages(); michael@0: michael@0: /** michael@0: * ICU "poor man's RTTI", returns a UClassID for this class. michael@0: * michael@0: * @stable ICU 2.2 michael@0: */ michael@0: static UClassID U_EXPORT2 getStaticClassID(); michael@0: michael@0: /** michael@0: * ICU "poor man's RTTI", returns a UClassID for the actual class. michael@0: * michael@0: * @stable ICU 2.2 michael@0: */ michael@0: virtual UClassID getDynamicClassID() const; michael@0: michael@0: protected: /* only protected for testing purposes. DO NOT USE. */ michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * Set this from a single POSIX style locale string. michael@0: * @internal michael@0: */ michael@0: void setFromPOSIXID(const char *posixID); michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: private: michael@0: /** michael@0: * Initialize the locale object with a new name. michael@0: * Was deprecated - used in implementation - moved internal michael@0: * michael@0: * @param cLocaleID The new locale name. michael@0: * @param canonicalize whether to call uloc_canonicalize on cLocaleID michael@0: */ michael@0: Locale& init(const char* cLocaleID, UBool canonicalize); michael@0: michael@0: /* michael@0: * Internal constructor to allow construction of a locale object with michael@0: * NO side effects. (Default constructor tries to get michael@0: * the default locale.) michael@0: */ michael@0: enum ELocaleType { michael@0: eBOGUS michael@0: }; michael@0: Locale(ELocaleType); michael@0: michael@0: /** michael@0: * Initialize the locale cache for commonly used locales michael@0: */ michael@0: static Locale *getLocaleCache(void); michael@0: michael@0: char language[ULOC_LANG_CAPACITY]; michael@0: char script[ULOC_SCRIPT_CAPACITY]; michael@0: char country[ULOC_COUNTRY_CAPACITY]; michael@0: int32_t variantBegin; michael@0: char* fullName; michael@0: char fullNameBuffer[ULOC_FULLNAME_CAPACITY]; michael@0: // name without keywords michael@0: char* baseName; michael@0: char baseNameBuffer[ULOC_FULLNAME_CAPACITY]; michael@0: michael@0: UBool fIsBogus; michael@0: michael@0: static const Locale &getLocale(int locid); michael@0: michael@0: /** michael@0: * A friend to allow the default locale to be set by either the C or C++ API. michael@0: * @internal michael@0: */ michael@0: friend Locale *locale_set_default_internal(const char *, UErrorCode& status); michael@0: michael@0: /** michael@0: * @internal michael@0: */ michael@0: friend void locale_available_init(); michael@0: }; michael@0: michael@0: inline UBool michael@0: Locale::operator!=(const Locale& other) const michael@0: { michael@0: return !operator==(other); michael@0: } michael@0: michael@0: inline const char * michael@0: Locale::getCountry() const michael@0: { michael@0: return country; michael@0: } michael@0: michael@0: inline const char * michael@0: Locale::getLanguage() const michael@0: { michael@0: return language; michael@0: } michael@0: michael@0: inline const char * michael@0: Locale::getScript() const michael@0: { michael@0: return script; michael@0: } michael@0: michael@0: inline const char * michael@0: Locale::getVariant() const michael@0: { michael@0: getBaseName(); // lazy init michael@0: return &baseName[variantBegin]; michael@0: } michael@0: michael@0: inline const char * michael@0: Locale::getName() const michael@0: { michael@0: return fullName; michael@0: } michael@0: michael@0: inline UBool michael@0: Locale::isBogus(void) const { michael@0: return fIsBogus; michael@0: } michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endifmichael@0: * static Locale* getAvailableLocales(int32_t& numLocales) michael@0: * static UnicodeString& getDisplayName(const Locale& objectLocale, michael@0: * const Locale& displayLocale, michael@0: * UnicodeString& displayName) michael@0: * static UnicodeString& getDisplayName(const Locale& objectLocale, michael@0: * UnicodeString& displayName) michael@0: *michael@0: * \htmlonly