ICU 75.1  75.1
locid.h
Go to the documentation of this file.
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 
51 U_NAMESPACE_BEGIN
52 
53 // Forward Declarations
56 class StringEnumeration;
57 class UnicodeString;
58 
195 class U_COMMON_API Locale : public UObject {
196 public:
198  static const Locale& U_EXPORT2 getRoot();
200  static const Locale& U_EXPORT2 getEnglish();
202  static const Locale& U_EXPORT2 getFrench();
204  static const Locale& U_EXPORT2 getGerman();
206  static const Locale& U_EXPORT2 getItalian();
208  static const Locale& U_EXPORT2 getJapanese();
210  static const Locale& U_EXPORT2 getKorean();
212  static const Locale& U_EXPORT2 getChinese();
214  static const Locale& U_EXPORT2 getSimplifiedChinese();
216  static const Locale& U_EXPORT2 getTraditionalChinese();
217 
219  static const Locale& U_EXPORT2 getFrance();
221  static const Locale& U_EXPORT2 getGermany();
223  static const Locale& U_EXPORT2 getItaly();
225  static const Locale& U_EXPORT2 getJapan();
227  static const Locale& U_EXPORT2 getKorea();
229  static const Locale& U_EXPORT2 getChina();
231  static const Locale& U_EXPORT2 getPRC();
233  static const Locale& U_EXPORT2 getTaiwan();
235  static const Locale& U_EXPORT2 getUK();
237  static const Locale& U_EXPORT2 getUS();
239  static const Locale& U_EXPORT2 getCanada();
241  static const Locale& U_EXPORT2 getCanadaFrench();
242 
251 
276  Locale(const char* language,
277  const char* country = nullptr,
278  const char* variant = nullptr,
279  const char* keywordsAndValues = nullptr);
280 
287  Locale(const Locale& other);
288 
296  Locale(Locale&& other) noexcept;
297 
302  virtual ~Locale() ;
303 
311  Locale& operator=(const Locale& other);
312 
322  Locale& operator=(Locale&& other) noexcept;
323 
331  bool operator==(const Locale& other) const;
332 
341  inline bool operator!=(const Locale& other) const;
342 
354  Locale *clone() const;
355 
356 #ifndef U_HIDE_SYSTEM_API
372  static const Locale& U_EXPORT2 getDefault();
373 
386  static void U_EXPORT2 setDefault(const Locale& newLocale,
387  UErrorCode& success);
388 #endif /* U_HIDE_SYSTEM_API */
389 
411  static Locale U_EXPORT2 forLanguageTag(StringPiece tag, UErrorCode& status);
412 
426  void toLanguageTag(ByteSink& sink, UErrorCode& status) const;
427 
438  template<typename StringClass>
439  inline StringClass toLanguageTag(UErrorCode& status) const;
440 
450  static Locale U_EXPORT2 createFromName(const char *name);
451 
460  static Locale U_EXPORT2 createCanonical(const char* name);
461 
467  inline const char * getLanguage( ) const;
468 
476  inline const char * getScript( ) const;
477 
483  inline const char * getCountry( ) const;
484 
490  inline const char * getVariant( ) const;
491 
500  inline const char * getName() const;
501 
509  const char * getBaseName() const;
510 
541 
572 
579  void canonicalize(UErrorCode& status);
580 
591 
602 
614  template<typename StringClass, typename OutputIterator>
615  inline void getKeywords(OutputIterator iterator, UErrorCode& status) const;
616 
628  template<typename StringClass, typename OutputIterator>
629  inline void getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const;
630 
647  int32_t getKeywordValue(const char* keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const;
648 
662  void getKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
663 
677  template<typename StringClass>
678  inline StringClass getKeywordValue(StringPiece keywordName, UErrorCode& status) const;
679 
693  void getUnicodeKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
694 
708  template<typename StringClass>
709  inline StringClass getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const;
710 
730  void setKeywordValue(const char* keywordName, const char* keywordValue, UErrorCode &status);
731 
750  void setKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
751 
770  void setUnicodeKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
771 
778  const char * getISO3Language() const;
779 
785  const char * getISO3Country() const;
786 
794  uint32_t getLCID() const;
795 
810 
821 
835  UnicodeString& getDisplayLanguage( const Locale& displayLocale,
836  UnicodeString& dispLang) const;
837 
848 
863  UnicodeString& getDisplayScript( const Locale& displayLocale,
864  UnicodeString& dispScript) const;
865 
876 
891  UnicodeString& getDisplayCountry( const Locale& displayLocale,
892  UnicodeString& dispCountry) const;
893 
902 
911  UnicodeString& getDisplayVariant( const Locale& displayLocale,
912  UnicodeString& dispVar) const;
913 
926 
939  UnicodeString& getDisplayName( const Locale& displayLocale,
940  UnicodeString& name) const;
941 
946  int32_t hashCode() const;
947 
956  void setToBogus();
957 
963  inline UBool isBogus() const;
964 
973  static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
974 
983  static const char* const* U_EXPORT2 getISOCountries();
984 
996  static const char* const* U_EXPORT2 getISOLanguages();
997 
1003  static UClassID U_EXPORT2 getStaticClassID();
1004 
1010  virtual UClassID getDynamicClassID() const override;
1011 
1016  class U_COMMON_API Iterator /* not : public UObject because this is an interface/mixin class */ {
1017  public:
1019  virtual ~Iterator();
1020 
1025  virtual UBool hasNext() const = 0;
1026 
1031  virtual const Locale &next() = 0;
1032  };
1033 
1038  template<typename Iter>
1039  class RangeIterator : public Iterator, public UMemory {
1040  public:
1050  RangeIterator(Iter begin, Iter end) : it_(begin), end_(end) {}
1051 
1056  UBool hasNext() const override { return it_ != end_; }
1057 
1062  const Locale &next() override { return *it_++; }
1063 
1064  private:
1065  Iter it_;
1066  const Iter end_;
1067  };
1068 
1074  template<typename Iter, typename Conv>
1075  class ConvertingIterator : public Iterator, public UMemory {
1076  public:
1087  ConvertingIterator(Iter begin, Iter end, Conv converter) :
1088  it_(begin), end_(end), converter_(converter) {}
1089 
1094  UBool hasNext() const override { return it_ != end_; }
1095 
1100  const Locale &next() override { return converter_(*it_++); }
1101 
1102  private:
1103  Iter it_;
1104  const Iter end_;
1105  Conv converter_;
1106  };
1107 
1108 protected: /* only protected for testing purposes. DO NOT USE. */
1109 #ifndef U_HIDE_INTERNAL_API
1114  void setFromPOSIXID(const char *posixID);
1123  void minimizeSubtags(bool favorScript, UErrorCode& status);
1124 #endif /* U_HIDE_INTERNAL_API */
1125 
1126 private:
1134  Locale& init(const char* cLocaleID, UBool canonicalize);
1135 
1136  /*
1137  * Internal constructor to allow construction of a locale object with
1138  * NO side effects. (Default constructor tries to get
1139  * the default locale.)
1140  */
1141  enum ELocaleType {
1142  eBOGUS
1143  };
1144  Locale(ELocaleType);
1145 
1149  static Locale* getLocaleCache();
1150 
1151  char language[ULOC_LANG_CAPACITY];
1152  char script[ULOC_SCRIPT_CAPACITY];
1153  char country[ULOC_COUNTRY_CAPACITY];
1154  int32_t variantBegin;
1155  char* fullName;
1156  char fullNameBuffer[ULOC_FULLNAME_CAPACITY];
1157  // name without keywords
1158  char* baseName;
1159  void initBaseName(UErrorCode& status);
1160 
1161  UBool fIsBogus;
1162 
1163  static const Locale &getLocale(int locid);
1164 
1169  friend Locale *locale_set_default_internal(const char *, UErrorCode& status);
1170 
1175 };
1176 
1177 inline bool
1178 Locale::operator!=(const Locale& other) const
1179 {
1180  return !operator==(other);
1181 }
1182 
1183 template<typename StringClass> inline StringClass
1184 Locale::toLanguageTag(UErrorCode& status) const
1185 {
1186  if (U_FAILURE(status)) { return {}; }
1187  StringClass result;
1188  StringByteSink<StringClass> sink(&result);
1189  toLanguageTag(sink, status);
1190  return result;
1191 }
1192 
1193 inline const char *
1194 Locale::getCountry() const
1195 {
1196  return country;
1197 }
1198 
1199 inline const char *
1200 Locale::getLanguage() const
1201 {
1202  return language;
1203 }
1204 
1205 inline const char *
1206 Locale::getScript() const
1207 {
1208  return script;
1209 }
1210 
1211 inline const char *
1212 Locale::getVariant() const
1213 {
1214  return fIsBogus ? "" : &baseName[variantBegin];
1215 }
1216 
1217 inline const char *
1218 Locale::getName() const
1219 {
1220  return fullName;
1221 }
1222 
1223 template<typename StringClass, typename OutputIterator> inline void
1224 Locale::getKeywords(OutputIterator iterator, UErrorCode& status) const
1225 {
1226  if (U_FAILURE(status)) { return; }
1227  LocalPointer<StringEnumeration> keys(createKeywords(status));
1228  if (U_FAILURE(status) || keys.isNull()) {
1229  return;
1230  }
1231  for (;;) {
1232  int32_t resultLength;
1233  const char* buffer = keys->next(&resultLength, status);
1234  if (U_FAILURE(status) || buffer == nullptr) {
1235  return;
1236  }
1237  *iterator++ = StringClass(buffer, resultLength);
1238  }
1239 }
1240 
1241 template<typename StringClass, typename OutputIterator> inline void
1242 Locale::getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const
1243 {
1244  if (U_FAILURE(status)) { return; }
1245  LocalPointer<StringEnumeration> keys(createUnicodeKeywords(status));
1246  if (U_FAILURE(status) || keys.isNull()) {
1247  return;
1248  }
1249  for (;;) {
1250  int32_t resultLength;
1251  const char* buffer = keys->next(&resultLength, status);
1252  if (U_FAILURE(status) || buffer == nullptr) {
1253  return;
1254  }
1255  *iterator++ = StringClass(buffer, resultLength);
1256  }
1257 }
1258 
1259 template<typename StringClass> inline StringClass
1260 Locale::getKeywordValue(StringPiece keywordName, UErrorCode& status) const
1261 {
1262  if (U_FAILURE(status)) { return {}; }
1263  StringClass result;
1264  StringByteSink<StringClass> sink(&result);
1265  getKeywordValue(keywordName, sink, status);
1266  return result;
1267 }
1268 
1269 template<typename StringClass> inline StringClass
1270 Locale::getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const
1271 {
1272  if (U_FAILURE(status)) { return {}; }
1273  StringClass result;
1274  StringByteSink<StringClass> sink(&result);
1275  getUnicodeKeywordValue(keywordName, sink, status);
1276  return result;
1277 }
1278 
1279 inline UBool
1280 Locale::isBogus() const {
1281  return fIsBogus;
1282 }
1283 
1284 U_NAMESPACE_END
1285 
1286 #endif /* U_SHOW_CPLUSPLUS_API */
1287 
1288 #endif
C++ API: Interface for writing bytes, and implementation classes.
A ByteSink can be filled with bytes.
Definition: bytestream.h:53
UBool isNull() const
nullptr check.
Definition: localpointer.h:94
"Smart pointer" class, deletes objects via the standard C++ delete operator.
Definition: localpointer.h:191
A generic Locale iterator implementation over Locale input iterators.
Definition: locid.h:1075
UBool hasNext() const override
Definition: locid.h:1094
ConvertingIterator(Iter begin, Iter end, Conv converter)
Constructs an iterator from a begin/end range.
Definition: locid.h:1087
const Locale & next() override
Definition: locid.h:1100
A Locale iterator interface similar to a Java Iterator<Locale>.
Definition: locid.h:1016
virtual UBool hasNext() const =0
virtual const Locale & next()=0
A generic Locale iterator implementation over Locale input iterators.
Definition: locid.h:1039
RangeIterator(Iter begin, Iter end)
Constructs an iterator from a begin/end range.
Definition: locid.h:1050
UBool hasNext() const override
Definition: locid.h:1056
const Locale & next() override
Definition: locid.h:1062
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195
static const Locale & getGerman()
Useful constant for this language.
void minimizeSubtags(UErrorCode &status)
Minimize the subtags for this Locale, per the algorithm described in the following CLDR technical rep...
static const Locale * getAvailableLocales(int32_t &count)
Returns a list of all installed locales.
void minimizeSubtags(bool favorScript, UErrorCode &status)
Minimize the subtags for this Locale, per the algorithm described.
static const char *const * getISOCountries()
Gets a list of all available 2-letter country codes defined in ISO 3166.
static Locale createFromName(const char *name)
Creates a locale which has had minimal canonicalization as per uloc_getName().
static const Locale & getChina()
Useful constant for this country/region.
friend void locale_available_init()
friend Locale * locale_set_default_internal(const char *, UErrorCode &status)
A friend to allow the default locale to be set by either the C or C++ API.
static Locale createCanonical(const char *name)
Creates a locale from the given string after canonicalizing the string according to CLDR by calling u...
UnicodeString & getDisplayCountry(const Locale &displayLocale, UnicodeString &dispCountry) const
Fills in "dispCountry" with the name of this locale's country in a format suitable for user display i...
static UClassID getStaticClassID()
ICU "poor man's RTTI", returns a UClassID for this class.
Locale()
Construct a default locale object, a Locale for the default locale ID.
Locale * clone() const
Clone this object.
void setKeywordValue(const char *keywordName, const char *keywordValue, UErrorCode &status)
Sets or removes the value for a keyword.
UnicodeString & getDisplayCountry(UnicodeString &dispCountry) const
Fills in "dispCountry" with the name of this locale's country in a format suitable for user display i...
static const Locale & getFrench()
Useful constant for this language.
Locale & operator=(Locale &&other) noexcept
Move assignment operator; might leave source in bogus state.
UnicodeString & getDisplayLanguage(const Locale &displayLocale, UnicodeString &dispLang) const
Fills in "dispLang" with the name of this locale's language in a format suitable for user display in ...
Locale(const char *language, const char *country=nullptr, const char *variant=nullptr, const char *keywordsAndValues=nullptr)
Construct a locale from language, country, variant.
static const Locale & getChinese()
Useful constant for this language.
static const char *const * getISOLanguages()
Returns a list of all unique language codes defined in ISO 639.
static const Locale & getItalian()
Useful constant for this language.
const char * getISO3Country() const
Fills in "name" with the locale's three-letter ISO-3166 country code.
static const Locale & getUS()
Useful constant for this country/region.
static const Locale & getPRC()
Useful constant for this country/region.
UnicodeString & getDisplayName(UnicodeString &name) const
Fills in "name" with the name of this locale in a format suitable for user display in the default loc...
virtual ~Locale()
Destructor.
int32_t getKeywordValue(const char *keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const
Gets the value for a keyword.
static void setDefault(const Locale &newLocale, UErrorCode &success)
Sets the default.
static const Locale & getTraditionalChinese()
Useful constant for this language.
static const Locale & getEnglish()
Useful constant for this language.
bool operator==(const Locale &other) const
Checks if two locale keys are the same.
StringEnumeration * createKeywords(UErrorCode &status) const
Gets the list of keywords for the specified locale.
static const Locale & getCanadaFrench()
Useful constant for this country/region.
static const Locale & getItaly()
Useful constant for this country/region.
static const Locale & getRoot()
Useful constant for the Root locale.
static const Locale & getKorea()
Useful constant for this country/region.
UnicodeString & getDisplayLanguage(UnicodeString &dispLang) const
Fills in "dispLang" with the name of this locale's language in a format suitable for user display in ...
void setKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode &status)
Sets or removes the value for a keyword.
void setUnicodeKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode &status)
Sets or removes the Unicode value for a Unicode keyword.
StringEnumeration * createUnicodeKeywords(UErrorCode &status) const
Gets the list of Unicode keywords for the specified locale.
void toLanguageTag(ByteSink &sink, UErrorCode &status) const
Returns a well-formed language tag for this Locale.
const char * getBaseName() const
Returns the programmatic name of the entire locale as getName() would return, but without keywords.
UnicodeString & getDisplayName(const Locale &displayLocale, UnicodeString &name) const
Fills in "name" with the name of this locale in a format suitable for user display in the locale spec...
void setToBogus()
Sets the locale to bogus A bogus locale represents a non-existing locale associated with services tha...
void addLikelySubtags(UErrorCode &status)
Add the likely subtags for this Locale, per the algorithm described in the following CLDR technical r...
Locale & operator=(const Locale &other)
Replaces the entire contents of *this with the specified value.
static const Locale & getJapanese()
Useful constant for this language.
static const Locale & getUK()
Useful constant for this country/region.
void canonicalize(UErrorCode &status)
Canonicalize the locale ID of this object according to CLDR.
static const Locale & getKorean()
Useful constant for this language.
static const Locale & getJapan()
Useful constant for this country/region.
int32_t hashCode() const
Generates a hash code for the locale.
uint32_t getLCID() const
Returns the Windows LCID value corresponding to this locale.
Locale(const Locale &other)
Initializes a Locale object from another Locale object.
static const Locale & getGermany()
Useful constant for this country/region.
UnicodeString & getDisplayVariant(UnicodeString &dispVar) const
Fills in "dispVar" with the name of this locale's variant code in a format suitable for user display ...
const char * getISO3Language() const
returns the locale's three-letter language code, as specified in ISO draft standard ISO-639-2.
void getUnicodeKeywordValue(StringPiece keywordName, ByteSink &sink, UErrorCode &status) const
Gets the Unicode value for a Unicode keyword.
UnicodeString & getDisplayScript(const Locale &displayLocale, UnicodeString &dispScript) const
Fills in "dispScript" with the name of this locale's country in a format suitable for user display in...
UnicodeString & getDisplayScript(UnicodeString &dispScript) const
Fills in "dispScript" with the name of this locale's script in a format suitable for user display in ...
static const Locale & getSimplifiedChinese()
Useful constant for this language.
static const Locale & getCanada()
Useful constant for this country/region.
UBool isRightToLeft() const
Returns whether this locale's script is written right-to-left.
void setFromPOSIXID(const char *posixID)
Set this from a single POSIX style locale string.
static const Locale & getDefault()
Common methods of getting the current default Locale.
void getKeywordValue(StringPiece keywordName, ByteSink &sink, UErrorCode &status) const
Gets the value for a keyword.
UnicodeString & getDisplayVariant(const Locale &displayLocale, UnicodeString &dispVar) const
Fills in "dispVar" with the name of this locale's variant code in a format suitable for user display ...
static const Locale & getFrance()
Useful constant for this country/region.
virtual UClassID getDynamicClassID() const override
ICU "poor man's RTTI", returns a UClassID for the actual class.
static const Locale & getTaiwan()
Useful constant for this country/region.
static Locale forLanguageTag(StringPiece tag, UErrorCode &status)
Returns a Locale for the specified BCP47 language tag string.
Locale(Locale &&other) noexcept
Move constructor; might leave source in bogus state.
Implementation of ByteSink that writes to a "string".
Definition: bytestream.h:267
Base class for 'pure' C++ implementations of uenum api.
Definition: strenum.h:61
A string-like object that points to a sized piece of memory.
Definition: stringpiece.h:60
UMemory is the common ICU base class.
Definition: uobject.h:115
UObject is the common ICU "boilerplate" class.
Definition: uobject.h:223
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:296
C++ API: "Smart pointers" for use with and in ICU4C C++ code.
U_EXPORT UBool operator==(const StringPiece &x, const StringPiece &y)
Global operator == for StringPiece.
void locale_available_init()
bool operator!=(const StringPiece &x, const StringPiece &y)
Global operator != for StringPiece.
Definition: stringpiece.h:335
#define U_CALLCONV
Similar to U_CDECL_BEGIN/U_CDECL_END, this qualifier is necessary in callback function typedefs to ma...
Definition: platform.h:834
C API: Platform Utilities.
C++ API: String Enumeration.
C++ API: StringPiece: Read-only byte string wrapper class.
C API: Locale ID functionality similar to C++ class Locale.
#define ULOC_SCRIPT_CAPACITY
Useful constant for the maximum size of the script part of a locale ID (including the terminating NUL...
Definition: uloc.h:271
#define ULOC_COUNTRY_CAPACITY
Useful constant for the maximum size of the country part of a locale ID (including the terminating NU...
Definition: uloc.h:258
#define ULOC_LANG_CAPACITY
Useful constant for the maximum size of the language part of a locale ID.
Definition: uloc.h:251
#define ULOC_FULLNAME_CAPACITY
Useful constant for the maximum size of the whole locale ID (including the terminating NULL and all k...
Definition: uloc.h:264
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:247
C++ API: Common ICU base class UObject.
void * UClassID
UClassID is used to identify classes without using the compiler's RTTI.
Definition: uobject.h:96
Basic definitions for ICU, for both C and C++ APIs.
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
#define U_FAILURE(x)
Does the error code indicate a failure?
Definition: utypes.h:733
#define U_COMMON_API
Set to export library symbols from inside the common library, and to import them from outside.
Definition: utypes.h:300