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