1 // 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/bytestream.h" 35 #include "unicode/localpointer.h" 36 #include "unicode/strenum.h" 37 #include "unicode/stringpiece.h" 38 #include "unicode/utypes.h" 39 #include "unicode/uobject.h" 40 #include "unicode/putil.h" 41 #include "unicode/uloc.h" 42 43 /** 44 * \file 45 * \brief C++ API: Locale ID object. 46 */ 47 48 U_NAMESPACE_BEGIN 49 50 // Forward Declarations 51 void U_CALLCONV locale_available_init(); /**< @internal */ 52 53 class StringEnumeration; 54 class UnicodeString; 55 56 /** 57 * A <code>Locale</code> object represents a specific geographical, political, 58 * or cultural region. An operation that requires a <code>Locale</code> to perform 59 * its task is called <em>locale-sensitive</em> and uses the <code>Locale</code> 60 * to tailor information for the user. For example, displaying a number 61 * is a locale-sensitive operation--the number should be formatted 62 * according to the customs/conventions of the user's native country, 63 * region, or culture. 64 * 65 * The Locale class is not suitable for subclassing. 66 * 67 * <P> 68 * You can create a <code>Locale</code> object using the constructor in 69 * this class: 70 * \htmlonly<blockquote>\endhtmlonly 71 * <pre> 72 * Locale( const char* language, 73 * const char* country, 74 * const char* variant); 75 * </pre> 76 * \htmlonly</blockquote>\endhtmlonly 77 * The first argument to the constructors is a valid <STRONG>ISO 78 * Language Code.</STRONG> These codes are the lower-case two-letter 79 * codes as defined by ISO-639. 80 * You can find a full list of these codes at: 81 * <BR><a href ="http://www.loc.gov/standards/iso639-2/"> 82 * http://www.loc.gov/standards/iso639-2/</a> 83 * 84 * <P> 85 * The second argument to the constructors is a valid <STRONG>ISO Country 86 * Code.</STRONG> These codes are the upper-case two-letter codes 87 * as defined by ISO-3166. 88 * You can find a full list of these codes at a number of sites, such as: 89 * <BR><a href="http://www.iso.org/iso/en/prods-services/iso3166ma/index.html"> 90 * http://www.iso.org/iso/en/prods-services/iso3166ma/index.html</a> 91 * 92 * <P> 93 * The third constructor requires a third argument--the <STRONG>Variant.</STRONG> 94 * The Variant codes are vendor and browser-specific. 95 * For example, use REVISED for a language's revised script orthography, and POSIX for POSIX. 96 * Where there are two variants, separate them with an underscore, and 97 * put the most important one first. For 98 * example, a Traditional Spanish collation might be referenced, with 99 * "ES", "ES", "Traditional_POSIX". 100 * 101 * <P> 102 * Because a <code>Locale</code> object is just an identifier for a region, 103 * no validity check is performed when you construct a <code>Locale</code>. 104 * If you want to see whether particular resources are available for the 105 * <code>Locale</code> you construct, you must query those resources. For 106 * example, ask the <code>NumberFormat</code> for the locales it supports 107 * using its <code>getAvailableLocales</code> method. 108 * <BR><STRONG>Note:</STRONG> When you ask for a resource for a particular 109 * locale, you get back the best available match, not necessarily 110 * precisely what you asked for. For more information, look at 111 * <code>ResourceBundle</code>. 112 * 113 * <P> 114 * The <code>Locale</code> class provides a number of convenient constants 115 * that you can use to create <code>Locale</code> objects for commonly used 116 * locales. For example, the following refers to a <code>Locale</code> object 117 * for the United States: 118 * \htmlonly<blockquote>\endhtmlonly 119 * <pre> 120 * Locale::getUS() 121 * </pre> 122 * \htmlonly</blockquote>\endhtmlonly 123 * 124 * <P> 125 * Once you've created a <code>Locale</code> you can query it for information about 126 * itself. Use <code>getCountry</code> to get the ISO Country Code and 127 * <code>getLanguage</code> to get the ISO Language Code. You can 128 * use <code>getDisplayCountry</code> to get the 129 * name of the country suitable for displaying to the user. Similarly, 130 * you can use <code>getDisplayLanguage</code> to get the name of 131 * the language suitable for displaying to the user. Interestingly, 132 * the <code>getDisplayXXX</code> methods are themselves locale-sensitive 133 * and have two versions: one that uses the default locale and one 134 * that takes a locale as an argument and displays the name or country in 135 * a language appropriate to that locale. 136 * 137 * <P> 138 * ICU provides a number of classes that perform locale-sensitive 139 * operations. For example, the <code>NumberFormat</code> class formats 140 * numbers, currency, or percentages in a locale-sensitive manner. Classes 141 * such as <code>NumberFormat</code> have a number of convenience methods 142 * for creating a default object of that type. For example, the 143 * <code>NumberFormat</code> class provides these three convenience methods 144 * for creating a default <code>NumberFormat</code> object: 145 * \htmlonly<blockquote>\endhtmlonly 146 * <pre> 147 * UErrorCode success = U_ZERO_ERROR; 148 * Locale myLocale; 149 * NumberFormat *nf; 150 * 151 * nf = NumberFormat::createInstance( success ); delete nf; 152 * nf = NumberFormat::createCurrencyInstance( success ); delete nf; 153 * nf = NumberFormat::createPercentInstance( success ); delete nf; 154 * </pre> 155 * \htmlonly</blockquote>\endhtmlonly 156 * Each of these methods has two variants; one with an explicit locale 157 * and one without; the latter using the default locale. 158 * \htmlonly<blockquote>\endhtmlonly 159 * <pre> 160 * nf = NumberFormat::createInstance( myLocale, success ); delete nf; 161 * nf = NumberFormat::createCurrencyInstance( myLocale, success ); delete nf; 162 * nf = NumberFormat::createPercentInstance( myLocale, success ); delete nf; 163 * </pre> 164 * \htmlonly</blockquote>\endhtmlonly 165 * A <code>Locale</code> is the mechanism for identifying the kind of object 166 * (<code>NumberFormat</code>) that you would like to get. The locale is 167 * <STRONG>just</STRONG> a mechanism for identifying objects, 168 * <STRONG>not</STRONG> a container for the objects themselves. 169 * 170 * <P> 171 * Each class that performs locale-sensitive operations allows you 172 * to get all the available objects of that type. You can sift 173 * through these objects by language, country, or variant, 174 * and use the display names to present a menu to the user. 175 * For example, you can create a menu of all the collation objects 176 * suitable for a given language. Such classes implement these 177 * three class methods: 178 * \htmlonly<blockquote>\endhtmlonly 179 * <pre> 180 * static Locale* getAvailableLocales(int32_t& numLocales) 181 * static UnicodeString& getDisplayName(const Locale& objectLocale, 182 * const Locale& displayLocale, 183 * UnicodeString& displayName) 184 * static UnicodeString& getDisplayName(const Locale& objectLocale, 185 * UnicodeString& displayName) 186 * </pre> 187 * \htmlonly</blockquote>\endhtmlonly 188 * 189 * @stable ICU 2.0 190 * @see ResourceBundle 191 */ 192 class U_COMMON_API Locale : public UObject { 193 public: 194 /** Useful constant for the Root locale. @stable ICU 4.4 */ 195 static const Locale &U_EXPORT2 getRoot(void); 196 /** Useful constant for this language. @stable ICU 2.0 */ 197 static const Locale &U_EXPORT2 getEnglish(void); 198 /** Useful constant for this language. @stable ICU 2.0 */ 199 static const Locale &U_EXPORT2 getFrench(void); 200 /** Useful constant for this language. @stable ICU 2.0 */ 201 static const Locale &U_EXPORT2 getGerman(void); 202 /** Useful constant for this language. @stable ICU 2.0 */ 203 static const Locale &U_EXPORT2 getItalian(void); 204 /** Useful constant for this language. @stable ICU 2.0 */ 205 static const Locale &U_EXPORT2 getJapanese(void); 206 /** Useful constant for this language. @stable ICU 2.0 */ 207 static const Locale &U_EXPORT2 getKorean(void); 208 /** Useful constant for this language. @stable ICU 2.0 */ 209 static const Locale &U_EXPORT2 getChinese(void); 210 /** Useful constant for this language. @stable ICU 2.0 */ 211 static const Locale &U_EXPORT2 getSimplifiedChinese(void); 212 /** Useful constant for this language. @stable ICU 2.0 */ 213 static const Locale &U_EXPORT2 getTraditionalChinese(void); 214 215 /** Useful constant for this country/region. @stable ICU 2.0 */ 216 static const Locale &U_EXPORT2 getFrance(void); 217 /** Useful constant for this country/region. @stable ICU 2.0 */ 218 static const Locale &U_EXPORT2 getGermany(void); 219 /** Useful constant for this country/region. @stable ICU 2.0 */ 220 static const Locale &U_EXPORT2 getItaly(void); 221 /** Useful constant for this country/region. @stable ICU 2.0 */ 222 static const Locale &U_EXPORT2 getJapan(void); 223 /** Useful constant for this country/region. @stable ICU 2.0 */ 224 static const Locale &U_EXPORT2 getKorea(void); 225 /** Useful constant for this country/region. @stable ICU 2.0 */ 226 static const Locale &U_EXPORT2 getChina(void); 227 /** Useful constant for this country/region. @stable ICU 2.0 */ 228 static const Locale &U_EXPORT2 getPRC(void); 229 /** Useful constant for this country/region. @stable ICU 2.0 */ 230 static const Locale &U_EXPORT2 getTaiwan(void); 231 /** Useful constant for this country/region. @stable ICU 2.0 */ 232 static const Locale &U_EXPORT2 getUK(void); 233 /** Useful constant for this country/region. @stable ICU 2.0 */ 234 static const Locale &U_EXPORT2 getUS(void); 235 /** Useful constant for this country/region. @stable ICU 2.0 */ 236 static const Locale &U_EXPORT2 getCanada(void); 237 /** Useful constant for this country/region. @stable ICU 2.0 */ 238 static const Locale &U_EXPORT2 getCanadaFrench(void); 239 240 241 /** 242 * Construct a default locale object, a Locale for the default locale ID. 243 * 244 * @see getDefault 245 * @see uloc_getDefault 246 * @stable ICU 2.0 247 */ 248 Locale(); 249 250 /** 251 * Construct a locale from language, country, variant. 252 * If an error occurs, then the constructed object will be "bogus" 253 * (isBogus() will return TRUE). 254 * 255 * @param language Lowercase two-letter or three-letter ISO-639 code. 256 * This parameter can instead be an ICU style C locale (e.g. "en_US"), 257 * but the other parameters must not be used. 258 * This parameter can be NULL; if so, 259 * the locale is initialized to match the current default locale. 260 * (This is the same as using the default constructor.) 261 * Please note: The Java Locale class does NOT accept the form 262 * 'new Locale("en_US")' but only 'new Locale("en","US")' 263 * 264 * @param country Uppercase two-letter ISO-3166 code. (optional) 265 * @param variant Uppercase vendor and browser specific code. See class 266 * description. (optional) 267 * @param keywordsAndValues A string consisting of keyword/values pairs, such as 268 * "collation=phonebook;currency=euro" 269 * 270 * @see getDefault 271 * @see uloc_getDefault 272 * @stable ICU 2.0 273 */ 274 Locale( const char * language, 275 const char * country = 0, 276 const char * variant = 0, 277 const char * keywordsAndValues = 0); 278 279 /** 280 * Initializes a Locale object from another Locale object. 281 * 282 * @param other The Locale object being copied in. 283 * @stable ICU 2.0 284 */ 285 Locale(const Locale& other); 286 287 #ifndef U_HIDE_DRAFT_API 288 /** 289 * Move constructor; might leave source in bogus state. 290 * This locale will have the same contents that the source locale had. 291 * 292 * @param other The Locale object being moved in. 293 * @draft ICU 63 294 */ 295 Locale(Locale&& other) U_NOEXCEPT; 296 #endif // U_HIDE_DRAFT_API 297 298 /** 299 * Destructor 300 * @stable ICU 2.0 301 */ 302 virtual ~Locale() ; 303 304 /** 305 * Replaces the entire contents of *this with the specified value. 306 * 307 * @param other The Locale object being copied in. 308 * @return *this 309 * @stable ICU 2.0 310 */ 311 Locale& operator=(const Locale& other); 312 313 #ifndef U_HIDE_DRAFT_API 314 /** 315 * Move assignment operator; might leave source in bogus state. 316 * This locale will have the same contents that the source locale had. 317 * The behavior is undefined if *this and the source are the same object. 318 * 319 * @param other The Locale object being moved in. 320 * @return *this 321 * @draft ICU 63 322 */ 323 Locale& operator=(Locale&& other) U_NOEXCEPT; 324 #endif // U_HIDE_DRAFT_API 325 326 /** 327 * Checks if two locale keys are the same. 328 * 329 * @param other The locale key object to be compared with this. 330 * @return True if the two locale keys are the same, false otherwise. 331 * @stable ICU 2.0 332 */ 333 UBool operator==(const Locale& other) const; 334 335 /** 336 * Checks if two locale keys are not the same. 337 * 338 * @param other The locale key object to be compared with this. 339 * @return True if the two locale keys are not the same, false 340 * otherwise. 341 * @stable ICU 2.0 342 */ 343 UBool operator!=(const Locale& other) const; 344 345 /** 346 * Clone this object. 347 * Clones can be used concurrently in multiple threads. 348 * If an error occurs, then NULL is returned. 349 * The caller must delete the clone. 350 * 351 * @return a clone of this object 352 * 353 * @see getDynamicClassID 354 * @stable ICU 2.8 355 */ 356 Locale *clone() const; 357 358 #ifndef U_HIDE_SYSTEM_API 359 /** 360 * Common methods of getting the current default Locale. Used for the 361 * presentation: menus, dialogs, etc. Generally set once when your applet or 362 * application is initialized, then never reset. (If you do reset the 363 * default locale, you probably want to reload your GUI, so that the change 364 * is reflected in your interface.) 365 * 366 * More advanced programs will allow users to use different locales for 367 * different fields, e.g. in a spreadsheet. 368 * 369 * Note that the initial setting will match the host system. 370 * @return a reference to the Locale object for the default locale ID 371 * @system 372 * @stable ICU 2.0 373 */ 374 static const Locale& U_EXPORT2 getDefault(void); 375 376 /** 377 * Sets the default. Normally set once at the beginning of a process, 378 * then never reset. 379 * setDefault() only changes ICU's default locale ID, <strong>not</strong> 380 * the default locale ID of the runtime environment. 381 * 382 * @param newLocale Locale to set to. If NULL, set to the value obtained 383 * from the runtime environment. 384 * @param success The error code. 385 * @system 386 * @stable ICU 2.0 387 */ 388 static void U_EXPORT2 setDefault(const Locale& newLocale, 389 UErrorCode& success); 390 #endif /* U_HIDE_SYSTEM_API */ 391 392 #ifndef U_HIDE_DRAFT_API 393 /** 394 * Returns a Locale for the specified BCP47 language tag string. 395 * If the specified language tag contains any ill-formed subtags, 396 * the first such subtag and all following subtags are ignored. 397 * <p> 398 * This implements the 'Language-Tag' production of BCP47, and so 399 * supports grandfathered (regular and irregular) as well as private 400 * use language tags. Private use tags are represented as 'x-whatever', 401 * and grandfathered tags are converted to their canonical replacements 402 * where they exist. Note that a few grandfathered tags have no modern 403 * replacement, these will be converted using the fallback described in 404 * the first paragraph, so some information might be lost. 405 * @param tag the input BCP47 language tag. 406 * @param status error information if creating the Locale failed. 407 * @return the Locale for the specified BCP47 language tag. 408 * @draft ICU 63 409 */ 410 static Locale U_EXPORT2 forLanguageTag(StringPiece tag, UErrorCode& status); 411 412 /** 413 * Returns a well-formed language tag for this Locale. 414 * <p> 415 * <b>Note</b>: Any locale fields which do not satisfy the BCP47 syntax 416 * requirement will be silently omitted from the result. 417 * 418 * If this function fails, partial output may have been written to the sink. 419 * 420 * @param sink the output sink receiving the BCP47 language 421 * tag for this Locale. 422 * @param status error information if creating the language tag failed. 423 * @draft ICU 63 424 */ 425 void toLanguageTag(ByteSink& sink, UErrorCode& status) const; 426 427 /** 428 * Returns a well-formed language tag for this Locale. 429 * <p> 430 * <b>Note</b>: Any locale fields which do not satisfy the BCP47 syntax 431 * requirement will be silently omitted from the result. 432 * 433 * @param status error information if creating the language tag failed. 434 * @return the BCP47 language tag for this Locale. 435 * @draft ICU 63 436 */ 437 template<typename StringClass> 438 inline StringClass toLanguageTag(UErrorCode& status) const; 439 #endif // U_HIDE_DRAFT_API 440 441 /** 442 * Creates a locale which has had minimal canonicalization 443 * as per uloc_getName(). 444 * @param name The name to create from. If name is null, 445 * the default Locale is used. 446 * @return new locale object 447 * @stable ICU 2.0 448 * @see uloc_getName 449 */ 450 static Locale U_EXPORT2 createFromName(const char *name); 451 452 /** 453 * Creates a locale from the given string after canonicalizing 454 * the string by calling uloc_canonicalize(). 455 * @param name the locale ID to create from. Must not be NULL. 456 * @return a new locale object corresponding to the given name 457 * @stable ICU 3.0 458 * @see uloc_canonicalize 459 */ 460 static Locale U_EXPORT2 createCanonical(const char* name); 461 462 /** 463 * Returns the locale's ISO-639 language code. 464 * @return An alias to the code 465 * @stable ICU 2.0 466 */ 467 inline const char * getLanguage( ) const; 468 469 /** 470 * Returns the locale's ISO-15924 abbreviation script code. 471 * @return An alias to the code 472 * @see uscript_getShortName 473 * @see uscript_getCode 474 * @stable ICU 2.8 475 */ 476 inline const char * getScript( ) const; 477 478 /** 479 * Returns the locale's ISO-3166 country code. 480 * @return An alias to the code 481 * @stable ICU 2.0 482 */ 483 inline const char * getCountry( ) const; 484 485 /** 486 * Returns the locale's variant code. 487 * @return An alias to the code 488 * @stable ICU 2.0 489 */ 490 inline const char * getVariant( ) const; 491 492 /** 493 * Returns the programmatic name of the entire locale, with the language, 494 * country and variant separated by underbars. If a field is missing, up 495 * to two leading underbars will occur. Example: "en", "de_DE", "en_US_WIN", 496 * "de__POSIX", "fr__MAC", "__MAC", "_MT", "_FR_EURO" 497 * @return A pointer to "name". 498 * @stable ICU 2.0 499 */ 500 inline const char * getName() const; 501 502 /** 503 * Returns the programmatic name of the entire locale as getName() would return, 504 * but without keywords. 505 * @return A pointer to "name". 506 * @see getName 507 * @stable ICU 2.8 508 */ 509 const char * getBaseName() const; 510 511 #ifndef U_HIDE_DRAFT_API 512 /** 513 * Add the likely subtags for this Locale, per the algorithm described 514 * in the following CLDR technical report: 515 * 516 * http://www.unicode.org/reports/tr35/#Likely_Subtags 517 * 518 * If this Locale is already in the maximal form, or not valid, or there is 519 * no data available for maximization, the Locale will be unchanged. 520 * 521 * For example, "und-Zzzz" cannot be maximized, since there is no 522 * reasonable maximization. 523 * 524 * Examples: 525 * 526 * "en" maximizes to "en_Latn_US" 527 * 528 * "de" maximizes to "de_Latn_US" 529 * 530 * "sr" maximizes to "sr_Cyrl_RS" 531 * 532 * "sh" maximizes to "sr_Latn_RS" (Note this will not reverse.) 533 * 534 * "zh_Hani" maximizes to "zh_Hans_CN" (Note this will not reverse.) 535 * 536 * @param status error information if maximizing this Locale failed. 537 * If this Locale is not well-formed, the error code is 538 * U_ILLEGAL_ARGUMENT_ERROR. 539 * @draft ICU 63 540 */ 541 void addLikelySubtags(UErrorCode& status); 542 543 /** 544 * Minimize the subtags for this Locale, per the algorithm described 545 * in the following CLDR technical report: 546 * 547 * http://www.unicode.org/reports/tr35/#Likely_Subtags 548 * 549 * If this Locale is already in the minimal form, or not valid, or there is 550 * no data available for minimization, the Locale will be unchanged. 551 * 552 * Since the minimization algorithm relies on proper maximization, see the 553 * comments for addLikelySubtags for reasons why there might not be any 554 * data. 555 * 556 * Examples: 557 * 558 * "en_Latn_US" minimizes to "en" 559 * 560 * "de_Latn_US" minimizes to "de" 561 * 562 * "sr_Cyrl_RS" minimizes to "sr" 563 * 564 * "zh_Hant_TW" minimizes to "zh_TW" (The region is preferred to the 565 * script, and minimizing to "zh" would imply "zh_Hans_CN".) 566 * 567 * @param status error information if maximizing this Locale failed. 568 * If this Locale is not well-formed, the error code is 569 * U_ILLEGAL_ARGUMENT_ERROR. 570 * @draft ICU 63 571 */ 572 void minimizeSubtags(UErrorCode& status); 573 #endif // U_HIDE_DRAFT_API 574 575 /** 576 * Gets the list of keywords for the specified locale. 577 * 578 * @param status the status code 579 * @return pointer to StringEnumeration class, or NULL if there are no keywords. 580 * Client must dispose of it by calling delete. 581 * @see getKeywords 582 * @stable ICU 2.8 583 */ 584 StringEnumeration * createKeywords(UErrorCode &status) const; 585 586 #ifndef U_HIDE_DRAFT_API 587 588 /** 589 * Gets the list of Unicode keywords for the specified locale. 590 * 591 * @param status the status code 592 * @return pointer to StringEnumeration class, or NULL if there are no keywords. 593 * Client must dispose of it by calling delete. 594 * @see getUnicodeKeywords 595 * @draft ICU 63 596 */ 597 StringEnumeration * createUnicodeKeywords(UErrorCode &status) const; 598 599 /** 600 * Gets the set of keywords for this Locale. 601 * 602 * A wrapper to call createKeywords() and write the resulting 603 * keywords as standard strings (or compatible objects) into any kind of 604 * container that can be written to by an STL style output iterator. 605 * 606 * @param iterator an STL style output iterator to write the keywords to. 607 * @param status error information if creating set of keywords failed. 608 * @draft ICU 63 609 */ 610 template<typename StringClass, typename OutputIterator> 611 inline void getKeywords(OutputIterator iterator, UErrorCode& status) const; 612 613 /** 614 * Gets the set of Unicode keywords for this Locale. 615 * 616 * A wrapper to call createUnicodeKeywords() and write the resulting 617 * keywords as standard strings (or compatible objects) into any kind of 618 * container that can be written to by an STL style output iterator. 619 * 620 * @param iterator an STL style output iterator to write the keywords to. 621 * @param status error information if creating set of keywords failed. 622 * @draft ICU 63 623 */ 624 template<typename StringClass, typename OutputIterator> 625 inline void getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const; 626 627 #endif // U_HIDE_DRAFT_API 628 629 /** 630 * Gets the value for a keyword. 631 * 632 * This uses legacy keyword=value pairs, like "collation=phonebook". 633 * 634 * ICU4C doesn't do automatic conversion between legacy and Unicode 635 * keywords and values in getters and setters (as opposed to ICU4J). 636 * 637 * @param keywordName name of the keyword for which we want the value. Case insensitive. 638 * @param buffer The buffer to receive the keyword value. 639 * @param bufferCapacity The capacity of receiving buffer 640 * @param status Returns any error information while performing this operation. 641 * @return the length of the keyword value 642 * 643 * @stable ICU 2.8 644 */ 645 int32_t getKeywordValue(const char* keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const; 646 647 #ifndef U_HIDE_DRAFT_API 648 /** 649 * Gets the value for a keyword. 650 * 651 * This uses legacy keyword=value pairs, like "collation=phonebook". 652 * 653 * ICU4C doesn't do automatic conversion between legacy and Unicode 654 * keywords and values in getters and setters (as opposed to ICU4J). 655 * 656 * @param keywordName name of the keyword for which we want the value. 657 * @param sink the sink to receive the keyword value. 658 * @param status error information if getting the value failed. 659 * @draft ICU 63 660 */ 661 void getKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const; 662 663 /** 664 * Gets the value for a keyword. 665 * 666 * This uses legacy keyword=value pairs, like "collation=phonebook". 667 * 668 * ICU4C doesn't do automatic conversion between legacy and Unicode 669 * keywords and values in getters and setters (as opposed to ICU4J). 670 * 671 * @param keywordName name of the keyword for which we want the value. 672 * @param status error information if getting the value failed. 673 * @return the keyword value. 674 * @draft ICU 63 675 */ 676 template<typename StringClass> 677 inline StringClass getKeywordValue(StringPiece keywordName, UErrorCode& status) const; 678 679 /** 680 * Gets the Unicode value for a Unicode keyword. 681 * 682 * This uses Unicode key-value pairs, like "co-phonebk". 683 * 684 * ICU4C doesn't do automatic conversion between legacy and Unicode 685 * keywords and values in getters and setters (as opposed to ICU4J). 686 * 687 * @param keywordName name of the keyword for which we want the value. 688 * @param sink the sink to receive the keyword value. 689 * @param status error information if getting the value failed. 690 * @draft ICU 63 691 */ 692 void getUnicodeKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const; 693 694 /** 695 * Gets the Unicode value for a Unicode keyword. 696 * 697 * This uses Unicode key-value pairs, like "co-phonebk". 698 * 699 * ICU4C doesn't do automatic conversion between legacy and Unicode 700 * keywords and values in getters and setters (as opposed to ICU4J). 701 * 702 * @param keywordName name of the keyword for which we want the value. 703 * @param status error information if getting the value failed. 704 * @return the keyword value. 705 * @draft ICU 63 706 */ 707 template<typename StringClass> 708 inline StringClass getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const; 709 #endif // U_HIDE_DRAFT_API 710 711 /** 712 * Sets or removes the value for a keyword. 713 * 714 * For removing all keywords, use getBaseName(), 715 * and construct a new Locale if it differs from getName(). 716 * 717 * This uses legacy keyword=value pairs, like "collation=phonebook". 718 * 719 * ICU4C doesn't do automatic conversion between legacy and Unicode 720 * keywords and values in getters and setters (as opposed to ICU4J). 721 * 722 * @param keywordName name of the keyword to be set. Case insensitive. 723 * @param keywordValue value of the keyword to be set. If 0-length or 724 * NULL, will result in the keyword being removed. No error is given if 725 * that keyword does not exist. 726 * @param status Returns any error information while performing this operation. 727 * 728 * @stable ICU 49 729 */ 730 void setKeywordValue(const char* keywordName, const char* keywordValue, UErrorCode &status); 731 732 #ifndef U_HIDE_DRAFT_API 733 /** 734 * Sets or removes the value for a keyword. 735 * 736 * For removing all keywords, use getBaseName(), 737 * and construct a new Locale if it differs from getName(). 738 * 739 * This uses legacy keyword=value pairs, like "collation=phonebook". 740 * 741 * ICU4C doesn't do automatic conversion between legacy and Unicode 742 * keywords and values in getters and setters (as opposed to ICU4J). 743 * 744 * @param keywordName name of the keyword to be set. 745 * @param keywordValue value of the keyword to be set. If 0-length or 746 * NULL, will result in the keyword being removed. No error is given if 747 * that keyword does not exist. 748 * @param status Returns any error information while performing this operation. 749 * @draft ICU 63 750 */ 751 void setKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status); 752 753 /** 754 * Sets or removes the Unicode value for a Unicode keyword. 755 * 756 * For removing all keywords, use getBaseName(), 757 * and construct a new Locale if it differs from getName(). 758 * 759 * This uses Unicode key-value pairs, like "co-phonebk". 760 * 761 * ICU4C doesn't do automatic conversion between legacy and Unicode 762 * keywords and values in getters and setters (as opposed to ICU4J). 763 * 764 * @param keywordName name of the keyword to be set. 765 * @param keywordValue value of the keyword to be set. If 0-length or 766 * NULL, will result in the keyword being removed. No error is given if 767 * that keyword does not exist. 768 * @param status Returns any error information while performing this operation. 769 * @draft ICU 63 770 */ 771 void setUnicodeKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status); 772 #endif // U_HIDE_DRAFT_API 773 774 /** 775 * returns the locale's three-letter language code, as specified 776 * in ISO draft standard ISO-639-2. 777 * @return An alias to the code, or an empty string 778 * @stable ICU 2.0 779 */ 780 const char * getISO3Language() const; 781 782 /** 783 * Fills in "name" with the locale's three-letter ISO-3166 country code. 784 * @return An alias to the code, or an empty string 785 * @stable ICU 2.0 786 */ 787 const char * getISO3Country() const; 788 789 /** 790 * Returns the Windows LCID value corresponding to this locale. 791 * This value is stored in the resource data for the locale as a one-to-four-digit 792 * hexadecimal number. If the resource is missing, in the wrong format, or 793 * there is no Windows LCID value that corresponds to this locale, returns 0. 794 * @stable ICU 2.0 795 */ 796 uint32_t getLCID(void) const; 797 798 /** 799 * Returns whether this locale's script is written right-to-left. 800 * If there is no script subtag, then the likely script is used, see uloc_addLikelySubtags(). 801 * If no likely script is known, then FALSE is returned. 802 * 803 * A script is right-to-left according to the CLDR script metadata 804 * which corresponds to whether the script's letters have Bidi_Class=R or AL. 805 * 806 * Returns TRUE for "ar" and "en-Hebr", FALSE for "zh" and "fa-Cyrl". 807 * 808 * @return TRUE if the locale's script is written right-to-left 809 * @stable ICU 54 810 */ 811 UBool isRightToLeft() const; 812 813 /** 814 * Fills in "dispLang" with the name of this locale's language in a format suitable for 815 * user display in the default locale. For example, if the locale's language code is 816 * "fr" and the default locale's language code is "en", this function would set 817 * dispLang to "French". 818 * @param dispLang Receives the language's display name. 819 * @return A reference to "dispLang". 820 * @stable ICU 2.0 821 */ 822 UnicodeString& getDisplayLanguage(UnicodeString& dispLang) const; 823 824 /** 825 * Fills in "dispLang" with the name of this locale's language in a format suitable for 826 * user display in the locale specified by "displayLocale". For example, if the locale's 827 * language code is "en" and displayLocale's language code is "fr", this function would set 828 * dispLang to "Anglais". 829 * @param displayLocale Specifies the locale to be used to display the name. In other words, 830 * if the locale's language code is "en", passing Locale::getFrench() for 831 * displayLocale would result in "Anglais", while passing Locale::getGerman() 832 * for displayLocale would result in "Englisch". 833 * @param dispLang Receives the language's display name. 834 * @return A reference to "dispLang". 835 * @stable ICU 2.0 836 */ 837 UnicodeString& getDisplayLanguage( const Locale& displayLocale, 838 UnicodeString& dispLang) const; 839 840 /** 841 * Fills in "dispScript" with the name of this locale's script in a format suitable 842 * for user display in the default locale. For example, if the locale's script code 843 * is "LATN" and the default locale's language code is "en", this function would set 844 * dispScript to "Latin". 845 * @param dispScript Receives the scripts's display name. 846 * @return A reference to "dispScript". 847 * @stable ICU 2.8 848 */ 849 UnicodeString& getDisplayScript( UnicodeString& dispScript) const; 850 851 /** 852 * Fills in "dispScript" with the name of this locale's country in a format suitable 853 * for user display in the locale specified by "displayLocale". For example, if the locale's 854 * script code is "LATN" and displayLocale's language code is "en", this function would set 855 * dispScript to "Latin". 856 * @param displayLocale Specifies the locale to be used to display the name. In other 857 * words, if the locale's script code is "LATN", passing 858 * Locale::getFrench() for displayLocale would result in "", while 859 * passing Locale::getGerman() for displayLocale would result in 860 * "". 861 * @param dispScript Receives the scripts's display name. 862 * @return A reference to "dispScript". 863 * @stable ICU 2.8 864 */ 865 UnicodeString& getDisplayScript( const Locale& displayLocale, 866 UnicodeString& dispScript) const; 867 868 /** 869 * Fills in "dispCountry" with the name of this locale's country in a format suitable 870 * for user display in the default locale. For example, if the locale's country code 871 * is "FR" and the default locale's language code is "en", this function would set 872 * dispCountry to "France". 873 * @param dispCountry Receives the country's display name. 874 * @return A reference to "dispCountry". 875 * @stable ICU 2.0 876 */ 877 UnicodeString& getDisplayCountry( UnicodeString& dispCountry) const; 878 879 /** 880 * Fills in "dispCountry" with the name of this locale's country in a format suitable 881 * for user display in the locale specified by "displayLocale". For example, if the locale's 882 * country code is "US" and displayLocale's language code is "fr", this function would set 883 * dispCountry to "États-Unis". 884 * @param displayLocale Specifies the locale to be used to display the name. In other 885 * words, if the locale's country code is "US", passing 886 * Locale::getFrench() for displayLocale would result in "États-Unis", while 887 * passing Locale::getGerman() for displayLocale would result in 888 * "Vereinigte Staaten". 889 * @param dispCountry Receives the country's display name. 890 * @return A reference to "dispCountry". 891 * @stable ICU 2.0 892 */ 893 UnicodeString& getDisplayCountry( const Locale& displayLocale, 894 UnicodeString& dispCountry) const; 895 896 /** 897 * Fills in "dispVar" with the name of this locale's variant code in a format suitable 898 * for user display in the default locale. 899 * @param dispVar Receives the variant's name. 900 * @return A reference to "dispVar". 901 * @stable ICU 2.0 902 */ 903 UnicodeString& getDisplayVariant( UnicodeString& dispVar) const; 904 905 /** 906 * Fills in "dispVar" with the name of this locale's variant code in a format 907 * suitable for user display in the locale specified by "displayLocale". 908 * @param displayLocale Specifies the locale to be used to display the name. 909 * @param dispVar Receives the variant's display name. 910 * @return A reference to "dispVar". 911 * @stable ICU 2.0 912 */ 913 UnicodeString& getDisplayVariant( const Locale& displayLocale, 914 UnicodeString& dispVar) const; 915 916 /** 917 * Fills in "name" with the name of this locale in a format suitable for user display 918 * in the default locale. This function uses getDisplayLanguage(), getDisplayCountry(), 919 * and getDisplayVariant() to do its work, and outputs the display name in the format 920 * "language (country[,variant])". For example, if the default locale is en_US, then 921 * fr_FR's display name would be "French (France)", and es_MX_Traditional's display name 922 * would be "Spanish (Mexico,Traditional)". 923 * @param name Receives the locale's display name. 924 * @return A reference to "name". 925 * @stable ICU 2.0 926 */ 927 UnicodeString& getDisplayName( UnicodeString& name) const; 928 929 /** 930 * Fills in "name" with the name of this locale in a format suitable for user display 931 * in the locale specified by "displayLocale". This function uses getDisplayLanguage(), 932 * getDisplayCountry(), and getDisplayVariant() to do its work, and outputs the display 933 * name in the format "language (country[,variant])". For example, if displayLocale is 934 * fr_FR, then en_US's display name would be "Anglais (États-Unis)", and no_NO_NY's 935 * display name would be "norvégien (Norvège,NY)". 936 * @param displayLocale Specifies the locale to be used to display the name. 937 * @param name Receives the locale's display name. 938 * @return A reference to "name". 939 * @stable ICU 2.0 940 */ 941 UnicodeString& getDisplayName( const Locale& displayLocale, 942 UnicodeString& name) const; 943 944 /** 945 * Generates a hash code for the locale. 946 * @stable ICU 2.0 947 */ 948 int32_t hashCode(void) const; 949 950 /** 951 * Sets the locale to bogus 952 * A bogus locale represents a non-existing locale associated 953 * with services that can be instantiated from non-locale data 954 * in addition to locale (for example, collation can be 955 * instantiated from a locale and from a rule set). 956 * @stable ICU 2.1 957 */ 958 void setToBogus(); 959 960 /** 961 * Gets the bogus state. Locale object can be bogus if it doesn't exist 962 * @return FALSE if it is a real locale, TRUE if it is a bogus locale 963 * @stable ICU 2.1 964 */ 965 UBool isBogus(void) const; 966 967 /** 968 * Returns a list of all installed locales. 969 * @param count Receives the number of locales in the list. 970 * @return A pointer to an array of Locale objects. This array is the list 971 * of all locales with installed resource files. The called does NOT 972 * get ownership of this list, and must NOT delete it. 973 * @stable ICU 2.0 974 */ 975 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count); 976 977 /** 978 * Gets a list of all available 2-letter country codes defined in ISO 3166. This is a 979 * pointer to an array of pointers to arrays of char. All of these pointers are 980 * owned by ICU-- do not delete them, and do not write through them. The array is 981 * terminated with a null pointer. 982 * @return a list of all available country codes 983 * @stable ICU 2.0 984 */ 985 static const char* const* U_EXPORT2 getISOCountries(); 986 987 /** 988 * Gets a list of all available language codes defined in ISO 639. This is a pointer 989 * to an array of pointers to arrays of char. All of these pointers are owned 990 * by ICU-- do not delete them, and do not write through them. The array is 991 * terminated with a null pointer. 992 * @return a list of all available language codes 993 * @stable ICU 2.0 994 */ 995 static const char* const* U_EXPORT2 getISOLanguages(); 996 997 /** 998 * ICU "poor man's RTTI", returns a UClassID for this class. 999 * 1000 * @stable ICU 2.2 1001 */ 1002 static UClassID U_EXPORT2 getStaticClassID(); 1003 1004 /** 1005 * ICU "poor man's RTTI", returns a UClassID for the actual class. 1006 * 1007 * @stable ICU 2.2 1008 */ 1009 virtual UClassID getDynamicClassID() const; 1010 1011 protected: /* only protected for testing purposes. DO NOT USE. */ 1012 #ifndef U_HIDE_INTERNAL_API 1013 /** 1014 * Set this from a single POSIX style locale string. 1015 * @internal 1016 */ 1017 void setFromPOSIXID(const char *posixID); 1018 #endif /* U_HIDE_INTERNAL_API */ 1019 1020 private: 1021 /** 1022 * Initialize the locale object with a new name. 1023 * Was deprecated - used in implementation - moved internal 1024 * 1025 * @param cLocaleID The new locale name. 1026 * @param canonicalize whether to call uloc_canonicalize on cLocaleID 1027 */ 1028 Locale& init(const char* cLocaleID, UBool canonicalize); 1029 1030 /* 1031 * Internal constructor to allow construction of a locale object with 1032 * NO side effects. (Default constructor tries to get 1033 * the default locale.) 1034 */ 1035 enum ELocaleType { 1036 eBOGUS 1037 }; 1038 Locale(ELocaleType); 1039 1040 /** 1041 * Initialize the locale cache for commonly used locales 1042 */ 1043 static Locale *getLocaleCache(void); 1044 1045 char language[ULOC_LANG_CAPACITY]; 1046 char script[ULOC_SCRIPT_CAPACITY]; 1047 char country[ULOC_COUNTRY_CAPACITY]; 1048 int32_t variantBegin; 1049 char* fullName; 1050 char fullNameBuffer[ULOC_FULLNAME_CAPACITY]; 1051 // name without keywords 1052 char* baseName; 1053 void initBaseName(UErrorCode& status); 1054 1055 UBool fIsBogus; 1056 1057 static const Locale &getLocale(int locid); 1058 1059 /** 1060 * A friend to allow the default locale to be set by either the C or C++ API. 1061 * @internal (private) 1062 */ 1063 friend Locale *locale_set_default_internal(const char *, UErrorCode& status); 1064 1065 /** 1066 * @internal (private) 1067 */ 1068 friend void U_CALLCONV locale_available_init(); 1069 }; 1070 1071 inline UBool 1072 Locale::operator!=(const Locale& other) const 1073 { 1074 return !operator==(other); 1075 } 1076 1077 #ifndef U_HIDE_DRAFT_API 1078 template<typename StringClass> inline StringClass 1079 Locale::toLanguageTag(UErrorCode& status) const 1080 { 1081 StringClass result; 1082 StringByteSink<StringClass> sink(&result); 1083 toLanguageTag(sink, status); 1084 return result; 1085 } 1086 #endif // U_HIDE_DRAFT_API 1087 1088 inline const char * 1089 Locale::getCountry() const 1090 { 1091 return country; 1092 } 1093 1094 inline const char * 1095 Locale::getLanguage() const 1096 { 1097 return language; 1098 } 1099 1100 inline const char * 1101 Locale::getScript() const 1102 { 1103 return script; 1104 } 1105 1106 inline const char * 1107 Locale::getVariant() const 1108 { 1109 return &baseName[variantBegin]; 1110 } 1111 1112 inline const char * 1113 Locale::getName() const 1114 { 1115 return fullName; 1116 } 1117 1118 #ifndef U_HIDE_DRAFT_API 1119 1120 template<typename StringClass, typename OutputIterator> inline void 1121 Locale::getKeywords(OutputIterator iterator, UErrorCode& status) const 1122 { 1123 LocalPointer<StringEnumeration> keys(createKeywords(status)); 1124 if (U_FAILURE(status)) { 1125 return; 1126 } 1127 for (;;) { 1128 int32_t resultLength; 1129 const char* buffer = keys->next(&resultLength, status); 1130 if (U_FAILURE(status) || buffer == nullptr) { 1131 return; 1132 } 1133 *iterator++ = StringClass(buffer, resultLength); 1134 } 1135 } 1136 1137 template<typename StringClass, typename OutputIterator> inline void 1138 Locale::getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const 1139 { 1140 LocalPointer<StringEnumeration> keys(createUnicodeKeywords(status)); 1141 if (U_FAILURE(status)) { 1142 return; 1143 } 1144 for (;;) { 1145 int32_t resultLength; 1146 const char* buffer = keys->next(&resultLength, status); 1147 if (U_FAILURE(status) || buffer == nullptr) { 1148 return; 1149 } 1150 *iterator++ = StringClass(buffer, resultLength); 1151 } 1152 } 1153 1154 template<typename StringClass> inline StringClass 1155 Locale::getKeywordValue(StringPiece keywordName, UErrorCode& status) const 1156 { 1157 StringClass result; 1158 StringByteSink<StringClass> sink(&result); 1159 getKeywordValue(keywordName, sink, status); 1160 return result; 1161 } 1162 1163 template<typename StringClass> inline StringClass 1164 Locale::getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const 1165 { 1166 StringClass result; 1167 StringByteSink<StringClass> sink(&result); 1168 getUnicodeKeywordValue(keywordName, sink, status); 1169 return result; 1170 } 1171 1172 #endif // U_HIDE_DRAFT_API 1173 1174 inline UBool 1175 Locale::isBogus(void) const { 1176 return fIsBogus; 1177 } 1178 1179 U_NAMESPACE_END 1180 1181 #endif 1182