ICU 68.2  68.2
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(void);
200  static const Locale &U_EXPORT2 getEnglish(void);
202  static const Locale &U_EXPORT2 getFrench(void);
204  static const Locale &U_EXPORT2 getGerman(void);
206  static const Locale &U_EXPORT2 getItalian(void);
208  static const Locale &U_EXPORT2 getJapanese(void);
210  static const Locale &U_EXPORT2 getKorean(void);
212  static const Locale &U_EXPORT2 getChinese(void);
214  static const Locale &U_EXPORT2 getSimplifiedChinese(void);
216  static const Locale &U_EXPORT2 getTraditionalChinese(void);
217 
219  static const Locale &U_EXPORT2 getFrance(void);
221  static const Locale &U_EXPORT2 getGermany(void);
223  static const Locale &U_EXPORT2 getItaly(void);
225  static const Locale &U_EXPORT2 getJapan(void);
227  static const Locale &U_EXPORT2 getKorea(void);
229  static const Locale &U_EXPORT2 getChina(void);
231  static const Locale &U_EXPORT2 getPRC(void);
233  static const Locale &U_EXPORT2 getTaiwan(void);
235  static const Locale &U_EXPORT2 getUK(void);
237  static const Locale &U_EXPORT2 getUS(void);
239  static const Locale &U_EXPORT2 getCanada(void);
241  static const Locale &U_EXPORT2 getCanadaFrench(void);
242 
243 
251  Locale();
252 
277  Locale( const char * language,
278  const char * country = 0,
279  const char * variant = 0,
280  const char * keywordsAndValues = 0);
281 
288  Locale(const Locale& other);
289 
297  Locale(Locale&& other) U_NOEXCEPT;
298 
303  virtual ~Locale() ;
304 
312  Locale& operator=(const Locale& other);
313 
323  Locale& operator=(Locale&& other) U_NOEXCEPT;
324 
332  UBool operator==(const Locale& other) const;
333 
342  inline UBool operator!=(const Locale& other) const;
343 
355  Locale *clone() const;
356 
357 #ifndef U_HIDE_SYSTEM_API
358 
373  static const Locale& U_EXPORT2 getDefault(void);
374 
387  static void U_EXPORT2 setDefault(const Locale& newLocale,
388  UErrorCode& success);
389 #endif /* U_HIDE_SYSTEM_API */
390 
412  static Locale U_EXPORT2 forLanguageTag(StringPiece tag, UErrorCode& status);
413 
427  void toLanguageTag(ByteSink& sink, UErrorCode& status) const;
428 
439  template<typename StringClass>
440  inline StringClass toLanguageTag(UErrorCode& status) const;
441 
451  static Locale U_EXPORT2 createFromName(const char *name);
452 
461  static Locale U_EXPORT2 createCanonical(const char* name);
462 
468  inline const char * getLanguage( ) const;
469 
477  inline const char * getScript( ) const;
478 
484  inline const char * getCountry( ) const;
485 
491  inline const char * getVariant( ) const;
492 
501  inline const char * getName() const;
502 
510  const char * getBaseName() const;
511 
541  void addLikelySubtags(UErrorCode& status);
542 
572  void minimizeSubtags(UErrorCode& status);
573 
574 #ifndef U_HIDE_DRAFT_API
575 
581  void canonicalize(UErrorCode& status);
582 #endif // U_HIDE_DRAFT_API
583 
593  StringEnumeration * createKeywords(UErrorCode &status) const;
594 
604  StringEnumeration * createUnicodeKeywords(UErrorCode &status) const;
605 
617  template<typename StringClass, typename OutputIterator>
618  inline void getKeywords(OutputIterator iterator, UErrorCode& status) const;
619 
631  template<typename StringClass, typename OutputIterator>
632  inline void getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const;
633 
650  int32_t getKeywordValue(const char* keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const;
651 
665  void getKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
666 
680  template<typename StringClass>
681  inline StringClass getKeywordValue(StringPiece keywordName, UErrorCode& status) const;
682 
696  void getUnicodeKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
697 
711  template<typename StringClass>
712  inline StringClass getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const;
713 
733  void setKeywordValue(const char* keywordName, const char* keywordValue, UErrorCode &status);
734 
753  void setKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
754 
773  void setUnicodeKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
774 
781  const char * getISO3Language() const;
782 
788  const char * getISO3Country() const;
789 
797  uint32_t getLCID(void) const;
798 
812  UBool isRightToLeft() const;
813 
823  UnicodeString& getDisplayLanguage(UnicodeString& dispLang) const;
824 
838  UnicodeString& getDisplayLanguage( const Locale& displayLocale,
839  UnicodeString& dispLang) const;
840 
850  UnicodeString& getDisplayScript( UnicodeString& dispScript) const;
851 
866  UnicodeString& getDisplayScript( const Locale& displayLocale,
867  UnicodeString& dispScript) const;
868 
878  UnicodeString& getDisplayCountry( UnicodeString& dispCountry) const;
879 
894  UnicodeString& getDisplayCountry( const Locale& displayLocale,
895  UnicodeString& dispCountry) const;
896 
904  UnicodeString& getDisplayVariant( UnicodeString& dispVar) const;
905 
914  UnicodeString& getDisplayVariant( const Locale& displayLocale,
915  UnicodeString& dispVar) const;
916 
928  UnicodeString& getDisplayName( UnicodeString& name) const;
929 
942  UnicodeString& getDisplayName( const Locale& displayLocale,
943  UnicodeString& name) const;
944 
949  int32_t hashCode(void) const;
950 
959  void setToBogus();
960 
966  inline UBool isBogus(void) const;
967 
976  static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
977 
986  static const char* const* U_EXPORT2 getISOCountries();
987 
996  static const char* const* U_EXPORT2 getISOLanguages();
997 
1003  static UClassID U_EXPORT2 getStaticClassID();
1004 
1010  virtual UClassID getDynamicClassID() const;
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
1110 
1114  void setFromPOSIXID(const char *posixID);
1115 #endif /* U_HIDE_INTERNAL_API */
1116 
1117 private:
1125  Locale& init(const char* cLocaleID, UBool canonicalize);
1126 
1127  /*
1128  * Internal constructor to allow construction of a locale object with
1129  * NO side effects. (Default constructor tries to get
1130  * the default locale.)
1131  */
1132  enum ELocaleType {
1133  eBOGUS
1134  };
1135  Locale(ELocaleType);
1136 
1140  static Locale *getLocaleCache(void);
1141 
1142  char language[ULOC_LANG_CAPACITY];
1143  char script[ULOC_SCRIPT_CAPACITY];
1144  char country[ULOC_COUNTRY_CAPACITY];
1145  int32_t variantBegin;
1146  char* fullName;
1147  char fullNameBuffer[ULOC_FULLNAME_CAPACITY];
1148  // name without keywords
1149  char* baseName;
1150  void initBaseName(UErrorCode& status);
1151 
1152  UBool fIsBogus;
1153 
1154  static const Locale &getLocale(int locid);
1155 
1160  friend Locale *locale_set_default_internal(const char *, UErrorCode& status);
1161 
1165  friend void U_CALLCONV locale_available_init();
1166 };
1167 
1168 inline UBool
1169 Locale::operator!=(const Locale& other) const
1170 {
1171  return !operator==(other);
1172 }
1173 
1174 template<typename StringClass> inline StringClass
1175 Locale::toLanguageTag(UErrorCode& status) const
1176 {
1177  StringClass result;
1178  StringByteSink<StringClass> sink(&result);
1179  toLanguageTag(sink, status);
1180  return result;
1181 }
1182 
1183 inline const char *
1184 Locale::getCountry() const
1185 {
1186  return country;
1187 }
1188 
1189 inline const char *
1190 Locale::getLanguage() const
1191 {
1192  return language;
1193 }
1194 
1195 inline const char *
1196 Locale::getScript() const
1197 {
1198  return script;
1199 }
1200 
1201 inline const char *
1202 Locale::getVariant() const
1203 {
1204  return &baseName[variantBegin];
1205 }
1206 
1207 inline const char *
1208 Locale::getName() const
1209 {
1210  return fullName;
1211 }
1212 
1213 template<typename StringClass, typename OutputIterator> inline void
1214 Locale::getKeywords(OutputIterator iterator, UErrorCode& status) const
1215 {
1216  LocalPointer<StringEnumeration> keys(createKeywords(status));
1217  if (U_FAILURE(status) || keys.isNull()) {
1218  return;
1219  }
1220  for (;;) {
1221  int32_t resultLength;
1222  const char* buffer = keys->next(&resultLength, status);
1223  if (U_FAILURE(status) || buffer == nullptr) {
1224  return;
1225  }
1226  *iterator++ = StringClass(buffer, resultLength);
1227  }
1228 }
1229 
1230 template<typename StringClass, typename OutputIterator> inline void
1231 Locale::getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const
1232 {
1233  LocalPointer<StringEnumeration> keys(createUnicodeKeywords(status));
1234  if (U_FAILURE(status) || keys.isNull()) {
1235  return;
1236  }
1237  for (;;) {
1238  int32_t resultLength;
1239  const char* buffer = keys->next(&resultLength, status);
1240  if (U_FAILURE(status) || buffer == nullptr) {
1241  return;
1242  }
1243  *iterator++ = StringClass(buffer, resultLength);
1244  }
1245 }
1246 
1247 template<typename StringClass> inline StringClass
1248 Locale::getKeywordValue(StringPiece keywordName, UErrorCode& status) const
1249 {
1250  StringClass result;
1251  StringByteSink<StringClass> sink(&result);
1252  getKeywordValue(keywordName, sink, status);
1253  return result;
1254 }
1255 
1256 template<typename StringClass> inline StringClass
1257 Locale::getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const
1258 {
1259  StringClass result;
1260  StringByteSink<StringClass> sink(&result);
1261  getUnicodeKeywordValue(keywordName, sink, status);
1262  return result;
1263 }
1264 
1265 inline UBool
1266 Locale::isBogus(void) const {
1267  return fIsBogus;
1268 }
1269 
1270 U_NAMESPACE_END
1271 
1272 #endif /* U_SHOW_CPLUSPLUS_API */
1273 
1274 #endif
icu::Locale::ConvertingIterator::hasNext
UBool hasNext() const override
Definition: locid.h:1094
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
icu::Locale::RangeIterator
A generic Locale iterator implementation over Locale input iterators.
Definition: locid.h:1039
icu::Locale::ConvertingIterator::ConvertingIterator
ConvertingIterator(Iter begin, Iter end, Conv converter)
Constructs an iterator from a begin/end range.
Definition: locid.h:1087
UBool
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:269
U_NOEXCEPT
#define U_NOEXCEPT
Definition: platform.h:529
ULOC_SCRIPT_CAPACITY
#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
icu::Locale::ConvertingIterator::next
const Locale & next() override
Definition: locid.h:1100
U_CALLCONV
#define U_CALLCONV
Definition: platform.h:870
icu::operator==
U_EXPORT UBool operator==(const StringPiece &x, const StringPiece &y)
Global operator == for StringPiece.
icu::Locale::ConvertingIterator
A generic Locale iterator implementation over Locale input iterators.
Definition: locid.h:1075
U_COMMON_API
#define U_COMMON_API
Definition: utypes.h:300
icu::LocalPointer
"Smart pointer" class, deletes objects via the standard C++ delete operator.
Definition: localpointer.h:191
stringpiece.h
C++ API: StringPiece: Read-only byte string wrapper class.
icu::UnicodeString
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:294
uloc.h
C API: Locale.
U_FAILURE
#define U_FAILURE(x)
Does the error code indicate a failure?
Definition: utypes.h:719
icu::UObject
UObject is the common ICU "boilerplate" class.
Definition: uobject.h:223
icu::Locale::Iterator
A Locale iterator interface similar to a Java Iterator<Locale>.
Definition: locid.h:1016
UClassID
void * UClassID
UClassID is used to identify classes without using the compiler's RTTI.
Definition: uobject.h:96
UErrorCode
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
putil.h
C API: Platform Utilities.
icu::Locale::RangeIterator::next
const Locale & next() override
Definition: locid.h:1062
icu::StringEnumeration
Base class for 'pure' C++ implementations of uenum api.
Definition: strenum.h:61
icu::UObject::getDynamicClassID
virtual UClassID getDynamicClassID() const
ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class.
icu::ByteSink
A ByteSink can be filled with bytes.
Definition: bytestream.h:53
icu::UMemory
UMemory is the common ICU base class.
Definition: uobject.h:115
icu::operator!=
UBool operator!=(const StringPiece &x, const StringPiece &y)
Global operator != for StringPiece.
Definition: stringpiece.h:345
icu::Locale::RangeIterator::hasNext
UBool hasNext() const override
Definition: locid.h:1056
icu::LocalPointerBase::isNull
UBool isNull() const
NULL check.
Definition: localpointer.h:94
ULOC_FULLNAME_CAPACITY
#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
localpointer.h
C++ API: "Smart pointers" for use with and in ICU4C C++ code.
icu::locale_available_init
void locale_available_init()
icu::Locale::RangeIterator::RangeIterator
RangeIterator(Iter begin, Iter end)
Constructs an iterator from a begin/end range.
Definition: locid.h:1050
strenum.h
C++ API: String Enumeration.
icu::StringByteSink
Implementation of ByteSink that writes to a "string".
Definition: bytestream.h:269
ULOC_LANG_CAPACITY
#define ULOC_LANG_CAPACITY
Useful constant for the maximum size of the language part of a locale ID.
Definition: uloc.h:251
uobject.h
C++ API: Common ICU base class UObject.
icu::StringPiece
A string-like object that points to a sized piece of memory.
Definition: stringpiece.h:60
bytestream.h
C++ API: Interface for writing bytes, and implementation classes.
icu::Locale
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195
ULOC_COUNTRY_CAPACITY
#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