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