ICU 74.1 74.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"
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
51U_NAMESPACE_BEGIN
52
53// Forward Declarations
57class UnicodeString;
58
196public:
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
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) noexcept;
298
303 virtual ~Locale() ;
304
312 Locale& operator=(const Locale& other);
313
323 Locale& operator=(Locale&& other) noexcept;
324
332 bool operator==(const Locale& other) const;
333
342 inline bool operator!=(const Locale& other) const;
343
355 Locale *clone() const;
356
357#ifndef U_HIDE_SYSTEM_API
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
542
573
581
592
603
615 template<typename StringClass, typename OutputIterator>
616 inline void getKeywords(OutputIterator iterator, UErrorCode& status) const;
617
629 template<typename StringClass, typename OutputIterator>
630 inline void getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const;
631
648 int32_t getKeywordValue(const char* keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const;
649
663 void getKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
664
678 template<typename StringClass>
679 inline StringClass getKeywordValue(StringPiece keywordName, UErrorCode& status) const;
680
694 void getUnicodeKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
695
709 template<typename StringClass>
710 inline StringClass getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const;
711
731 void setKeywordValue(const char* keywordName, const char* keywordValue, UErrorCode &status);
732
751 void setKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
752
771 void setUnicodeKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
772
779 const char * getISO3Language() const;
780
786 const char * getISO3Country() const;
787
795 uint32_t getLCID(void) const;
796
811
822
837 UnicodeString& dispLang) const;
838
849
864 UnicodeString& getDisplayScript( const Locale& displayLocale,
865 UnicodeString& dispScript) const;
866
877
892 UnicodeString& getDisplayCountry( const Locale& displayLocale,
893 UnicodeString& dispCountry) const;
894
903
912 UnicodeString& getDisplayVariant( const Locale& displayLocale,
913 UnicodeString& dispVar) const;
914
927
940 UnicodeString& getDisplayName( const Locale& displayLocale,
941 UnicodeString& name) const;
942
947 int32_t hashCode(void) const;
948
958
964 inline UBool isBogus(void) const;
965
974 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
975
984 static const char* const* U_EXPORT2 getISOCountries();
985
997 static const char* const* U_EXPORT2 getISOLanguages();
998
1004 static UClassID U_EXPORT2 getStaticClassID();
1005
1011 virtual UClassID getDynamicClassID() const override;
1012
1017 class U_COMMON_API Iterator /* not : public UObject because this is an interface/mixin class */ {
1018 public:
1020 virtual ~Iterator();
1021
1026 virtual UBool hasNext() const = 0;
1027
1032 virtual const Locale &next() = 0;
1033 };
1034
1039 template<typename Iter>
1040 class RangeIterator : public Iterator, public UMemory {
1041 public:
1051 RangeIterator(Iter begin, Iter end) : it_(begin), end_(end) {}
1052
1057 UBool hasNext() const override { return it_ != end_; }
1058
1063 const Locale &next() override { return *it_++; }
1064
1065 private:
1066 Iter it_;
1067 const Iter end_;
1068 };
1069
1075 template<typename Iter, typename Conv>
1076 class ConvertingIterator : public Iterator, public UMemory {
1077 public:
1088 ConvertingIterator(Iter begin, Iter end, Conv converter) :
1089 it_(begin), end_(end), converter_(converter) {}
1090
1095 UBool hasNext() const override { return it_ != end_; }
1096
1101 const Locale &next() override { return converter_(*it_++); }
1102
1103 private:
1104 Iter it_;
1105 const Iter end_;
1106 Conv converter_;
1107 };
1108
1109protected: /* only protected for testing purposes. DO NOT USE. */
1110#ifndef U_HIDE_INTERNAL_API
1115 void setFromPOSIXID(const char *posixID);
1124 void minimizeSubtags(bool favorScript, UErrorCode& status);
1125#endif /* U_HIDE_INTERNAL_API */
1126
1127private:
1135 Locale& init(const char* cLocaleID, UBool canonicalize);
1136
1137 /*
1138 * Internal constructor to allow construction of a locale object with
1139 * NO side effects. (Default constructor tries to get
1140 * the default locale.)
1141 */
1142 enum ELocaleType {
1143 eBOGUS
1144 };
1145 Locale(ELocaleType);
1146
1150 static Locale *getLocaleCache(void);
1151
1152 char language[ULOC_LANG_CAPACITY];
1153 char script[ULOC_SCRIPT_CAPACITY];
1154 char country[ULOC_COUNTRY_CAPACITY];
1155 int32_t variantBegin;
1156 char* fullName;
1157 char fullNameBuffer[ULOC_FULLNAME_CAPACITY];
1158 // name without keywords
1159 char* baseName;
1160 void initBaseName(UErrorCode& status);
1161
1162 UBool fIsBogus;
1163
1164 static const Locale &getLocale(int locid);
1165
1170 friend Locale *locale_set_default_internal(const char *, UErrorCode& status);
1171
1176};
1177
1178inline bool
1179Locale::operator!=(const Locale& other) const
1180{
1181 return !operator==(other);
1182}
1183
1184template<typename StringClass> inline StringClass
1185Locale::toLanguageTag(UErrorCode& status) const
1186{
1187 StringClass result;
1188 StringByteSink<StringClass> sink(&result);
1189 toLanguageTag(sink, status);
1190 return result;
1191}
1192
1193inline const char *
1194Locale::getCountry() const
1195{
1196 return country;
1197}
1198
1199inline const char *
1200Locale::getLanguage() const
1201{
1202 return language;
1203}
1204
1205inline const char *
1206Locale::getScript() const
1207{
1208 return script;
1209}
1210
1211inline const char *
1212Locale::getVariant() const
1213{
1214 return &baseName[variantBegin];
1215}
1216
1217inline const char *
1218Locale::getName() const
1219{
1220 return fullName;
1221}
1222
1223template<typename StringClass, typename OutputIterator> inline void
1224Locale::getKeywords(OutputIterator iterator, UErrorCode& status) const
1225{
1226 LocalPointer<StringEnumeration> keys(createKeywords(status));
1227 if (U_FAILURE(status) || keys.isNull()) {
1228 return;
1229 }
1230 for (;;) {
1231 int32_t resultLength;
1232 const char* buffer = keys->next(&resultLength, status);
1233 if (U_FAILURE(status) || buffer == nullptr) {
1234 return;
1235 }
1236 *iterator++ = StringClass(buffer, resultLength);
1237 }
1238}
1239
1240template<typename StringClass, typename OutputIterator> inline void
1241Locale::getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const
1242{
1243 LocalPointer<StringEnumeration> keys(createUnicodeKeywords(status));
1244 if (U_FAILURE(status) || keys.isNull()) {
1245 return;
1246 }
1247 for (;;) {
1248 int32_t resultLength;
1249 const char* buffer = keys->next(&resultLength, status);
1250 if (U_FAILURE(status) || buffer == nullptr) {
1251 return;
1252 }
1253 *iterator++ = StringClass(buffer, resultLength);
1254 }
1255}
1256
1257template<typename StringClass> inline StringClass
1258Locale::getKeywordValue(StringPiece keywordName, UErrorCode& status) const
1259{
1260 StringClass result;
1261 StringByteSink<StringClass> sink(&result);
1262 getKeywordValue(keywordName, sink, status);
1263 return result;
1264}
1265
1266template<typename StringClass> inline StringClass
1267Locale::getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const
1268{
1269 StringClass result;
1270 StringByteSink<StringClass> sink(&result);
1271 getUnicodeKeywordValue(keywordName, sink, status);
1272 return result;
1273}
1274
1275inline UBool
1276Locale::isBogus(void) const {
1277 return fIsBogus;
1278}
1279
1280U_NAMESPACE_END
1281
1282#endif /* U_SHOW_CPLUSPLUS_API */
1283
1284#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:1076
const Locale & next() override
Definition: locid.h:1101
UBool hasNext() const override
Definition: locid.h:1095
ConvertingIterator(Iter begin, Iter end, Conv converter)
Constructs an iterator from a begin/end range.
Definition: locid.h:1088
A Locale iterator interface similar to a Java Iterator<Locale>.
Definition: locid.h:1017
virtual UBool hasNext() const =0
virtual const Locale & next()=0
A generic Locale iterator implementation over Locale input iterators.
Definition: locid.h:1040
RangeIterator(Iter begin, Iter end)
Constructs an iterator from a begin/end range.
Definition: locid.h:1051
UBool hasNext() const override
Definition: locid.h:1057
const Locale & next() override
Definition: locid.h:1063
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195
static const Locale & getGermany(void)
Useful constant for this country/region.
void minimizeSubtags(UErrorCode &status)
Minimize the subtags for this Locale, per the algorithm described in the following CLDR technical rep...
static const Locale & getTraditionalChinese(void)
Useful constant for this language.
void minimizeSubtags(bool favorScript, UErrorCode &status)
Minimize the subtags for this Locale, per the algorithm described.
static const char *const * getISOLanguages()
Returns a list of all unique language codes defined in ISO 639.
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 createFromName(const char *name)
Creates a locale which has had minimal canonicalization as per uloc_getName().
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 ...
static const Locale & getCanadaFrench(void)
Useful constant for this country/region.
static const Locale & getJapanese(void)
Useful constant for this language.
friend void locale_available_init()
static Locale createCanonical(const char *name)
Creates a locale from the given string after canonicalizing the string according to CLDR by calling u...
static const Locale & getUS(void)
Useful constant for this country/region.
static const Locale & getGerman(void)
Useful constant for this language.
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.
static const Locale & getItaly(void)
Useful constant for this country/region.
static const Locale & getChinese(void)
Useful constant for this language.
void setKeywordValue(const char *keywordName, const char *keywordValue, UErrorCode &status)
Sets or removes the value for a keyword.
uint32_t getLCID(void) const
Returns the Windows LCID value corresponding to this locale.
const char * getBaseName() const
Returns the programmatic name of the entire locale as getName() would return, but without keywords.
Locale & operator=(const Locale &other)
Replaces the entire contents of *this with the specified value.
Locale(const char *language, const char *country=0, const char *variant=0, const char *keywordsAndValues=0)
Construct a locale from language, country, variant.
static const Locale & getTaiwan(void)
Useful constant for this country/region.
static const Locale & getKorea(void)
Useful constant for this country/region.
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...
virtual ~Locale()
Destructor.
const char * getISO3Language() const
returns the locale's three-letter language code, as specified in ISO draft standard ISO-639-2.
static const Locale & getRoot(void)
Useful constant for the Root locale.
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 & getUK(void)
Useful constant for this country/region.
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 ...
Locale & operator=(Locale &&other) noexcept
Move assignment operator; might leave source in bogus state.
StringEnumeration * createKeywords(UErrorCode &status) const
Gets the list of keywords for the specified locale.
static const Locale & getItalian(void)
Useful constant for this language.
static const Locale & getCanada(void)
Useful constant for this country/region.
bool operator==(const Locale &other) const
Checks if two locale keys are the same.
static const Locale * getAvailableLocales(int32_t &count)
Returns a list of all installed locales.
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.
static const Locale & getPRC(void)
Useful constant for this country/region.
void toLanguageTag(ByteSink &sink, UErrorCode &status) const
Returns a well-formed language tag for this Locale.
static const Locale & getKorean(void)
Useful constant for this language.
void setToBogus()
Sets the locale to bogus A bogus locale represents a non-existing locale associated with services tha...
UnicodeString & getDisplayVariant(UnicodeString &dispVar) const
Fills in "dispVar" with the name of this locale's variant code in a format suitable for user display ...
void addLikelySubtags(UErrorCode &status)
Add the likely subtags for this Locale, per the algorithm described in the following CLDR technical r...
static const Locale & getFrance(void)
Useful constant for this country/region.
void canonicalize(UErrorCode &status)
Canonicalize the locale ID of this object according to CLDR.
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...
const char * getISO3Country() const
Fills in "name" with the locale's three-letter ISO-3166 country code.
static const Locale & getFrench(void)
Useful constant for this language.
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 & getEnglish(void)
Useful constant for this language.
int32_t hashCode(void) const
Generates a hash code for the locale.
Locale(const Locale &other)
Initializes a Locale object from another Locale object.
static const Locale & getSimplifiedChinese(void)
Useful constant for this language.
void getUnicodeKeywordValue(StringPiece keywordName, ByteSink &sink, UErrorCode &status) const
Gets the Unicode value for a Unicode keyword.
StringEnumeration * createUnicodeKeywords(UErrorCode &status) const
Gets the list of Unicode keywords for the specified locale.
static const char *const * getISOCountries()
Gets a list of all available 2-letter country codes defined in ISO 3166.
static const Locale & getChina(void)
Useful constant for this country/region.
UnicodeString & getDisplayScript(UnicodeString &dispScript) const
Fills in "dispScript" with the name of this locale's script in a format suitable for user display in ...
UBool isRightToLeft() const
Returns whether this locale's script is written right-to-left.
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 setFromPOSIXID(const char *posixID)
Set this from a single POSIX style locale string.
static const Locale & getJapan(void)
Useful constant for this country/region.
static const Locale & getDefault(void)
Common methods of getting the current default Locale.
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...
void getKeywordValue(StringPiece keywordName, ByteSink &sink, UErrorCode &status) const
Gets the value for a keyword.
virtual UClassID getDynamicClassID() const override
ICU "poor man's RTTI", returns a UClassID for the actual class.
Locale * clone() const
Clone this object.
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...
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:866
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:717
#define U_COMMON_API
Set to export library symbols from inside the common library, and to import them from outside.
Definition: utypes.h:300