ICU 76.1  76.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 
250  Locale();
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
357 
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 
540  void addLikelySubtags(UErrorCode& status);
541 
571  void minimizeSubtags(UErrorCode& status);
572 
579  void canonicalize(UErrorCode& status);
580 
590  StringEnumeration * createKeywords(UErrorCode &status) const;
591 
601  StringEnumeration * createUnicodeKeywords(UErrorCode &status) const;
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  setKeywordValue(StringPiece{keywordName}, StringPiece{keywordValue}, status);
732  }
733 
752  void setKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
753 
772  void setUnicodeKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
773 
780  const char * getISO3Language() const;
781 
787  const char * getISO3Country() const;
788 
796  uint32_t getLCID() const;
797 
811  UBool isRightToLeft() const;
812 
822  UnicodeString& getDisplayLanguage(UnicodeString& dispLang) const;
823 
837  UnicodeString& getDisplayLanguage( const Locale& displayLocale,
838  UnicodeString& dispLang) const;
839 
849  UnicodeString& getDisplayScript( UnicodeString& dispScript) const;
850 
865  UnicodeString& getDisplayScript( const Locale& displayLocale,
866  UnicodeString& dispScript) const;
867 
877  UnicodeString& getDisplayCountry( UnicodeString& dispCountry) const;
878 
893  UnicodeString& getDisplayCountry( const Locale& displayLocale,
894  UnicodeString& dispCountry) const;
895 
903  UnicodeString& getDisplayVariant( UnicodeString& dispVar) const;
904 
913  UnicodeString& getDisplayVariant( const Locale& displayLocale,
914  UnicodeString& dispVar) const;
915 
927  UnicodeString& getDisplayName( UnicodeString& name) const;
928 
941  UnicodeString& getDisplayName( const Locale& displayLocale,
942  UnicodeString& name) const;
943 
948  int32_t hashCode() const;
949 
958  void setToBogus();
959 
965  inline UBool isBogus() const;
966 
975  static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
976 
985  static const char* const* U_EXPORT2 getISOCountries();
986 
998  static const char* const* U_EXPORT2 getISOLanguages();
999 
1005  static UClassID U_EXPORT2 getStaticClassID();
1006 
1012  virtual UClassID getDynamicClassID() const override;
1013 
1018  class U_COMMON_API Iterator /* not : public UObject because this is an interface/mixin class */ {
1019  public:
1021  virtual ~Iterator();
1022 
1027  virtual UBool hasNext() const = 0;
1028 
1033  virtual const Locale &next() = 0;
1034  };
1035 
1040  template<typename Iter>
1041  class RangeIterator : public Iterator, public UMemory {
1042  public:
1052  RangeIterator(Iter begin, Iter end) : it_(begin), end_(end) {}
1053 
1058  UBool hasNext() const override { return it_ != end_; }
1059 
1064  const Locale &next() override { return *it_++; }
1065 
1066  private:
1067  Iter it_;
1068  const Iter end_;
1069  };
1070 
1076  template<typename Iter, typename Conv>
1077  class ConvertingIterator : public Iterator, public UMemory {
1078  public:
1089  ConvertingIterator(Iter begin, Iter end, Conv converter) :
1090  it_(begin), end_(end), converter_(converter) {}
1091 
1096  UBool hasNext() const override { return it_ != end_; }
1097 
1102  const Locale &next() override { return converter_(*it_++); }
1103 
1104  private:
1105  Iter it_;
1106  const Iter end_;
1107  Conv converter_;
1108  };
1109 
1110 protected: /* only protected for testing purposes. DO NOT USE. */
1111 #ifndef U_HIDE_INTERNAL_API
1112 
1116  void setFromPOSIXID(const char *posixID);
1125  void minimizeSubtags(bool favorScript, UErrorCode& status);
1126 #endif /* U_HIDE_INTERNAL_API */
1127 
1128 private:
1136  Locale& init(const char* cLocaleID, UBool canonicalize);
1137 
1138  /*
1139  * Internal constructor to allow construction of a locale object with
1140  * NO side effects. (Default constructor tries to get
1141  * the default locale.)
1142  */
1143  enum ELocaleType {
1144  eBOGUS
1145  };
1146  Locale(ELocaleType);
1147 
1151  static Locale* getLocaleCache();
1152 
1153  char language[ULOC_LANG_CAPACITY];
1154  char script[ULOC_SCRIPT_CAPACITY];
1155  char country[ULOC_COUNTRY_CAPACITY];
1156  int32_t variantBegin;
1157  char* fullName;
1158  char fullNameBuffer[ULOC_FULLNAME_CAPACITY];
1159  // name without keywords
1160  char* baseName;
1161  void initBaseName(UErrorCode& status);
1162 
1163  UBool fIsBogus;
1164 
1165  static const Locale &getLocale(int locid);
1166 
1171  friend Locale *locale_set_default_internal(const char *, UErrorCode& status);
1172 
1176  friend void U_CALLCONV locale_available_init();
1177 };
1178 
1179 inline bool
1180 Locale::operator!=(const Locale& other) const
1181 {
1182  return !operator==(other);
1183 }
1184 
1185 template<typename StringClass> inline StringClass
1186 Locale::toLanguageTag(UErrorCode& status) const
1187 {
1188  if (U_FAILURE(status)) { return {}; }
1189  StringClass result;
1190  StringByteSink<StringClass> sink(&result);
1191  toLanguageTag(sink, status);
1192  return result;
1193 }
1194 
1195 inline const char *
1196 Locale::getCountry() const
1197 {
1198  return country;
1199 }
1200 
1201 inline const char *
1202 Locale::getLanguage() const
1203 {
1204  return language;
1205 }
1206 
1207 inline const char *
1208 Locale::getScript() const
1209 {
1210  return script;
1211 }
1212 
1213 inline const char *
1214 Locale::getVariant() const
1215 {
1216  return fIsBogus ? "" : &baseName[variantBegin];
1217 }
1218 
1219 inline const char *
1220 Locale::getName() const
1221 {
1222  return fullName;
1223 }
1224 
1225 template<typename StringClass, typename OutputIterator> inline void
1226 Locale::getKeywords(OutputIterator iterator, UErrorCode& status) const
1227 {
1228  if (U_FAILURE(status)) { return; }
1229  LocalPointer<StringEnumeration> keys(createKeywords(status));
1230  if (U_FAILURE(status) || keys.isNull()) {
1231  return;
1232  }
1233  for (;;) {
1234  int32_t resultLength;
1235  const char* buffer = keys->next(&resultLength, status);
1236  if (U_FAILURE(status) || buffer == nullptr) {
1237  return;
1238  }
1239  *iterator++ = StringClass(buffer, resultLength);
1240  }
1241 }
1242 
1243 template<typename StringClass, typename OutputIterator> inline void
1244 Locale::getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const
1245 {
1246  if (U_FAILURE(status)) { return; }
1247  LocalPointer<StringEnumeration> keys(createUnicodeKeywords(status));
1248  if (U_FAILURE(status) || keys.isNull()) {
1249  return;
1250  }
1251  for (;;) {
1252  int32_t resultLength;
1253  const char* buffer = keys->next(&resultLength, status);
1254  if (U_FAILURE(status) || buffer == nullptr) {
1255  return;
1256  }
1257  *iterator++ = StringClass(buffer, resultLength);
1258  }
1259 }
1260 
1261 template<typename StringClass> inline StringClass
1262 Locale::getKeywordValue(StringPiece keywordName, UErrorCode& status) const
1263 {
1264  if (U_FAILURE(status)) { return {}; }
1265  StringClass result;
1266  StringByteSink<StringClass> sink(&result);
1267  getKeywordValue(keywordName, sink, status);
1268  return result;
1269 }
1270 
1271 template<typename StringClass> inline StringClass
1272 Locale::getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const
1273 {
1274  if (U_FAILURE(status)) { return {}; }
1275  StringClass result;
1276  StringByteSink<StringClass> sink(&result);
1277  getUnicodeKeywordValue(keywordName, sink, status);
1278  return result;
1279 }
1280 
1281 inline UBool
1282 Locale::isBogus() const {
1283  return fIsBogus;
1284 }
1285 
1286 U_NAMESPACE_END
1287 
1288 #endif /* U_SHOW_CPLUSPLUS_API */
1289 
1290 #endif
bool operator!=(const StringPiece &x, const StringPiece &y)
Global operator != for StringPiece.
Definition: stringpiece.h:346
const Locale & next() override
Definition: locid.h:1102
#define U_FAILURE(x)
Does the error code indicate a failure?
Definition: utypes.h:747
#define ULOC_LANG_CAPACITY
Useful constant for the maximum size of the language part of a locale ID.
Definition: uloc.h:251
"Smart pointer" class, deletes objects via the standard C++ delete operator.
Definition: localpointer.h:191
U_EXPORT UBool operator==(const StringPiece &x, const StringPiece &y)
Global operator == for StringPiece.
#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 U_CALLCONV
Similar to U_CDECL_BEGIN/U_CDECL_END, this qualifier is necessary in callback function typedefs to ma...
Definition: platform.h:846
UBool hasNext() const override
Definition: locid.h:1058
void * UClassID
UClassID is used to identify classes without using the compiler&#39;s RTTI.
Definition: uobject.h:96
void setKeywordValue(const char *keywordName, const char *keywordValue, UErrorCode &status)
Sets or removes the value for a keyword.
Definition: locid.h:730
#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
Base class for &#39;pure&#39; C++ implementations of uenum api.
Definition: strenum.h:61
#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
A ByteSink can be filled with bytes.
Definition: bytestream.h:53
A Locale iterator interface similar to a Java Iterator<Locale>.
Definition: locid.h:1018
void locale_available_init()
C++ API: StringPiece: Read-only byte string wrapper class.
C++ API: Interface for writing bytes, and implementation classes.
A generic Locale iterator implementation over Locale input iterators.
Definition: locid.h:1041
UBool isNull() const
nullptr check.
Definition: localpointer.h:94
C++ API: "Smart pointers" for use with and in ICU4C C++ code.
virtual UClassID getDynamicClassID() const
ICU4C "poor man&#39;s RTTI", returns a UClassID for the actual ICU class.
C API: Platform Utilities.
RangeIterator(Iter begin, Iter end)
Constructs an iterator from a begin/end range.
Definition: locid.h:1052
C++ API: Common ICU base class UObject.
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:430
C++ API: String Enumeration.
Basic definitions for ICU, for both C and C++ APIs.
Implementation of ByteSink that writes to a "string".
Definition: bytestream.h:267
#define U_COMMON_API
Set to export library symbols from inside the common library, and to import them from outside...
Definition: utypes.h:315
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:295
A generic Locale iterator implementation over Locale input iterators.
Definition: locid.h:1077
A string-like object that points to a sized piece of memory.
Definition: stringpiece.h:61
UObject is the common ICU "boilerplate" class.
Definition: uobject.h:223
UMemory is the common ICU base class.
Definition: uobject.h:115
const Locale & next() override
Definition: locid.h:1064
ConvertingIterator(Iter begin, Iter end, Conv converter)
Constructs an iterator from a begin/end range.
Definition: locid.h:1089
UBool hasNext() const override
Definition: locid.h:1096
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:247
C API: Locale ID functionality similar to C++ class Locale.
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195