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();
199 /** Useful constant for this language. @stable ICU 2.0 */
200 static const Locale& U_EXPORT2 getEnglish();
201 /** Useful constant for this language. @stable ICU 2.0 */
202 static const Locale& U_EXPORT2 getFrench();
203 /** Useful constant for this language. @stable ICU 2.0 */
204 static const Locale& U_EXPORT2 getGerman();
205 /** Useful constant for this language. @stable ICU 2.0 */
206 static const Locale& U_EXPORT2 getItalian();
207 /** Useful constant for this language. @stable ICU 2.0 */
208 static const Locale& U_EXPORT2 getJapanese();
209 /** Useful constant for this language. @stable ICU 2.0 */
210 static const Locale& U_EXPORT2 getKorean();
211 /** Useful constant for this language. @stable ICU 2.0 */
212 static const Locale& U_EXPORT2 getChinese();
213 /** Useful constant for this language. @stable ICU 2.0 */
214 static const Locale& U_EXPORT2 getSimplifiedChinese();
215 /** Useful constant for this language. @stable ICU 2.0 */
216 static const Locale& U_EXPORT2 getTraditionalChinese();
217
218 /** Useful constant for this country/region. @stable ICU 2.0 */
219 static const Locale& U_EXPORT2 getFrance();
220 /** Useful constant for this country/region. @stable ICU 2.0 */
221 static const Locale& U_EXPORT2 getGermany();
222 /** Useful constant for this country/region. @stable ICU 2.0 */
223 static const Locale& U_EXPORT2 getItaly();
224 /** Useful constant for this country/region. @stable ICU 2.0 */
225 static const Locale& U_EXPORT2 getJapan();
226 /** Useful constant for this country/region. @stable ICU 2.0 */
227 static const Locale& U_EXPORT2 getKorea();
228 /** Useful constant for this country/region. @stable ICU 2.0 */
229 static const Locale& U_EXPORT2 getChina();
230 /** Useful constant for this country/region. @stable ICU 2.0 */
231 static const Locale& U_EXPORT2 getPRC();
232 /** Useful constant for this country/region. @stable ICU 2.0 */
233 static const Locale& U_EXPORT2 getTaiwan();
234 /** Useful constant for this country/region. @stable ICU 2.0 */
235 static const Locale& U_EXPORT2 getUK();
236 /** Useful constant for this country/region. @stable ICU 2.0 */
237 static const Locale& U_EXPORT2 getUS();
238 /** Useful constant for this country/region. @stable ICU 2.0 */
239 static const Locale& U_EXPORT2 getCanada();
240 /** Useful constant for this country/region. @stable ICU 2.0 */
241 static const Locale& U_EXPORT2 getCanadaFrench();
242
243 /**
244 * Construct a default locale object, a Locale for the default locale ID.
245 *
246 * @see getDefault
247 * @see uloc_getDefault
248 * @stable ICU 2.0
249 */
250 Locale();
251
252 /**
253 * Construct a locale from language, country, variant.
254 * If an error occurs, then the constructed object will be "bogus"
255 * (isBogus() will return true).
256 *
257 * @param language Lowercase two-letter or three-letter ISO-639 code.
258 * This parameter can instead be an ICU style C locale (e.g. "en_US"),
259 * but the other parameters must not be used.
260 * This parameter can be nullptr; if so,
261 * the locale is initialized to match the current default locale.
262 * (This is the same as using the default constructor.)
263 * Please note: The Java Locale class does NOT accept the form
264 * 'new Locale("en_US")' but only 'new Locale("en","US")'
265 *
266 * @param country Uppercase two-letter ISO-3166 code. (optional)
267 * @param variant Uppercase vendor and browser specific code. See class
268 * description. (optional)
269 * @param keywordsAndValues A string consisting of keyword/values pairs, such as
270 * "collation=phonebook;currency=euro"
271 *
272 * @see getDefault
273 * @see uloc_getDefault
274 * @stable ICU 2.0
275 */
276 Locale(const char* language,
277 const char* country = nullptr,
278 const char* variant = nullptr,
279 const char* keywordsAndValues = nullptr);
280
281 /**
282 * Initializes a Locale object from another Locale object.
283 *
284 * @param other The Locale object being copied in.
285 * @stable ICU 2.0
286 */
287 Locale(const Locale& other);
288
289 /**
290 * Move constructor; might leave source in bogus state.
291 * This locale will have the same contents that the source locale had.
292 *
293 * @param other The Locale object being moved in.
294 * @stable ICU 63
295 */
296 Locale(Locale&& other) noexcept;
297
298 /**
299 * Destructor
300 * @stable ICU 2.0
301 */
302 virtual ~Locale() ;
303
304 /**
305 * Replaces the entire contents of *this with the specified value.
306 *
307 * @param other The Locale object being copied in.
308 * @return *this
309 * @stable ICU 2.0
310 */
311 Locale& operator=(const Locale& other);
312
313 /**
314 * Move assignment operator; might leave source in bogus state.
315 * This locale will have the same contents that the source locale had.
316 * The behavior is undefined if *this and the source are the same object.
317 *
318 * @param other The Locale object being moved in.
319 * @return *this
320 * @stable ICU 63
321 */
322 Locale& operator=(Locale&& other) noexcept;
323
324 /**
325 * Checks if two locale keys are the same.
326 *
327 * @param other The locale key object to be compared with this.
328 * @return true if the two locale keys are the same, false otherwise.
329 * @stable ICU 2.0
330 */
331 bool operator==(const Locale& other) const;
332
333 /**
334 * Checks if two locale keys are not the same.
335 *
336 * @param other The locale key object to be compared with this.
337 * @return true if the two locale keys are not the same, false
338 * otherwise.
339 * @stable ICU 2.0
340 */
341 inline bool operator!=(const Locale& other) const;
342
343 /**
344 * Clone this object.
345 * Clones can be used concurrently in multiple threads.
346 * If an error occurs, then nullptr is returned.
347 * The caller must delete the clone.
348 *
349 * @return a clone of this object
350 *
351 * @see getDynamicClassID
352 * @stable ICU 2.8
353 */
354 Locale *clone() const;
355
356 #ifndef U_HIDE_SYSTEM_API
357 /**
358 * Common methods of getting the current default Locale. Used for the
359 * presentation: menus, dialogs, etc. Generally set once when your applet or
360 * application is initialized, then never reset. (If you do reset the
361 * default locale, you probably want to reload your GUI, so that the change
362 * is reflected in your interface.)
363 *
364 * More advanced programs will allow users to use different locales for
365 * different fields, e.g. in a spreadsheet.
366 *
367 * Note that the initial setting will match the host system.
368 * @return a reference to the Locale object for the default locale ID
369 * @system
370 * @stable ICU 2.0
371 */
372 static const Locale& U_EXPORT2 getDefault();
373
374 /**
375 * Sets the default. Normally set once at the beginning of a process,
376 * then never reset.
377 * setDefault() only changes ICU's default locale ID, <strong>not</strong>
378 * the default locale ID of the runtime environment.
379 *
380 * @param newLocale Locale to set to. If nullptr, set to the value obtained
381 * from the runtime environment.
382 * @param success The error code.
383 * @system
384 * @stable ICU 2.0
385 */
386 static void U_EXPORT2 setDefault(const Locale& newLocale,
387 UErrorCode& success);
388 #endif /* U_HIDE_SYSTEM_API */
389
390 /**
391 * Returns a Locale for the specified BCP47 language tag string.
392 * If the specified language tag contains any ill-formed subtags,
393 * the first such subtag and all following subtags are ignored.
394 * <p>
395 * This implements the 'Language-Tag' production of BCP 47, and so
396 * supports legacy language tags (marked as “Type: grandfathered” in BCP 47)
397 * (regular and irregular) as well as private use language tags.
398 *
399 * Private use tags are represented as 'x-whatever',
400 * and legacy tags are converted to their canonical replacements where they exist.
401 *
402 * Note that a few legacy tags have no modern replacement;
403 * these will be converted using the fallback described in
404 * the first paragraph, so some information might be lost.
405 *
406 * @param tag the input BCP47 language tag.
407 * @param status error information if creating the Locale failed.
408 * @return the Locale for the specified BCP47 language tag.
409 * @stable ICU 63
410 */
411 static Locale U_EXPORT2 forLanguageTag(StringPiece tag, UErrorCode& status);
412
413 /**
414 * Returns a well-formed language tag for this Locale.
415 * <p>
416 * <b>Note</b>: Any locale fields which do not satisfy the BCP47 syntax
417 * requirement will be silently omitted from the result.
418 *
419 * If this function fails, partial output may have been written to the sink.
420 *
421 * @param sink the output sink receiving the BCP47 language
422 * tag for this Locale.
423 * @param status error information if creating the language tag failed.
424 * @stable ICU 63
425 */
426 void toLanguageTag(ByteSink& sink, UErrorCode& status) const;
427
428 /**
429 * Returns a well-formed language tag for this Locale.
430 * <p>
431 * <b>Note</b>: Any locale fields which do not satisfy the BCP47 syntax
432 * requirement will be silently omitted from the result.
433 *
434 * @param status error information if creating the language tag failed.
435 * @return the BCP47 language tag for this Locale.
436 * @stable ICU 63
437 */
438 template<typename StringClass>
439 inline StringClass toLanguageTag(UErrorCode& status) const;
440
441 /**
442 * Creates a locale which has had minimal canonicalization
443 * as per uloc_getName().
444 * @param name The name to create from. If name is null,
445 * the default Locale is used.
446 * @return new locale object
447 * @stable ICU 2.0
448 * @see uloc_getName
449 */
450 static Locale U_EXPORT2 createFromName(const char *name);
451
452 /**
453 * Creates a locale from the given string after canonicalizing
454 * the string according to CLDR by calling uloc_canonicalize().
455 * @param name the locale ID to create from. Must not be nullptr.
456 * @return a new locale object corresponding to the given name
457 * @stable ICU 3.0
458 * @see uloc_canonicalize
459 */
460 static Locale U_EXPORT2 createCanonical(const char* name);
461
462 /**
463 * Returns the locale's ISO-639 language code.
464 * @return An alias to the code
465 * @stable ICU 2.0
466 */
467 inline const char * getLanguage( ) const;
468
469 /**
470 * Returns the locale's ISO-15924 abbreviation script code.
471 * @return An alias to the code
472 * @see uscript_getShortName
473 * @see uscript_getCode
474 * @stable ICU 2.8
475 */
476 inline const char * getScript( ) const;
477
478 /**
479 * Returns the locale's ISO-3166 country code.
480 * @return An alias to the code
481 * @stable ICU 2.0
482 */
483 inline const char * getCountry( ) const;
484
485 /**
486 * Returns the locale's variant code.
487 * @return An alias to the code
488 * @stable ICU 2.0
489 */
490 inline const char * getVariant( ) const;
491
492 /**
493 * Returns the programmatic name of the entire locale, with the language,
494 * country and variant separated by underbars. If a field is missing, up
495 * to two leading underbars will occur. Example: "en", "de_DE", "en_US_WIN",
496 * "de__POSIX", "fr__MAC", "__MAC", "_MT", "_FR_EURO"
497 * @return A pointer to "name".
498 * @stable ICU 2.0
499 */
500 inline const char * getName() const;
501
502 /**
503 * Returns the programmatic name of the entire locale as getName() would return,
504 * but without keywords.
505 * @return A pointer to "name".
506 * @see getName
507 * @stable ICU 2.8
508 */
509 const char * getBaseName() const;
510
511 /**
512 * Add the likely subtags for this Locale, per the algorithm described
513 * in the following CLDR technical report:
514 *
515 * http://www.unicode.org/reports/tr35/#Likely_Subtags
516 *
517 * If this Locale is already in the maximal form, or not valid, or there is
518 * no data available for maximization, the Locale will be unchanged.
519 *
520 * For example, "sh" cannot be maximized, since there is no
521 * reasonable maximization.
522 *
523 * Examples:
524 *
525 * "und_Zzzz" maximizes to "en_Latn_US"
526 *
527 * "en" maximizes to "en_Latn_US"
528 *
529 * "de" maximizes to "de_Latn_DE"
530 *
531 * "sr" maximizes to "sr_Cyrl_RS"
532 *
533 * "zh_Hani" maximizes to "zh_Hani_CN"
534 *
535 * @param status error information if maximizing this Locale failed.
536 * If this Locale is not well-formed, the error code is
537 * U_ILLEGAL_ARGUMENT_ERROR.
538 * @stable ICU 63
539 */
540 void addLikelySubtags(UErrorCode& status);
541
542 /**
543 * Minimize the subtags for this Locale, per the algorithm described
544 * in the following CLDR technical report:
545 *
546 * http://www.unicode.org/reports/tr35/#Likely_Subtags
547 *
548 * If this Locale is already in the minimal form, or not valid, or there is
549 * no data available for minimization, the Locale will be unchanged.
550 *
551 * Since the minimization algorithm relies on proper maximization, see the
552 * comments for addLikelySubtags for reasons why there might not be any
553 * data.
554 *
555 * Examples:
556 *
557 * "en_Latn_US" minimizes to "en"
558 *
559 * "de_Latn_US" minimizes to "de"
560 *
561 * "sr_Cyrl_RS" minimizes to "sr"
562 *
563 * "zh_Hant_TW" minimizes to "zh_TW" (The region is preferred to the
564 * script, and minimizing to "zh" would imply "zh_Hans_CN".)
565 *
566 * @param status error information if maximizing this Locale failed.
567 * If this Locale is not well-formed, the error code is
568 * U_ILLEGAL_ARGUMENT_ERROR.
569 * @stable ICU 63
570 */
571 void minimizeSubtags(UErrorCode& status);
572
573 /**
574 * Canonicalize the locale ID of this object according to CLDR.
575 * @param status the status code
576 * @stable ICU 67
577 * @see createCanonical
578 */
579 void canonicalize(UErrorCode& status);
580
581 /**
582 * Gets the list of keywords for the specified locale.
583 *
584 * @param status the status code
585 * @return pointer to StringEnumeration class, or nullptr if there are no keywords.
586 * Client must dispose of it by calling delete.
587 * @see getKeywords
588 * @stable ICU 2.8
589 */
590 StringEnumeration * createKeywords(UErrorCode &status) const;
591
592 /**
593 * Gets the list of Unicode keywords for the specified locale.
594 *
595 * @param status the status code
596 * @return pointer to StringEnumeration class, or nullptr if there are no keywords.
597 * Client must dispose of it by calling delete.
598 * @see getUnicodeKeywords
599 * @stable ICU 63
600 */
601 StringEnumeration * createUnicodeKeywords(UErrorCode &status) const;
602
603 /**
604 * Gets the set of keywords for this Locale.
605 *
606 * A wrapper to call createKeywords() and write the resulting
607 * keywords as standard strings (or compatible objects) into any kind of
608 * container that can be written to by an STL style output iterator.
609 *
610 * @param iterator an STL style output iterator to write the keywords to.
611 * @param status error information if creating set of keywords failed.
612 * @stable ICU 63
613 */
614 template<typename StringClass, typename OutputIterator>
615 inline void getKeywords(OutputIterator iterator, UErrorCode& status) const;
616
617 /**
618 * Gets the set of Unicode keywords for this Locale.
619 *
620 * A wrapper to call createUnicodeKeywords() and write the resulting
621 * keywords as standard strings (or compatible objects) into any kind of
622 * container that can be written to by an STL style output iterator.
623 *
624 * @param iterator an STL style output iterator to write the keywords to.
625 * @param status error information if creating set of keywords failed.
626 * @stable ICU 63
627 */
628 template<typename StringClass, typename OutputIterator>
629 inline void getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const;
630
631 /**
632 * Gets the value for a keyword.
633 *
634 * This uses legacy keyword=value pairs, like "collation=phonebook".
635 *
636 * ICU4C doesn't do automatic conversion between legacy and Unicode
637 * keywords and values in getters and setters (as opposed to ICU4J).
638 *
639 * @param keywordName name of the keyword for which we want the value. Case insensitive.
640 * @param buffer The buffer to receive the keyword value.
641 * @param bufferCapacity The capacity of receiving buffer
642 * @param status Returns any error information while performing this operation.
643 * @return the length of the keyword value
644 *
645 * @stable ICU 2.8
646 */
647 int32_t getKeywordValue(const char* keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const;
648
649 /**
650 * Gets the value for a keyword.
651 *
652 * This uses legacy keyword=value pairs, like "collation=phonebook".
653 *
654 * ICU4C doesn't do automatic conversion between legacy and Unicode
655 * keywords and values in getters and setters (as opposed to ICU4J).
656 *
657 * @param keywordName name of the keyword for which we want the value.
658 * @param sink the sink to receive the keyword value.
659 * @param status error information if getting the value failed.
660 * @stable ICU 63
661 */
662 void getKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
663
664 /**
665 * Gets the value for a keyword.
666 *
667 * This uses legacy keyword=value pairs, like "collation=phonebook".
668 *
669 * ICU4C doesn't do automatic conversion between legacy and Unicode
670 * keywords and values in getters and setters (as opposed to ICU4J).
671 *
672 * @param keywordName name of the keyword for which we want the value.
673 * @param status error information if getting the value failed.
674 * @return the keyword value.
675 * @stable ICU 63
676 */
677 template<typename StringClass>
678 inline StringClass getKeywordValue(StringPiece keywordName, UErrorCode& status) const;
679
680 /**
681 * Gets the Unicode value for a Unicode keyword.
682 *
683 * This uses Unicode key-value pairs, like "co-phonebk".
684 *
685 * ICU4C doesn't do automatic conversion between legacy and Unicode
686 * keywords and values in getters and setters (as opposed to ICU4J).
687 *
688 * @param keywordName name of the keyword for which we want the value.
689 * @param sink the sink to receive the keyword value.
690 * @param status error information if getting the value failed.
691 * @stable ICU 63
692 */
693 void getUnicodeKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
694
695 /**
696 * Gets the Unicode value for a Unicode keyword.
697 *
698 * This uses Unicode key-value pairs, like "co-phonebk".
699 *
700 * ICU4C doesn't do automatic conversion between legacy and Unicode
701 * keywords and values in getters and setters (as opposed to ICU4J).
702 *
703 * @param keywordName name of the keyword for which we want the value.
704 * @param status error information if getting the value failed.
705 * @return the keyword value.
706 * @stable ICU 63
707 */
708 template<typename StringClass>
709 inline StringClass getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const;
710
711 /**
712 * Sets or removes the value for a keyword.
713 *
714 * For removing all keywords, use getBaseName(),
715 * and construct a new Locale if it differs from getName().
716 *
717 * This uses legacy keyword=value pairs, like "collation=phonebook".
718 *
719 * ICU4C doesn't do automatic conversion between legacy and Unicode
720 * keywords and values in getters and setters (as opposed to ICU4J).
721 *
722 * @param keywordName name of the keyword to be set. Case insensitive.
723 * @param keywordValue value of the keyword to be set. If 0-length or
724 * nullptr, will result in the keyword being removed. No error is given if
725 * that keyword does not exist.
726 * @param status Returns any error information while performing this operation.
727 *
728 * @stable ICU 49
729 */
setKeywordValue(const char * keywordName,const char * keywordValue,UErrorCode & status)730 void setKeywordValue(const char* keywordName, const char* keywordValue, UErrorCode &status) {
731 setKeywordValue(StringPiece{keywordName}, StringPiece{keywordValue}, status);
732 }
733
734 /**
735 * Sets or removes the value for a keyword.
736 *
737 * For removing all keywords, use getBaseName(),
738 * and construct a new Locale if it differs from getName().
739 *
740 * This uses legacy keyword=value pairs, like "collation=phonebook".
741 *
742 * ICU4C doesn't do automatic conversion between legacy and Unicode
743 * keywords and values in getters and setters (as opposed to ICU4J).
744 *
745 * @param keywordName name of the keyword to be set.
746 * @param keywordValue value of the keyword to be set. If 0-length or
747 * nullptr, will result in the keyword being removed. No error is given if
748 * that keyword does not exist.
749 * @param status Returns any error information while performing this operation.
750 * @stable ICU 63
751 */
752 void setKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
753
754 /**
755 * Sets or removes the Unicode value for a Unicode keyword.
756 *
757 * For removing all keywords, use getBaseName(),
758 * and construct a new Locale if it differs from getName().
759 *
760 * This uses Unicode key-value pairs, like "co-phonebk".
761 *
762 * ICU4C doesn't do automatic conversion between legacy and Unicode
763 * keywords and values in getters and setters (as opposed to ICU4J).
764 *
765 * @param keywordName name of the keyword to be set.
766 * @param keywordValue value of the keyword to be set. If 0-length or
767 * nullptr, will result in the keyword being removed. No error is given if
768 * that keyword does not exist.
769 * @param status Returns any error information while performing this operation.
770 * @stable ICU 63
771 */
772 void setUnicodeKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
773
774 /**
775 * returns the locale's three-letter language code, as specified
776 * in ISO draft standard ISO-639-2.
777 * @return An alias to the code, or an empty string
778 * @stable ICU 2.0
779 */
780 const char * getISO3Language() const;
781
782 /**
783 * Fills in "name" with the locale's three-letter ISO-3166 country code.
784 * @return An alias to the code, or an empty string
785 * @stable ICU 2.0
786 */
787 const char * getISO3Country() const;
788
789 /**
790 * Returns the Windows LCID value corresponding to this locale.
791 * This value is stored in the resource data for the locale as a one-to-four-digit
792 * hexadecimal number. If the resource is missing, in the wrong format, or
793 * there is no Windows LCID value that corresponds to this locale, returns 0.
794 * @stable ICU 2.0
795 */
796 uint32_t getLCID() const;
797
798 /**
799 * Returns whether this locale's script is written right-to-left.
800 * If there is no script subtag, then the likely script is used, see uloc_addLikelySubtags().
801 * If no likely script is known, then false is returned.
802 *
803 * A script is right-to-left according to the CLDR script metadata
804 * which corresponds to whether the script's letters have Bidi_Class=R or AL.
805 *
806 * Returns true for "ar" and "en-Hebr", false for "zh" and "fa-Cyrl".
807 *
808 * @return true if the locale's script is written right-to-left
809 * @stable ICU 54
810 */
811 UBool isRightToLeft() const;
812
813 /**
814 * Fills in "dispLang" with the name of this locale's language in a format suitable for
815 * user display in the default locale. For example, if the locale's language code is
816 * "fr" and the default locale's language code is "en", this function would set
817 * dispLang to "French".
818 * @param dispLang Receives the language's display name.
819 * @return A reference to "dispLang".
820 * @stable ICU 2.0
821 */
822 UnicodeString& getDisplayLanguage(UnicodeString& dispLang) const;
823
824 /**
825 * Fills in "dispLang" with the name of this locale's language in a format suitable for
826 * user display in the locale specified by "displayLocale". For example, if the locale's
827 * language code is "en" and displayLocale's language code is "fr", this function would set
828 * dispLang to "Anglais".
829 * @param displayLocale Specifies the locale to be used to display the name. In other words,
830 * if the locale's language code is "en", passing Locale::getFrench() for
831 * displayLocale would result in "Anglais", while passing Locale::getGerman()
832 * for displayLocale would result in "Englisch".
833 * @param dispLang Receives the language's display name.
834 * @return A reference to "dispLang".
835 * @stable ICU 2.0
836 */
837 UnicodeString& getDisplayLanguage( const Locale& displayLocale,
838 UnicodeString& dispLang) const;
839
840 /**
841 * Fills in "dispScript" with the name of this locale's script in a format suitable
842 * for user display in the default locale. For example, if the locale's script code
843 * is "LATN" and the default locale's language code is "en", this function would set
844 * dispScript to "Latin".
845 * @param dispScript Receives the scripts's display name.
846 * @return A reference to "dispScript".
847 * @stable ICU 2.8
848 */
849 UnicodeString& getDisplayScript( UnicodeString& dispScript) const;
850
851 /**
852 * Fills in "dispScript" with the name of this locale's country in a format suitable
853 * for user display in the locale specified by "displayLocale". For example, if the locale's
854 * script code is "LATN" and displayLocale's language code is "en", this function would set
855 * dispScript to "Latin".
856 * @param displayLocale Specifies the locale to be used to display the name. In other
857 * words, if the locale's script code is "LATN", passing
858 * Locale::getFrench() for displayLocale would result in "", while
859 * passing Locale::getGerman() for displayLocale would result in
860 * "".
861 * @param dispScript Receives the scripts's display name.
862 * @return A reference to "dispScript".
863 * @stable ICU 2.8
864 */
865 UnicodeString& getDisplayScript( const Locale& displayLocale,
866 UnicodeString& dispScript) const;
867
868 /**
869 * Fills in "dispCountry" with the name of this locale's country in a format suitable
870 * for user display in the default locale. For example, if the locale's country code
871 * is "FR" and the default locale's language code is "en", this function would set
872 * dispCountry to "France".
873 * @param dispCountry Receives the country's display name.
874 * @return A reference to "dispCountry".
875 * @stable ICU 2.0
876 */
877 UnicodeString& getDisplayCountry( UnicodeString& dispCountry) const;
878
879 /**
880 * Fills in "dispCountry" with the name of this locale's country in a format suitable
881 * for user display in the locale specified by "displayLocale". For example, if the locale's
882 * country code is "US" and displayLocale's language code is "fr", this function would set
883 * dispCountry to "États-Unis".
884 * @param displayLocale Specifies the locale to be used to display the name. In other
885 * words, if the locale's country code is "US", passing
886 * Locale::getFrench() for displayLocale would result in "États-Unis", while
887 * passing Locale::getGerman() for displayLocale would result in
888 * "Vereinigte Staaten".
889 * @param dispCountry Receives the country's display name.
890 * @return A reference to "dispCountry".
891 * @stable ICU 2.0
892 */
893 UnicodeString& getDisplayCountry( const Locale& displayLocale,
894 UnicodeString& dispCountry) const;
895
896 /**
897 * Fills in "dispVar" with the name of this locale's variant code in a format suitable
898 * for user display in the default locale.
899 * @param dispVar Receives the variant's name.
900 * @return A reference to "dispVar".
901 * @stable ICU 2.0
902 */
903 UnicodeString& getDisplayVariant( UnicodeString& dispVar) const;
904
905 /**
906 * Fills in "dispVar" with the name of this locale's variant code in a format
907 * suitable for user display in the locale specified by "displayLocale".
908 * @param displayLocale Specifies the locale to be used to display the name.
909 * @param dispVar Receives the variant's display name.
910 * @return A reference to "dispVar".
911 * @stable ICU 2.0
912 */
913 UnicodeString& getDisplayVariant( const Locale& displayLocale,
914 UnicodeString& dispVar) const;
915
916 /**
917 * Fills in "name" with the name of this locale in a format suitable for user display
918 * in the default locale. This function uses getDisplayLanguage(), getDisplayCountry(),
919 * and getDisplayVariant() to do its work, and outputs the display name in the format
920 * "language (country[,variant])". For example, if the default locale is en_US, then
921 * fr_FR's display name would be "French (France)", and es_MX_Traditional's display name
922 * would be "Spanish (Mexico,Traditional)".
923 * @param name Receives the locale's display name.
924 * @return A reference to "name".
925 * @stable ICU 2.0
926 */
927 UnicodeString& getDisplayName( UnicodeString& name) const;
928
929 /**
930 * Fills in "name" with the name of this locale in a format suitable for user display
931 * in the locale specified by "displayLocale". This function uses getDisplayLanguage(),
932 * getDisplayCountry(), and getDisplayVariant() to do its work, and outputs the display
933 * name in the format "language (country[,variant])". For example, if displayLocale is
934 * fr_FR, then en_US's display name would be "Anglais (États-Unis)", and no_NO_NY's
935 * display name would be "norvégien (Norvège,NY)".
936 * @param displayLocale Specifies the locale to be used to display the name.
937 * @param name Receives the locale's display name.
938 * @return A reference to "name".
939 * @stable ICU 2.0
940 */
941 UnicodeString& getDisplayName( const Locale& displayLocale,
942 UnicodeString& name) const;
943
944 /**
945 * Generates a hash code for the locale.
946 * @stable ICU 2.0
947 */
948 int32_t hashCode() const;
949
950 /**
951 * Sets the locale to bogus
952 * A bogus locale represents a non-existing locale associated
953 * with services that can be instantiated from non-locale data
954 * in addition to locale (for example, collation can be
955 * instantiated from a locale and from a rule set).
956 * @stable ICU 2.1
957 */
958 void setToBogus();
959
960 /**
961 * Gets the bogus state. Locale object can be bogus if it doesn't exist
962 * @return false if it is a real locale, true if it is a bogus locale
963 * @stable ICU 2.1
964 */
965 inline UBool isBogus() const;
966
967 /**
968 * Returns a list of all installed locales.
969 * @param count Receives the number of locales in the list.
970 * @return A pointer to an array of Locale objects. This array is the list
971 * of all locales with installed resource files. The called does NOT
972 * get ownership of this list, and must NOT delete it.
973 * @stable ICU 2.0
974 */
975 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
976
977 /**
978 * Gets a list of all available 2-letter country codes defined in ISO 3166. This is a
979 * pointer to an array of pointers to arrays of char. All of these pointers are
980 * owned by ICU-- do not delete them, and do not write through them. The array is
981 * terminated with a null pointer.
982 * @return a list of all available country codes
983 * @stable ICU 2.0
984 */
985 static const char* const* U_EXPORT2 getISOCountries();
986
987 /**
988 * Returns a list of all unique language codes defined in ISO 639.
989 * They can be 2 or 3 letter codes, as defined by
990 * <a href="https://www.ietf.org/rfc/bcp/bcp47.html#section-2.2.1">
991 * BCP 47, section 2.2.1</a>. This is a pointer
992 * to an array of pointers to arrays of char. All of these pointers are owned
993 * by ICU-- do not delete them, and do not write through them. The array is
994 * terminated with a null pointer.
995 * @return a list of all available language codes
996 * @stable ICU 2.0
997 */
998 static const char* const* U_EXPORT2 getISOLanguages();
999
1000 /**
1001 * ICU "poor man's RTTI", returns a UClassID for this class.
1002 *
1003 * @stable ICU 2.2
1004 */
1005 static UClassID U_EXPORT2 getStaticClassID();
1006
1007 /**
1008 * ICU "poor man's RTTI", returns a UClassID for the actual class.
1009 *
1010 * @stable ICU 2.2
1011 */
1012 virtual UClassID getDynamicClassID() const override;
1013
1014 /**
1015 * A Locale iterator interface similar to a Java Iterator<Locale>.
1016 * @stable ICU 65
1017 */
1018 class U_COMMON_API Iterator /* not : public UObject because this is an interface/mixin class */ {
1019 public:
1020 /** @stable ICU 65 */
1021 virtual ~Iterator();
1022
1023 /**
1024 * @return true if next() can be called again.
1025 * @stable ICU 65
1026 */
1027 virtual UBool hasNext() const = 0;
1028
1029 /**
1030 * @return the next locale.
1031 * @stable ICU 65
1032 */
1033 virtual const Locale &next() = 0;
1034 };
1035
1036 /**
1037 * A generic Locale iterator implementation over Locale input iterators.
1038 * @stable ICU 65
1039 */
1040 template<typename Iter>
1041 class RangeIterator : public Iterator, public UMemory {
1042 public:
1043 /**
1044 * Constructs an iterator from a begin/end range.
1045 * Each of the iterator parameter values must be an
1046 * input iterator whose value is convertible to const Locale &.
1047 *
1048 * @param begin Start of range.
1049 * @param end Exclusive end of range.
1050 * @stable ICU 65
1051 */
RangeIterator(Iter begin,Iter end)1052 RangeIterator(Iter begin, Iter end) : it_(begin), end_(end) {}
1053
1054 /**
1055 * @return true if next() can be called again.
1056 * @stable ICU 65
1057 */
hasNext()1058 UBool hasNext() const override { return it_ != end_; }
1059
1060 /**
1061 * @return the next locale.
1062 * @stable ICU 65
1063 */
next()1064 const Locale &next() override { return *it_++; }
1065
1066 private:
1067 Iter it_;
1068 const Iter end_;
1069 };
1070
1071 /**
1072 * A generic Locale iterator implementation over Locale input iterators.
1073 * Calls the converter to convert each *begin to a const Locale &.
1074 * @stable ICU 65
1075 */
1076 template<typename Iter, typename Conv>
1077 class ConvertingIterator : public Iterator, public UMemory {
1078 public:
1079 /**
1080 * Constructs an iterator from a begin/end range.
1081 * Each of the iterator parameter values must be an
1082 * input iterator whose value the converter converts to const Locale &.
1083 *
1084 * @param begin Start of range.
1085 * @param end Exclusive end of range.
1086 * @param converter Converter from *begin to const Locale & or compatible.
1087 * @stable ICU 65
1088 */
ConvertingIterator(Iter begin,Iter end,Conv converter)1089 ConvertingIterator(Iter begin, Iter end, Conv converter) :
1090 it_(begin), end_(end), converter_(converter) {}
1091
1092 /**
1093 * @return true if next() can be called again.
1094 * @stable ICU 65
1095 */
hasNext()1096 UBool hasNext() const override { return it_ != end_; }
1097
1098 /**
1099 * @return the next locale.
1100 * @stable ICU 65
1101 */
next()1102 const Locale &next() override { return converter_(*it_++); }
1103
1104 private:
1105 Iter it_;
1106 const Iter end_;
1107 Conv converter_;
1108 };
1109
1110 protected: /* only protected for testing purposes. DO NOT USE. */
1111 #ifndef U_HIDE_INTERNAL_API
1112 /**
1113 * Set this from a single POSIX style locale string.
1114 * @internal
1115 */
1116 void setFromPOSIXID(const char *posixID);
1117 /**
1118 * Minimize the subtags for this Locale, per the algorithm described
1119 * @param favorScript favor to keep script if true, to keep region if false.
1120 * @param status error information if maximizing this Locale failed.
1121 * If this Locale is not well-formed, the error code is
1122 * U_ILLEGAL_ARGUMENT_ERROR.
1123 * @internal
1124 */
1125 void minimizeSubtags(bool favorScript, UErrorCode& status);
1126 #endif /* U_HIDE_INTERNAL_API */
1127
1128 private:
1129 /**
1130 * Initialize the locale object with a new name.
1131 * Was deprecated - used in implementation - moved internal
1132 *
1133 * @param cLocaleID The new locale name.
1134 * @param canonicalize whether to call uloc_canonicalize on cLocaleID
1135 */
1136 Locale& init(const char* cLocaleID, UBool canonicalize);
1137
1138 /*
1139 * Internal constructor to allow construction of a locale object with
1140 * NO side effects. (Default constructor tries to get
1141 * the default locale.)
1142 */
1143 enum ELocaleType {
1144 eBOGUS
1145 };
1146 Locale(ELocaleType);
1147
1148 /**
1149 * Initialize the locale cache for commonly used locales
1150 */
1151 static Locale* getLocaleCache();
1152
1153 char language[ULOC_LANG_CAPACITY];
1154 char script[ULOC_SCRIPT_CAPACITY];
1155 char country[ULOC_COUNTRY_CAPACITY];
1156 int32_t variantBegin;
1157 char* fullName;
1158 char fullNameBuffer[ULOC_FULLNAME_CAPACITY];
1159 // name without keywords
1160 char* baseName;
1161 void initBaseName(UErrorCode& status);
1162
1163 UBool fIsBogus;
1164
1165 static const Locale &getLocale(int locid);
1166
1167 /**
1168 * A friend to allow the default locale to be set by either the C or C++ API.
1169 * @internal (private)
1170 */
1171 friend Locale *locale_set_default_internal(const char *, UErrorCode& status);
1172
1173 /**
1174 * @internal (private)
1175 */
1176 friend void U_CALLCONV locale_available_init();
1177 };
1178
1179 inline bool
1180 Locale::operator!=(const Locale& other) const
1181 {
1182 return !operator==(other);
1183 }
1184
1185 template<typename StringClass> inline StringClass
toLanguageTag(UErrorCode & status)1186 Locale::toLanguageTag(UErrorCode& status) const
1187 {
1188 if (U_FAILURE(status)) { return {}; }
1189 StringClass result;
1190 StringByteSink<StringClass> sink(&result);
1191 toLanguageTag(sink, status);
1192 return result;
1193 }
1194
1195 inline const char *
getCountry()1196 Locale::getCountry() const
1197 {
1198 return country;
1199 }
1200
1201 inline const char *
getLanguage()1202 Locale::getLanguage() const
1203 {
1204 return language;
1205 }
1206
1207 inline const char *
getScript()1208 Locale::getScript() const
1209 {
1210 return script;
1211 }
1212
1213 inline const char *
getVariant()1214 Locale::getVariant() const
1215 {
1216 return fIsBogus ? "" : &baseName[variantBegin];
1217 }
1218
1219 inline const char *
getName()1220 Locale::getName() const
1221 {
1222 return fullName;
1223 }
1224
1225 template<typename StringClass, typename OutputIterator> inline void
getKeywords(OutputIterator iterator,UErrorCode & status)1226 Locale::getKeywords(OutputIterator iterator, UErrorCode& status) const
1227 {
1228 if (U_FAILURE(status)) { return; }
1229 LocalPointer<StringEnumeration> keys(createKeywords(status));
1230 if (U_FAILURE(status) || keys.isNull()) {
1231 return;
1232 }
1233 for (;;) {
1234 int32_t resultLength;
1235 const char* buffer = keys->next(&resultLength, status);
1236 if (U_FAILURE(status) || buffer == nullptr) {
1237 return;
1238 }
1239 *iterator++ = StringClass(buffer, resultLength);
1240 }
1241 }
1242
1243 template<typename StringClass, typename OutputIterator> inline void
getUnicodeKeywords(OutputIterator iterator,UErrorCode & status)1244 Locale::getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const
1245 {
1246 if (U_FAILURE(status)) { return; }
1247 LocalPointer<StringEnumeration> keys(createUnicodeKeywords(status));
1248 if (U_FAILURE(status) || keys.isNull()) {
1249 return;
1250 }
1251 for (;;) {
1252 int32_t resultLength;
1253 const char* buffer = keys->next(&resultLength, status);
1254 if (U_FAILURE(status) || buffer == nullptr) {
1255 return;
1256 }
1257 *iterator++ = StringClass(buffer, resultLength);
1258 }
1259 }
1260
1261 template<typename StringClass> inline StringClass
getKeywordValue(StringPiece keywordName,UErrorCode & status)1262 Locale::getKeywordValue(StringPiece keywordName, UErrorCode& status) const
1263 {
1264 if (U_FAILURE(status)) { return {}; }
1265 StringClass result;
1266 StringByteSink<StringClass> sink(&result);
1267 getKeywordValue(keywordName, sink, status);
1268 return result;
1269 }
1270
1271 template<typename StringClass> inline StringClass
getUnicodeKeywordValue(StringPiece keywordName,UErrorCode & status)1272 Locale::getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const
1273 {
1274 if (U_FAILURE(status)) { return {}; }
1275 StringClass result;
1276 StringByteSink<StringClass> sink(&result);
1277 getUnicodeKeywordValue(keywordName, sink, status);
1278 return result;
1279 }
1280
1281 inline UBool
isBogus()1282 Locale::isBogus() const {
1283 return fIsBogus;
1284 }
1285
1286 U_NAMESPACE_END
1287
1288 #endif /* U_SHOW_CPLUSPLUS_API */
1289
1290 #endif
1291