source/common/unicode/locid.h

   1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 ******************************************************************************
   5 *
   6 *   Copyright (C) 1996-2015, International Business Machines
   7 *   Corporation and others.  All Rights Reserved.
   8 *
   9 ******************************************************************************
  10 *
  11 * File locid.h
  12 *
  13 * Created by: Helena Shih
  14 *
  15 * Modification History:
  16 *
  17 *   Date        Name        Description
  18 *   02/11/97    aliu        Changed gLocPath to fgLocPath and added methods to
  19 *                           get and set it.
  20 *   04/02/97    aliu        Made operator!= inline; fixed return value of getName().
  21 *   04/15/97    aliu        Cleanup for AIX/Win32.
  22 *   04/24/97    aliu        Numerous changes per code review.
  23 *   08/18/98    stephen     Added tokenizeString(),changed getDisplayName()
  24 *   09/08/98    stephen     Moved definition of kEmptyString for Mac Port
  25 *   11/09/99    weiv        Added const char * getName() const;
  26 *   04/12/00    srl         removing unicodestring api's and cached hash code
  27 *   08/10/01    grhoten     Change the static Locales to accessor functions
  28 ******************************************************************************
  29 */
  30
  31 #ifndef LOCID_H
  32 #define LOCID_H
  33
  34 #include "unicode/utypes.h"
  35 #include "unicode/uobject.h"
  36 #include "unicode/unistr.h"
  37 #include "unicode/putil.h"
  38 #include "unicode/uloc.h"
  39 #include "unicode/strenum.h"
  40
  41 /**
  42  * \file
  43  * \brief C++ API: Locale ID object.
  44  */
  45
  46 U_NAMESPACE_BEGIN
  47
  48 // Forward Declarations
  49 void U_CALLCONV locale_available_init(); /**< @internal */
  50
  51 /**
  52  * A <code>Locale</code> object represents a specific geographical, political,
  53  * or cultural region. An operation that requires a <code>Locale</code> to perform
  54  * its task is called <em>locale-sensitive</em> and uses the <code>Locale</code>
  55  * to tailor information for the user. For example, displaying a number
  56  * is a locale-sensitive operation--the number should be formatted
  57  * according to the customs/conventions of the user's native country,
  58  * region, or culture.
  59  *
  60  * The Locale class is not suitable for subclassing.
  61  *
  62  * <P>
  63  * You can create a <code>Locale</code> object using the constructor in
  64  * this class:
  65  * \htmlonly<blockquote>\endhtmlonly
  66  * <pre>
  67  *       Locale( const   char*  language,
  68  *               const   char*  country,
  69  *               const   char*  variant);
  70  * </pre>
  71  * \htmlonly</blockquote>\endhtmlonly
  72  * The first argument to the constructors is a valid <STRONG>ISO
  73  * Language Code.</STRONG> These codes are the lower-case two-letter
  74  * codes as defined by ISO-639.
  75  * You can find a full list of these codes at:
  76  * <BR><a href ="http://www.loc.gov/standards/iso639-2/">
  77  * http://www.loc.gov/standards/iso639-2/</a>
  78  *
  79  * <P>
  80  * The second argument to the constructors is a valid <STRONG>ISO Country
  81  * Code.</STRONG> These codes are the upper-case two-letter codes
  82  * as defined by ISO-3166.
  83  * You can find a full list of these codes at a number of sites, such as:
  84  * <BR><a href="http://www.iso.org/iso/en/prods-services/iso3166ma/index.html">
  85  * http://www.iso.org/iso/en/prods-services/iso3166ma/index.html</a>
  86  *
  87  * <P>
  88  * The third constructor requires a third argument--the <STRONG>Variant.</STRONG>
  89  * The Variant codes are vendor and browser-specific.
  90  * For example, use REVISED for a langauge's revised script orthography, and POSIX for POSIX.
  91  * Where there are two variants, separate them with an underscore, and
  92  * put the most important one first. For
  93  * example, a Traditional Spanish collation might be referenced, with
  94  * "ES", "ES", "Traditional_POSIX".
  95  *
  96  * <P>
  97  * Because a <code>Locale</code> object is just an identifier for a region,
  98  * no validity check is performed when you construct a <code>Locale</code>.
  99  * If you want to see whether particular resources are available for the
 100  * <code>Locale</code> you construct, you must query those resources. For
 101  * example, ask the <code>NumberFormat</code> for the locales it supports
 102  * using its <code>getAvailableLocales</code> method.
 103  * <BR><STRONG>Note:</STRONG> When you ask for a resource for a particular
 104  * locale, you get back the best available match, not necessarily
 105  * precisely what you asked for. For more information, look at
 106  * <code>ResourceBundle</code>.
 107  *
 108  * <P>
 109  * The <code>Locale</code> class provides a number of convenient constants
 110  * that you can use to create <code>Locale</code> objects for commonly used
 111  * locales. For example, the following refers to a <code>Locale</code> object
 112  * for the United States:
 113  * \htmlonly<blockquote>\endhtmlonly
 114  * <pre>
 115  *       Locale::getUS()
 116  * </pre>
 117  * \htmlonly</blockquote>\endhtmlonly
 118  *
 119  * <P>
 120  * Once you've created a <code>Locale</code> you can query it for information about
 121  * itself. Use <code>getCountry</code> to get the ISO Country Code and
 122  * <code>getLanguage</code> to get the ISO Language Code. You can
 123  * use <code>getDisplayCountry</code> to get the
 124  * name of the country suitable for displaying to the user. Similarly,
 125  * you can use <code>getDisplayLanguage</code> to get the name of
 126  * the language suitable for displaying to the user. Interestingly,
 127  * the <code>getDisplayXXX</code> methods are themselves locale-sensitive
 128  * and have two versions: one that uses the default locale and one
 129  * that takes a locale as an argument and displays the name or country in
 130  * a language appropriate to that locale.
 131  *
 132  * <P>
 133  * ICU provides a number of classes that perform locale-sensitive
 134  * operations. For example, the <code>NumberFormat</code> class formats
 135  * numbers, currency, or percentages in a locale-sensitive manner. Classes
 136  * such as <code>NumberFormat</code> have a number of convenience methods
 137  * for creating a default object of that type. For example, the
 138  * <code>NumberFormat</code> class provides these three convenience methods
 139  * for creating a default <code>NumberFormat</code> object:
 140  * \htmlonly<blockquote>\endhtmlonly
 141  * <pre>
 142  *     UErrorCode success = U_ZERO_ERROR;
 143  *     Locale myLocale;
 144  *     NumberFormat *nf;
 145  *
 146  *     nf = NumberFormat::createInstance( success );          delete nf;
 147  *     nf = NumberFormat::createCurrencyInstance( success );  delete nf;
 148  *     nf = NumberFormat::createPercentInstance( success );   delete nf;
 149  * </pre>
 150  * \htmlonly</blockquote>\endhtmlonly
 151  * Each of these methods has two variants; one with an explicit locale
 152  * and one without; the latter using the default locale.
 153  * \htmlonly<blockquote>\endhtmlonly
 154  * <pre>
 155  *     nf = NumberFormat::createInstance( myLocale, success );          delete nf;
 156  *     nf = NumberFormat::createCurrencyInstance( myLocale, success );  delete nf;
 157  *     nf = NumberFormat::createPercentInstance( myLocale, success );   delete nf;
 158  * </pre>
 159  * \htmlonly</blockquote>\endhtmlonly
 160  * A <code>Locale</code> is the mechanism for identifying the kind of object
 161  * (<code>NumberFormat</code>) that you would like to get. The locale is
 162  * <STRONG>just</STRONG> a mechanism for identifying objects,
 163  * <STRONG>not</STRONG> a container for the objects themselves.
 164  *
 165  * <P>
 166  * Each class that performs locale-sensitive operations allows you
 167  * to get all the available objects of that type. You can sift
 168  * through these objects by language, country, or variant,
 169  * and use the display names to present a menu to the user.
 170  * For example, you can create a menu of all the collation objects
 171  * suitable for a given language. Such classes implement these
 172  * three class methods:
 173  * \htmlonly<blockquote>\endhtmlonly
 174  * <pre>
 175  *       static Locale* getAvailableLocales(int32_t& numLocales)
 176  *       static UnicodeString& getDisplayName(const Locale&  objectLocale,
 177  *                                            const Locale&  displayLocale,
 178  *                                            UnicodeString& displayName)
 179  *       static UnicodeString& getDisplayName(const Locale&  objectLocale,
 180  *                                            UnicodeString& displayName)
 181  * </pre>
 182  * \htmlonly</blockquote>\endhtmlonly
 183  *
 184  * @stable ICU 2.0
 185  * @see ResourceBundle
 186  */
 187 class U_COMMON_API Locale : public UObject {
 188 public:
 189     /** Useful constant for the Root locale. @stable ICU 4.4 */
 190     static const Locale &U_EXPORT2 getRoot(void);
 191     /** Useful constant for this language. @stable ICU 2.0 */
 192     static const Locale &U_EXPORT2 getEnglish(void);
 193     /** Useful constant for this language. @stable ICU 2.0 */
 194     static const Locale &U_EXPORT2 getFrench(void);
 195     /** Useful constant for this language. @stable ICU 2.0 */
 196     static const Locale &U_EXPORT2 getGerman(void);
 197     /** Useful constant for this language. @stable ICU 2.0 */
 198     static const Locale &U_EXPORT2 getItalian(void);
 199     /** Useful constant for this language. @stable ICU 2.0 */
 200     static const Locale &U_EXPORT2 getJapanese(void);
 201     /** Useful constant for this language. @stable ICU 2.0 */
 202     static const Locale &U_EXPORT2 getKorean(void);
 203     /** Useful constant for this language. @stable ICU 2.0 */
 204     static const Locale &U_EXPORT2 getChinese(void);
 205     /** Useful constant for this language. @stable ICU 2.0 */
 206     static const Locale &U_EXPORT2 getSimplifiedChinese(void);
 207     /** Useful constant for this language. @stable ICU 2.0 */
 208     static const Locale &U_EXPORT2 getTraditionalChinese(void);
 209
 210     /** Useful constant for this country/region. @stable ICU 2.0 */
 211     static const Locale &U_EXPORT2 getFrance(void);
 212     /** Useful constant for this country/region. @stable ICU 2.0 */
 213     static const Locale &U_EXPORT2 getGermany(void);
 214     /** Useful constant for this country/region. @stable ICU 2.0 */
 215     static const Locale &U_EXPORT2 getItaly(void);
 216     /** Useful constant for this country/region. @stable ICU 2.0 */
 217     static const Locale &U_EXPORT2 getJapan(void);
 218     /** Useful constant for this country/region. @stable ICU 2.0 */
 219     static const Locale &U_EXPORT2 getKorea(void);
 220     /** Useful constant for this country/region. @stable ICU 2.0 */
 221     static const Locale &U_EXPORT2 getChina(void);
 222     /** Useful constant for this country/region. @stable ICU 2.0 */
 223     static const Locale &U_EXPORT2 getPRC(void);
 224     /** Useful constant for this country/region. @stable ICU 2.0 */
 225     static const Locale &U_EXPORT2 getTaiwan(void);
 226     /** Useful constant for this country/region. @stable ICU 2.0 */
 227     static const Locale &U_EXPORT2 getUK(void);
 228     /** Useful constant for this country/region. @stable ICU 2.0 */
 229     static const Locale &U_EXPORT2 getUS(void);
 230     /** Useful constant for this country/region. @stable ICU 2.0 */
 231     static const Locale &U_EXPORT2 getCanada(void);
 232     /** Useful constant for this country/region. @stable ICU 2.0 */
 233     static const Locale &U_EXPORT2 getCanadaFrench(void);
 234
 235
 236     /**
 237      * Construct a default locale object, a Locale for the default locale ID.
 238      *
 239      * @see getDefault
 240      * @see uloc_getDefault
 241      * @stable ICU 2.0
 242      */
 243     Locale();
 244
 245     /**
 246      * Construct a locale from language, country, variant.
 247      * If an error occurs, then the constructed object will be "bogus"
 248      * (isBogus() will return TRUE).
 249      *
 250      * @param language Lowercase two-letter or three-letter ISO-639 code.
 251      *  This parameter can instead be an ICU style C locale (e.g. "en_US"),
 252      *  but the other parameters must not be used.
 253      *  This parameter can be NULL; if so,
 254      *  the locale is initialized to match the current default locale.
 255      *  (This is the same as using the default constructor.)
 256      *  Please note: The Java Locale class does NOT accept the form
 257      *  'new Locale("en_US")' but only 'new Locale("en","US")'
 258      *
 259      * @param country  Uppercase two-letter ISO-3166 code. (optional)
 260      * @param variant  Uppercase vendor and browser specific code. See class
 261      *                 description. (optional)
 262      * @param keywordsAndValues A string consisting of keyword/values pairs, such as
 263      *                 "collation=phonebook;currency=euro"
 264      *
 265      * @see getDefault
 266      * @see uloc_getDefault
 267      * @stable ICU 2.0
 268      */
 269     Locale( const   char * language,
 270             const   char * country  = 0,
 271             const   char * variant  = 0,
 272             const   char * keywordsAndValues = 0);
 273
 274     /**
 275      * Initializes a Locale object from another Locale object.
 276      *
 277      * @param other The Locale object being copied in.
 278      * @stable ICU 2.0
 279      */
 280     Locale(const    Locale& other);
 281
 282
 283     /**
 284      * Destructor
 285      * @stable ICU 2.0
 286      */
 287     virtual ~Locale() ;
 288
 289     /**
 290      * Replaces the entire contents of *this with the specified value.
 291      *
 292      * @param other The Locale object being copied in.
 293      * @return      *this
 294      * @stable ICU 2.0
 295      */
 296     Locale& operator=(const Locale& other);
 297
 298     /**
 299      * Checks if two locale keys are the same.
 300      *
 301      * @param other The locale key object to be compared with this.
 302      * @return      True if the two locale keys are the same, false otherwise.
 303      * @stable ICU 2.0
 304      */
 305     UBool   operator==(const    Locale&     other) const;
 306
 307     /**
 308      * Checks if two locale keys are not the same.
 309      *
 310      * @param other The locale key object to be compared with this.
 311      * @return      True if the two locale keys are not the same, false
 312      *              otherwise.
 313      * @stable ICU 2.0
 314      */
 315     UBool   operator!=(const    Locale&     other) const;
 316
 317     /**
 318      * Clone this object.
 319      * Clones can be used concurrently in multiple threads.
 320      * If an error occurs, then NULL is returned.
 321      * The caller must delete the clone.
 322      *
 323      * @return a clone of this object
 324      *
 325      * @see getDynamicClassID
 326      * @stable ICU 2.8
 327      */
 328     Locale *clone() const;
 329
 330 #ifndef U_HIDE_SYSTEM_API
 331     /**
 332      * Common methods of getting the current default Locale. Used for the
 333      * presentation: menus, dialogs, etc. Generally set once when your applet or
 334      * application is initialized, then never reset. (If you do reset the
 335      * default locale, you probably want to reload your GUI, so that the change
 336      * is reflected in your interface.)
 337      *
 338      * More advanced programs will allow users to use different locales for
 339      * different fields, e.g. in a spreadsheet.
 340      *
 341      * Note that the initial setting will match the host system.
 342      * @return a reference to the Locale object for the default locale ID
 343      * @system
 344      * @stable ICU 2.0
 345      */
 346     static const Locale& U_EXPORT2 getDefault(void);
 347
 348     /**
 349      * Sets the default. Normally set once at the beginning of a process,
 350      * then never reset.
 351      * setDefault() only changes ICU's default locale ID, <strong>not</strong>
 352      * the default locale ID of the runtime environment.
 353      *
 354      * @param newLocale Locale to set to.  If NULL, set to the value obtained
 355      *                  from the runtime environement.
 356      * @param success The error code.
 357      * @system
 358      * @stable ICU 2.0
 359      */
 360     static void U_EXPORT2 setDefault(const Locale& newLocale,
 361                                      UErrorCode&   success);
 362 #endif  /* U_HIDE_SYSTEM_API */
 363
 364     /**
 365      * Creates a locale which has had minimal canonicalization
 366      * as per uloc_getName().
 367      * @param name The name to create from.  If name is null,
 368      *  the default Locale is used.
 369      * @return new locale object
 370      * @stable ICU 2.0
 371      * @see uloc_getName
 372      */
 373     static Locale U_EXPORT2 createFromName(const char *name);
 374
 375     /**
 376      * Creates a locale from the given string after canonicalizing
 377      * the string by calling uloc_canonicalize().
 378      * @param name the locale ID to create from.  Must not be NULL.
 379      * @return a new locale object corresponding to the given name
 380      * @stable ICU 3.0
 381      * @see uloc_canonicalize
 382      */
 383     static Locale U_EXPORT2 createCanonical(const char* name);
 384
 385     /**
 386      * Returns the locale's ISO-639 language code.
 387      * @return      An alias to the code
 388      * @stable ICU 2.0
 389      */
 390     inline const char *  getLanguage( ) const;
 391
 392     /**
 393      * Returns the locale's ISO-15924 abbreviation script code.
 394      * @return      An alias to the code
 395      * @see uscript_getShortName
 396      * @see uscript_getCode
 397      * @stable ICU 2.8
 398      */
 399     inline const char *  getScript( ) const;
 400
 401     /**
 402      * Returns the locale's ISO-3166 country code.
 403      * @return      An alias to the code
 404      * @stable ICU 2.0
 405      */
 406     inline const char *  getCountry( ) const;
 407
 408     /**
 409      * Returns the locale's variant code.
 410      * @return      An alias to the code
 411      * @stable ICU 2.0
 412      */
 413     inline const char *  getVariant( ) const;
 414
 415     /**
 416      * Returns the programmatic name of the entire locale, with the language,
 417      * country and variant separated by underbars. If a field is missing, up
 418      * to two leading underbars will occur. Example: "en", "de_DE", "en_US_WIN",
 419      * "de__POSIX", "fr__MAC", "__MAC", "_MT", "_FR_EURO"
 420      * @return      A pointer to "name".
 421      * @stable ICU 2.0
 422      */
 423     inline const char * getName() const;
 424
 425     /**
 426      * Returns the programmatic name of the entire locale as getName() would return,
 427      * but without keywords.
 428      * @return      A pointer to "name".
 429      * @see getName
 430      * @stable ICU 2.8
 431      */
 432     const char * getBaseName() const;
 433
 434
 435     /**
 436      * Gets the list of keywords for the specified locale.
 437      *
 438      * @param status the status code
 439      * @return pointer to StringEnumeration class, or NULL if there are no keywords.
 440      * Client must dispose of it by calling delete.
 441      * @stable ICU 2.8
 442      */
 443     StringEnumeration * createKeywords(UErrorCode &status) const;
 444
 445     /**
 446      * Gets the value for a keyword.
 447      *
 448      * @param keywordName name of the keyword for which we want the value. Case insensitive.
 449      * @param buffer The buffer to receive the keyword value.
 450      * @param bufferCapacity The capacity of receiving buffer
 451      * @param status Returns any error information while performing this operation.
 452      * @return the length of the keyword value
 453      *
 454      * @stable ICU 2.8
 455      */
 456     int32_t getKeywordValue(const char* keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const;
 457
 458     /**
 459      * Sets or removes the value for a keyword.
 460      *
 461      * For removing all keywords, use getBaseName(),
 462      * and construct a new Locale if it differs from getName().
 463      *
 464      * @param keywordName name of the keyword to be set. Case insensitive.
 465      * @param keywordValue value of the keyword to be set. If 0-length or
 466      *  NULL, will result in the keyword being removed. No error is given if
 467      *  that keyword does not exist.
 468      * @param status Returns any error information while performing this operation.
 469      *
 470      * @stable ICU 49
 471      */
 472     void setKeywordValue(const char* keywordName, const char* keywordValue, UErrorCode &status);
 473
 474     /**
 475      * returns the locale's three-letter language code, as specified
 476      * in ISO draft standard ISO-639-2.
 477      * @return      An alias to the code, or an empty string
 478      * @stable ICU 2.0
 479      */
 480     const char * getISO3Language() const;
 481
 482     /**
 483      * Fills in "name" with the locale's three-letter ISO-3166 country code.
 484      * @return      An alias to the code, or an empty string
 485      * @stable ICU 2.0
 486      */
 487     const char * getISO3Country() const;
 488
 489     /**
 490      * Returns the Windows LCID value corresponding to this locale.
 491      * This value is stored in the resource data for the locale as a one-to-four-digit
 492      * hexadecimal number.  If the resource is missing, in the wrong format, or
 493      * there is no Windows LCID value that corresponds to this locale, returns 0.
 494      * @stable ICU 2.0
 495      */
 496     uint32_t        getLCID(void) const;
 497
 498     /**
 499      * Returns whether this locale's script is written right-to-left.
 500      * If there is no script subtag, then the likely script is used, see uloc_addLikelySubtags().
 501      * If no likely script is known, then FALSE is returned.
 502      *
 503      * A script is right-to-left according to the CLDR script metadata
 504      * which corresponds to whether the script's letters have Bidi_Class=R or AL.
 505      *
 506      * Returns TRUE for "ar" and "en-Hebr", FALSE for "zh" and "fa-Cyrl".
 507      *
 508      * @return TRUE if the locale's script is written right-to-left
 509      * @stable ICU 54
 510      */
 511     UBool isRightToLeft() const;
 512
 513     /**
 514      * Fills in "dispLang" with the name of this locale's language in a format suitable for
 515      * user display in the default locale.  For example, if the locale's language code is
 516      * "fr" and the default locale's language code is "en", this function would set
 517      * dispLang to "French".
 518      * @param dispLang  Receives the language's display name.
 519      * @return          A reference to "dispLang".
 520      * @stable ICU 2.0
 521      */
 522     UnicodeString&  getDisplayLanguage(UnicodeString&   dispLang) const;
 523
 524     /**
 525      * Fills in "dispLang" with the name of this locale's language in a format suitable for
 526      * user display in the locale specified by "displayLocale".  For example, if the locale's
 527      * language code is "en" and displayLocale's language code is "fr", this function would set
 528      * dispLang to "Anglais".
 529      * @param displayLocale  Specifies the locale to be used to display the name.  In other words,
 530      *                  if the locale's language code is "en", passing Locale::getFrench() for
 531      *                  displayLocale would result in "Anglais", while passing Locale::getGerman()
 532      *                  for displayLocale would result in "Englisch".
 533      * @param dispLang  Receives the language's display name.
 534      * @return          A reference to "dispLang".
 535      * @stable ICU 2.0
 536      */
 537     UnicodeString&  getDisplayLanguage( const   Locale&         displayLocale,
 538                                                 UnicodeString&  dispLang) const;
 539
 540     /**
 541      * Fills in "dispScript" with the name of this locale's script in a format suitable
 542      * for user display in the default locale.  For example, if the locale's script code
 543      * is "LATN" and the default locale's language code is "en", this function would set
 544      * dispScript to "Latin".
 545      * @param dispScript    Receives the scripts's display name.
 546      * @return              A reference to "dispScript".
 547      * @stable ICU 2.8
 548      */
 549     UnicodeString&  getDisplayScript(          UnicodeString& dispScript) const;
 550
 551     /**
 552      * Fills in "dispScript" with the name of this locale's country in a format suitable
 553      * for user display in the locale specified by "displayLocale".  For example, if the locale's
 554      * script code is "LATN" and displayLocale's language code is "en", this function would set
 555      * dispScript to "Latin".
 556      * @param displayLocale      Specifies the locale to be used to display the name.  In other
 557      *                      words, if the locale's script code is "LATN", passing
 558      *                      Locale::getFrench() for displayLocale would result in "", while
 559      *                      passing Locale::getGerman() for displayLocale would result in
 560      *                      "".
 561      * @param dispScript    Receives the scripts's display name.
 562      * @return              A reference to "dispScript".
 563      * @stable ICU 2.8
 564      */
 565     UnicodeString&  getDisplayScript(  const   Locale&         displayLocale,
 566                                                UnicodeString&  dispScript) const;
 567
 568     /**
 569      * Fills in "dispCountry" with the name of this locale's country in a format suitable
 570      * for user display in the default locale.  For example, if the locale's country code
 571      * is "FR" and the default locale's language code is "en", this function would set
 572      * dispCountry to "France".
 573      * @param dispCountry   Receives the country's display name.
 574      * @return              A reference to "dispCountry".
 575      * @stable ICU 2.0
 576      */
 577     UnicodeString&  getDisplayCountry(          UnicodeString& dispCountry) const;
 578
 579     /**
 580      * Fills in "dispCountry" with the name of this locale's country in a format suitable
 581      * for user display in the locale specified by "displayLocale".  For example, if the locale's
 582      * country code is "US" and displayLocale's language code is "fr", this function would set
 583      * dispCountry to "&Eacute;tats-Unis".
 584      * @param displayLocale      Specifies the locale to be used to display the name.  In other
 585      *                      words, if the locale's country code is "US", passing
 586      *                      Locale::getFrench() for displayLocale would result in "&Eacute;tats-Unis", while
 587      *                      passing Locale::getGerman() for displayLocale would result in
 588      *                      "Vereinigte Staaten".
 589      * @param dispCountry   Receives the country's display name.
 590      * @return              A reference to "dispCountry".
 591      * @stable ICU 2.0
 592      */
 593     UnicodeString&  getDisplayCountry(  const   Locale&         displayLocale,
 594                                                 UnicodeString&  dispCountry) const;
 595
 596     /**
 597      * Fills in "dispVar" with the name of this locale's variant code in a format suitable
 598      * for user display in the default locale.
 599      * @param dispVar   Receives the variant's name.
 600      * @return          A reference to "dispVar".
 601      * @stable ICU 2.0
 602      */
 603     UnicodeString&  getDisplayVariant(      UnicodeString& dispVar) const;
 604
 605     /**
 606      * Fills in "dispVar" with the name of this locale's variant code in a format
 607      * suitable for user display in the locale specified by "displayLocale".
 608      * @param displayLocale  Specifies the locale to be used to display the name.
 609      * @param dispVar   Receives the variant's display name.
 610      * @return          A reference to "dispVar".
 611      * @stable ICU 2.0
 612      */
 613     UnicodeString&  getDisplayVariant(  const   Locale&         displayLocale,
 614                                                 UnicodeString&  dispVar) const;
 615
 616     /**
 617      * Fills in "name" with the name of this locale in a format suitable for user display
 618      * in the default locale.  This function uses getDisplayLanguage(), getDisplayCountry(),
 619      * and getDisplayVariant() to do its work, and outputs the display name in the format
 620      * "language (country[,variant])".  For example, if the default locale is en_US, then
 621      * fr_FR's display name would be "French (France)", and es_MX_Traditional's display name
 622      * would be "Spanish (Mexico,Traditional)".
 623      * @param name  Receives the locale's display name.
 624      * @return      A reference to "name".
 625      * @stable ICU 2.0
 626      */
 627     UnicodeString&  getDisplayName(         UnicodeString&  name) const;
 628
 629     /**
 630      * Fills in "name" with the name of this locale in a format suitable for user display
 631      * in the locale specfied by "displayLocale".  This function uses getDisplayLanguage(),
 632      * getDisplayCountry(), and getDisplayVariant() to do its work, and outputs the display
 633      * name in the format "language (country[,variant])".  For example, if displayLocale is
 634      * fr_FR, then en_US's display name would be "Anglais (&Eacute;tats-Unis)", and no_NO_NY's
 635      * display name would be "norv&eacute;gien (Norv&egrave;ge,NY)".
 636      * @param displayLocale  Specifies the locale to be used to display the name.
 637      * @param name      Receives the locale's display name.
 638      * @return          A reference to "name".
 639      * @stable ICU 2.0
 640      */
 641     UnicodeString&  getDisplayName( const   Locale&         displayLocale,
 642                                             UnicodeString&  name) const;
 643
 644     /**
 645      * Generates a hash code for the locale.
 646      * @stable ICU 2.0
 647      */
 648     int32_t         hashCode(void) const;
 649
 650     /**
 651      * Sets the locale to bogus
 652      * A bogus locale represents a non-existing locale associated
 653      * with services that can be instantiated from non-locale data
 654      * in addition to locale (for example, collation can be
 655      * instantiated from a locale and from a rule set).
 656      * @stable ICU 2.1
 657      */
 658     void setToBogus();
 659
 660     /**
 661      * Gets the bogus state. Locale object can be bogus if it doesn't exist
 662      * @return FALSE if it is a real locale, TRUE if it is a bogus locale
 663      * @stable ICU 2.1
 664      */
 665     UBool isBogus(void) const;
 666
 667     /**
 668      * Returns a list of all installed locales.
 669      * @param count Receives the number of locales in the list.
 670      * @return      A pointer to an array of Locale objects.  This array is the list
 671      *              of all locales with installed resource files.  The called does NOT
 672      *              get ownership of this list, and must NOT delete it.
 673      * @stable ICU 2.0
 674      */
 675     static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
 676
 677     /**
 678      * Gets a list of all available 2-letter country codes defined in ISO 3166.  This is a
 679      * pointer to an array of pointers to arrays of char.  All of these pointers are
 680      * owned by ICU-- do not delete them, and do not write through them.  The array is
 681      * terminated with a null pointer.
 682      * @return a list of all available country codes
 683      * @stable ICU 2.0
 684      */
 685     static const char* const* U_EXPORT2 getISOCountries();
 686
 687     /**
 688      * Gets a list of all available language codes defined in ISO 639.  This is a pointer
 689      * to an array of pointers to arrays of char.  All of these pointers are owned
 690      * by ICU-- do not delete them, and do not write through them.  The array is
 691      * terminated with a null pointer.
 692      * @return a list of all available language codes
 693      * @stable ICU 2.0
 694      */
 695     static const char* const* U_EXPORT2 getISOLanguages();
 696
 697     /**
 698      * ICU "poor man's RTTI", returns a UClassID for this class.
 699      *
 700      * @stable ICU 2.2
 701      */
 702     static UClassID U_EXPORT2 getStaticClassID();
 703
 704     /**
 705      * ICU "poor man's RTTI", returns a UClassID for the actual class.
 706      *
 707      * @stable ICU 2.2
 708      */
 709     virtual UClassID getDynamicClassID() const;
 710
 711 protected: /* only protected for testing purposes. DO NOT USE. */
 712 #ifndef U_HIDE_INTERNAL_API
 713     /**
 714      * Set this from a single POSIX style locale string.
 715      * @internal
 716      */
 717     void setFromPOSIXID(const char *posixID);
 718 #endif  /* U_HIDE_INTERNAL_API */
 719
 720 private:
 721     /**
 722      * Initialize the locale object with a new name.
 723      * Was deprecated - used in implementation - moved internal
 724      *
 725      * @param cLocaleID The new locale name.
 726      * @param canonicalize whether to call uloc_canonicalize on cLocaleID
 727      */
 728     Locale& init(const char* cLocaleID, UBool canonicalize);
 729
 730     /*
 731      * Internal constructor to allow construction of a locale object with
 732      *   NO side effects.   (Default constructor tries to get
 733      *   the default locale.)
 734      */
 735     enum ELocaleType {
 736         eBOGUS
 737     };
 738     Locale(ELocaleType);
 739
 740     /**
 741      * Initialize the locale cache for commonly used locales
 742      */
 743     static Locale *getLocaleCache(void);
 744
 745     char language[ULOC_LANG_CAPACITY];
 746     char script[ULOC_SCRIPT_CAPACITY];
 747     char country[ULOC_COUNTRY_CAPACITY];
 748     int32_t variantBegin;
 749     char* fullName;
 750     char fullNameBuffer[ULOC_FULLNAME_CAPACITY];
 751     // name without keywords
 752     char* baseName;
 753     void initBaseName(UErrorCode& status);
 754
 755     UBool fIsBogus;
 756
 757     static const Locale &getLocale(int locid);
 758
 759     /**
 760      * A friend to allow the default locale to be set by either the C or C++ API.
 761      * @internal
 762      */
 763     friend Locale *locale_set_default_internal(const char *, UErrorCode& status);
 764
 765     /**
 766      * @internal
 767      */
 768     friend void U_CALLCONV locale_available_init();
 769 };
 770
 771 inline UBool
 772 Locale::operator!=(const    Locale&     other) const
 773 {
 774     return !operator==(other);
 775 }
 776
 777 inline const char *
 778 Locale::getCountry() const
 779 {
 780     return country;
 781 }
 782
 783 inline const char *
 784 Locale::getLanguage() const
 785 {
 786     return language;
 787 }
 788
 789 inline const char *
 790 Locale::getScript() const
 791 {
 792     return script;
 793 }
 794
 795 inline const char *
 796 Locale::getVariant() const
 797 {
 798     return &baseName[variantBegin];
 799 }
 800
 801 inline const char *
 802 Locale::getName() const
 803 {
 804     return fullName;
 805 }
 806
 807 inline UBool
 808 Locale::isBogus(void) const {
 809     return fIsBogus;
 810 }
 811
 812 U_NAMESPACE_END
 813
 814 #endif