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