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
51U_NAMESPACE_BEGIN
52
53// Forward Declarations
54void U_CALLCONV locale_available_init(); /**< @internal */
55
56class StringEnumeration;
57class 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 */
195class U_COMMON_API Locale : public UObject {
196public:
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 "&Eacute;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 "&Eacute;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 (&Eacute;tats-Unis)", and no_NO_NY's
934 * display name would be "norv&eacute;gien (Norv&egrave;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 * Gets a list of all available language codes defined in ISO 639. This is a pointer
988 * to an array of pointers to arrays of char. All of these pointers are owned
989 * by ICU-- do not delete them, and do not write through them. The array is
990 * terminated with a null pointer.
991 * @return a list of all available language codes
992 * @stable ICU 2.0
993 */
994 static const char* const* U_EXPORT2 getISOLanguages();
995
996 /**
997 * ICU "poor man's RTTI", returns a UClassID for this class.
998 *
999 * @stable ICU 2.2
1000 */
1001 static UClassID U_EXPORT2 getStaticClassID();
1002
1003 /**
1004 * ICU "poor man's RTTI", returns a UClassID for the actual class.
1005 *
1006 * @stable ICU 2.2
1007 */
1008 virtual UClassID getDynamicClassID() const override;
1009
1010 /**
1011 * A Locale iterator interface similar to a Java Iterator<Locale>.
1012 * @stable ICU 65
1013 */
1014 class U_COMMON_API Iterator /* not : public UObject because this is an interface/mixin class */ {
1015 public:
1016 /** @stable ICU 65 */
1017 virtual ~Iterator();
1018
1019 /**
1020 * @return true if next() can be called again.
1021 * @stable ICU 65
1022 */
1023 virtual UBool hasNext() const = 0;
1024
1025 /**
1026 * @return the next locale.
1027 * @stable ICU 65
1028 */
1029 virtual const Locale &next() = 0;
1030 };
1031
1032 /**
1033 * A generic Locale iterator implementation over Locale input iterators.
1034 * @stable ICU 65
1035 */
1036 template<typename Iter>
1037 class RangeIterator : public Iterator, public UMemory {
1038 public:
1039 /**
1040 * Constructs an iterator from a begin/end range.
1041 * Each of the iterator parameter values must be an
1042 * input iterator whose value is convertible to const Locale &.
1043 *
1044 * @param begin Start of range.
1045 * @param end Exclusive end of range.
1046 * @stable ICU 65
1047 */
1048 RangeIterator(Iter begin, Iter end) : it_(begin), end_(end) {}
1049
1050 /**
1051 * @return true if next() can be called again.
1052 * @stable ICU 65
1053 */
1054 UBool hasNext() const override { return it_ != end_; }
1055
1056 /**
1057 * @return the next locale.
1058 * @stable ICU 65
1059 */
1060 const Locale &next() override { return *it_++; }
1061
1062 private:
1063 Iter it_;
1064 const Iter end_;
1065 };
1066
1067 /**
1068 * A generic Locale iterator implementation over Locale input iterators.
1069 * Calls the converter to convert each *begin to a const Locale &.
1070 * @stable ICU 65
1071 */
1072 template<typename Iter, typename Conv>
1073 class ConvertingIterator : public Iterator, public UMemory {
1074 public:
1075 /**
1076 * Constructs an iterator from a begin/end range.
1077 * Each of the iterator parameter values must be an
1078 * input iterator whose value the converter converts to const Locale &.
1079 *
1080 * @param begin Start of range.
1081 * @param end Exclusive end of range.
1082 * @param converter Converter from *begin to const Locale & or compatible.
1083 * @stable ICU 65
1084 */
1085 ConvertingIterator(Iter begin, Iter end, Conv converter) :
1086 it_(begin), end_(end), converter_(converter) {}
1087
1088 /**
1089 * @return true if next() can be called again.
1090 * @stable ICU 65
1091 */
1092 UBool hasNext() const override { return it_ != end_; }
1093
1094 /**
1095 * @return the next locale.
1096 * @stable ICU 65
1097 */
1098 const Locale &next() override { return converter_(*it_++); }
1099
1100 private:
1101 Iter it_;
1102 const Iter end_;
1103 Conv converter_;
1104 };
1105
1106protected: /* only protected for testing purposes. DO NOT USE. */
1107#ifndef U_HIDE_INTERNAL_API
1108 /**
1109 * Set this from a single POSIX style locale string.
1110 * @internal
1111 */
1112 void setFromPOSIXID(const char *posixID);
1113#endif /* U_HIDE_INTERNAL_API */
1114
1115private:
1116 /**
1117 * Initialize the locale object with a new name.
1118 * Was deprecated - used in implementation - moved internal
1119 *
1120 * @param cLocaleID The new locale name.
1121 * @param canonicalize whether to call uloc_canonicalize on cLocaleID
1122 */
1123 Locale& init(const char* cLocaleID, UBool canonicalize);
1124
1125 /*
1126 * Internal constructor to allow construction of a locale object with
1127 * NO side effects. (Default constructor tries to get
1128 * the default locale.)
1129 */
1130 enum ELocaleType {
1131 eBOGUS
1132 };
1133 Locale(ELocaleType);
1134
1135 /**
1136 * Initialize the locale cache for commonly used locales
1137 */
1138 static Locale *getLocaleCache(void);
1139
1140 char language[ULOC_LANG_CAPACITY];
1141 char script[ULOC_SCRIPT_CAPACITY];
1142 char country[ULOC_COUNTRY_CAPACITY];
1143 int32_t variantBegin;
1144 char* fullName;
1145 char fullNameBuffer[ULOC_FULLNAME_CAPACITY];
1146 // name without keywords
1147 char* baseName;
1148 void initBaseName(UErrorCode& status);
1149
1150 UBool fIsBogus;
1151
1152 static const Locale &getLocale(int locid);
1153
1154 /**
1155 * A friend to allow the default locale to be set by either the C or C++ API.
1156 * @internal (private)
1157 */
1158 friend Locale *locale_set_default_internal(const char *, UErrorCode& status);
1159
1160 /**
1161 * @internal (private)
1162 */
1163 friend void U_CALLCONV locale_available_init();
1164};
1165
1166inline bool
1167Locale::operator!=(const Locale& other) const
1168{
1169 return !operator==(other);
1170}
1171
1172template<typename StringClass> inline StringClass
1173Locale::toLanguageTag(UErrorCode& status) const
1174{
1175 StringClass result;
1176 StringByteSink<StringClass> sink(&result);
1177 toLanguageTag(sink, status);
1178 return result;
1179}
1180
1181inline const char *
1182Locale::getCountry() const
1183{
1184 return country;
1185}
1186
1187inline const char *
1188Locale::getLanguage() const
1189{
1190 return language;
1191}
1192
1193inline const char *
1194Locale::getScript() const
1195{
1196 return script;
1197}
1198
1199inline const char *
1200Locale::getVariant() const
1201{
1202 return &baseName[variantBegin];
1203}
1204
1205inline const char *
1206Locale::getName() const
1207{
1208 return fullName;
1209}
1210
1211template<typename StringClass, typename OutputIterator> inline void
1212Locale::getKeywords(OutputIterator iterator, UErrorCode& status) const
1213{
1214 LocalPointer<StringEnumeration> keys(createKeywords(status));
1215 if (U_FAILURE(status) || keys.isNull()) {
1216 return;
1217 }
1218 for (;;) {
1219 int32_t resultLength;
1220 const char* buffer = keys->next(&resultLength, status);
1221 if (U_FAILURE(status) || buffer == nullptr) {
1222 return;
1223 }
1224 *iterator++ = StringClass(buffer, resultLength);
1225 }
1226}
1227
1228template<typename StringClass, typename OutputIterator> inline void
1229Locale::getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const
1230{
1231 LocalPointer<StringEnumeration> keys(createUnicodeKeywords(status));
1232 if (U_FAILURE(status) || keys.isNull()) {
1233 return;
1234 }
1235 for (;;) {
1236 int32_t resultLength;
1237 const char* buffer = keys->next(&resultLength, status);
1238 if (U_FAILURE(status) || buffer == nullptr) {
1239 return;
1240 }
1241 *iterator++ = StringClass(buffer, resultLength);
1242 }
1243}
1244
1245template<typename StringClass> inline StringClass
1246Locale::getKeywordValue(StringPiece keywordName, UErrorCode& status) const
1247{
1248 StringClass result;
1249 StringByteSink<StringClass> sink(&result);
1250 getKeywordValue(keywordName, sink, status);
1251 return result;
1252}
1253
1254template<typename StringClass> inline StringClass
1255Locale::getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const
1256{
1257 StringClass result;
1258 StringByteSink<StringClass> sink(&result);
1259 getUnicodeKeywordValue(keywordName, sink, status);
1260 return result;
1261}
1262
1263inline UBool
1264Locale::isBogus(void) const {
1265 return fIsBogus;
1266}
1267
1268U_NAMESPACE_END
1269
1270#endif /* U_SHOW_CPLUSPLUS_API */
1271
1272#endif
1273