ICU 69.1  69.1
uloc.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 * Copyright (C) 1997-2016, International Business Machines
6 * Corporation and others. All Rights Reserved.
7 **********************************************************************
8 *
9 * File ULOC.H
10 *
11 * Modification History:
12 *
13 * Date Name Description
14 * 04/01/97 aliu Creation.
15 * 08/22/98 stephen JDK 1.2 sync.
16 * 12/08/98 rtg New C API for Locale
17 * 03/30/99 damiba overhaul
18 * 03/31/99 helena Javadoc for uloc functions.
19 * 04/15/99 Madhu Updated Javadoc
20 ********************************************************************************
21 */
22 
23 #ifndef ULOC_H
24 #define ULOC_H
25 
26 #include "unicode/utypes.h"
27 #include "unicode/uenum.h"
28 
203 #define ULOC_CHINESE "zh"
205 #define ULOC_ENGLISH "en"
207 #define ULOC_FRENCH "fr"
209 #define ULOC_GERMAN "de"
211 #define ULOC_ITALIAN "it"
213 #define ULOC_JAPANESE "ja"
215 #define ULOC_KOREAN "ko"
217 #define ULOC_SIMPLIFIED_CHINESE "zh_CN"
219 #define ULOC_TRADITIONAL_CHINESE "zh_TW"
220 
222 #define ULOC_CANADA "en_CA"
224 #define ULOC_CANADA_FRENCH "fr_CA"
226 #define ULOC_CHINA "zh_CN"
228 #define ULOC_PRC "zh_CN"
230 #define ULOC_FRANCE "fr_FR"
232 #define ULOC_GERMANY "de_DE"
234 #define ULOC_ITALY "it_IT"
236 #define ULOC_JAPAN "ja_JP"
238 #define ULOC_KOREA "ko_KR"
240 #define ULOC_TAIWAN "zh_TW"
242 #define ULOC_UK "en_GB"
244 #define ULOC_US "en_US"
245 
251 #define ULOC_LANG_CAPACITY 12
252 
258 #define ULOC_COUNTRY_CAPACITY 4
264 #define ULOC_FULLNAME_CAPACITY 157
265 
271 #define ULOC_SCRIPT_CAPACITY 6
272 
277 #define ULOC_KEYWORDS_CAPACITY 96
278 
283 #define ULOC_KEYWORD_AND_VALUES_CAPACITY 100
284 
289 #define ULOC_KEYWORD_SEPARATOR '@'
290 
296 #define ULOC_KEYWORD_SEPARATOR_UNICODE 0x40
297 
302 #define ULOC_KEYWORD_ASSIGN '='
303 
309 #define ULOC_KEYWORD_ASSIGN_UNICODE 0x3D
310 
315 #define ULOC_KEYWORD_ITEM_SEPARATOR ';'
316 
322 #define ULOC_KEYWORD_ITEM_SEPARATOR_UNICODE 0x3B
323 
338 typedef enum {
347 
348 #ifndef U_HIDE_DEPRECATED_API
353 
359 #endif // U_HIDE_DEPRECATED_API
361 
362 #ifndef U_HIDE_SYSTEM_API
374 U_CAPI const char* U_EXPORT2
376 
394 U_CAPI void U_EXPORT2
395 uloc_setDefault(const char* localeID,
396  UErrorCode* status);
397 #endif /* U_HIDE_SYSTEM_API */
398 
411 U_CAPI int32_t U_EXPORT2
412 uloc_getLanguage(const char* localeID,
413  char* language,
414  int32_t languageCapacity,
415  UErrorCode* err);
416 
429 U_CAPI int32_t U_EXPORT2
430 uloc_getScript(const char* localeID,
431  char* script,
432  int32_t scriptCapacity,
433  UErrorCode* err);
434 
447 U_CAPI int32_t U_EXPORT2
448 uloc_getCountry(const char* localeID,
449  char* country,
450  int32_t countryCapacity,
451  UErrorCode* err);
452 
465 U_CAPI int32_t U_EXPORT2
466 uloc_getVariant(const char* localeID,
467  char* variant,
468  int32_t variantCapacity,
469  UErrorCode* err);
470 
471 
488 U_CAPI int32_t U_EXPORT2
489 uloc_getName(const char* localeID,
490  char* name,
491  int32_t nameCapacity,
492  UErrorCode* err);
493 
511 U_CAPI int32_t U_EXPORT2
512 uloc_canonicalize(const char* localeID,
513  char* name,
514  int32_t nameCapacity,
515  UErrorCode* err);
516 
524 U_CAPI const char* U_EXPORT2
525 uloc_getISO3Language(const char* localeID);
526 
527 
535 U_CAPI const char* U_EXPORT2
536 uloc_getISO3Country(const char* localeID);
537 
549 U_CAPI uint32_t U_EXPORT2
550 uloc_getLCID(const char* localeID);
551 
573 U_CAPI int32_t U_EXPORT2
574 uloc_getDisplayLanguage(const char* locale,
575  const char* displayLocale,
576  UChar* language,
577  int32_t languageCapacity,
578  UErrorCode* status);
579 
602 U_CAPI int32_t U_EXPORT2
603 uloc_getDisplayScript(const char* locale,
604  const char* displayLocale,
605  UChar* script,
606  int32_t scriptCapacity,
607  UErrorCode* status);
608 
634 U_CAPI int32_t U_EXPORT2
635 uloc_getDisplayCountry(const char* locale,
636  const char* displayLocale,
637  UChar* country,
638  int32_t countryCapacity,
639  UErrorCode* status);
640 
641 
664 U_CAPI int32_t U_EXPORT2
665 uloc_getDisplayVariant(const char* locale,
666  const char* displayLocale,
667  UChar* variant,
668  int32_t variantCapacity,
669  UErrorCode* status);
670 
713 U_CAPI int32_t U_EXPORT2
714 uloc_getDisplayKeyword(const char* keyword,
715  const char* displayLocale,
716  UChar* dest,
717  int32_t destCapacity,
718  UErrorCode* status);
741 U_CAPI int32_t U_EXPORT2
742 uloc_getDisplayKeywordValue( const char* locale,
743  const char* keyword,
744  const char* displayLocale,
745  UChar* dest,
746  int32_t destCapacity,
747  UErrorCode* status);
764 U_CAPI int32_t U_EXPORT2
765 uloc_getDisplayName(const char* localeID,
766  const char* inLocaleID,
767  UChar* result,
768  int32_t maxResultSize,
769  UErrorCode* err);
770 
771 
788 U_CAPI const char* U_EXPORT2
789 uloc_getAvailable(int32_t n);
790 
797 U_CAPI int32_t U_EXPORT2 uloc_countAvailable(void);
798 
804 typedef enum ULocAvailableType {
812 
830 
838 
839 #ifndef U_HIDE_INTERNAL_API
844 #endif
846 
858 U_CAPI UEnumeration* U_EXPORT2
860 
872 U_CAPI const char* const* U_EXPORT2
874 
884 U_CAPI const char* const* U_EXPORT2
886 
900 U_CAPI int32_t U_EXPORT2
901 uloc_getParent(const char* localeID,
902  char* parent,
903  int32_t parentCapacity,
904  UErrorCode* err);
905 
906 
907 
908 
931 U_CAPI int32_t U_EXPORT2
932 uloc_getBaseName(const char* localeID,
933  char* name,
934  int32_t nameCapacity,
935  UErrorCode* err);
936 
946 U_CAPI UEnumeration* U_EXPORT2
947 uloc_openKeywords(const char* localeID,
948  UErrorCode* status);
949 
963 U_CAPI int32_t U_EXPORT2
964 uloc_getKeywordValue(const char* localeID,
965  const char* keywordName,
966  char* buffer, int32_t bufferCapacity,
967  UErrorCode* status);
968 
969 
1000 U_CAPI int32_t U_EXPORT2
1001 uloc_setKeywordValue(const char* keywordName,
1002  const char* keywordValue,
1003  char* buffer, int32_t bufferCapacity,
1004  UErrorCode* status);
1005 
1020 U_CAPI UBool U_EXPORT2
1021 uloc_isRightToLeft(const char *locale);
1022 
1028 typedef enum {
1029  ULOC_LAYOUT_LTR = 0, /* left-to-right. */
1030  ULOC_LAYOUT_RTL = 1, /* right-to-left. */
1031  ULOC_LAYOUT_TTB = 2, /* top-to-bottom. */
1032  ULOC_LAYOUT_BTT = 3, /* bottom-to-top. */
1033  ULOC_LAYOUT_UNKNOWN
1034 } ULayoutType;
1035 
1044 U_CAPI ULayoutType U_EXPORT2
1045 uloc_getCharacterOrientation(const char* localeId,
1046  UErrorCode *status);
1047 
1056 U_CAPI ULayoutType U_EXPORT2
1057 uloc_getLineOrientation(const char* localeId,
1058  UErrorCode *status);
1059 
1067 typedef enum {
1083  ULOC_ACCEPT_FALLBACK = 2 /* */
1085 
1103 U_CAPI int32_t U_EXPORT2
1104 uloc_acceptLanguageFromHTTP(char *result, int32_t resultAvailable,
1105  UAcceptResult *outResult,
1106  const char *httpAcceptLanguage,
1107  UEnumeration* availableLocales,
1108  UErrorCode *status);
1109 
1128 U_CAPI int32_t U_EXPORT2
1129 uloc_acceptLanguage(char *result, int32_t resultAvailable,
1130  UAcceptResult *outResult, const char **acceptList,
1131  int32_t acceptListCount,
1132  UEnumeration* availableLocales,
1133  UErrorCode *status);
1134 
1135 
1148 U_CAPI int32_t U_EXPORT2
1149 uloc_getLocaleForLCID(uint32_t hostID, char *locale, int32_t localeCapacity,
1150  UErrorCode *status);
1151 
1152 
1186 U_CAPI int32_t U_EXPORT2
1187 uloc_addLikelySubtags(const char* localeID,
1188  char* maximizedLocaleID,
1189  int32_t maximizedLocaleIDCapacity,
1190  UErrorCode* err);
1191 
1192 
1226 U_CAPI int32_t U_EXPORT2
1227 uloc_minimizeSubtags(const char* localeID,
1228  char* minimizedLocaleID,
1229  int32_t minimizedLocaleIDCapacity,
1230  UErrorCode* err);
1231 
1259 U_CAPI int32_t U_EXPORT2
1260 uloc_forLanguageTag(const char* langtag,
1261  char* localeID,
1262  int32_t localeIDCapacity,
1263  int32_t* parsedLength,
1264  UErrorCode* err);
1265 
1287 U_CAPI int32_t U_EXPORT2
1288 uloc_toLanguageTag(const char* localeID,
1289  char* langtag,
1290  int32_t langtagCapacity,
1291  UBool strict,
1292  UErrorCode* err);
1293 
1315 U_CAPI const char* U_EXPORT2
1316 uloc_toUnicodeLocaleKey(const char* keyword);
1317 
1346 U_CAPI const char* U_EXPORT2
1347 uloc_toUnicodeLocaleType(const char* keyword, const char* value);
1348 
1361 U_CAPI const char* U_EXPORT2
1362 uloc_toLegacyKey(const char* keyword);
1363 
1390 U_CAPI const char* U_EXPORT2
1391 uloc_toLegacyType(const char* keyword, const char* value);
1392 
1393 #endif /*_ULOC*/
C API: String Enumeration.
struct UEnumeration UEnumeration
structure representing an enumeration object instance
Definition: uenum.h:44
U_CAPI int32_t uloc_acceptLanguage(char *result, int32_t resultAvailable, UAcceptResult *outResult, const char **acceptList, int32_t acceptListCount, UEnumeration *availableLocales, UErrorCode *status)
Based on a list of available locales, determine an acceptable locale for the user.
U_CAPI const char * uloc_getAvailable(int32_t n)
Gets the specified locale from a list of available locales.
U_CAPI const char * uloc_getDefault(void)
Gets ICU's default locale.
U_CAPI const char * uloc_getISO3Language(const char *localeID)
Gets the ISO language code for the specified locale.
U_CAPI ULayoutType uloc_getLineOrientation(const char *localeId, UErrorCode *status)
Get the layout line orientation for the specified locale.
U_CAPI int32_t uloc_toLanguageTag(const char *localeID, char *langtag, int32_t langtagCapacity, UBool strict, UErrorCode *err)
Returns a well-formed language tag for this locale ID.
U_CAPI const char * uloc_toUnicodeLocaleType(const char *keyword, const char *value)
Converts the specified keyword value (legacy type, or BCP 47 Unicode locale extension type) to the we...
U_CAPI int32_t uloc_getDisplayName(const char *localeID, const char *inLocaleID, UChar *result, int32_t maxResultSize, UErrorCode *err)
Gets the full name suitable for display for the specified locale.
UAcceptResult
Output values which uloc_acceptLanguage() writes to the 'outResult' parameter.
Definition: uloc.h:1067
@ ULOC_ACCEPT_VALID
An exact match was found.
Definition: uloc.h:1077
@ ULOC_ACCEPT_FALLBACK
A fallback was found.
Definition: uloc.h:1083
@ ULOC_ACCEPT_FAILED
No exact match was found.
Definition: uloc.h:1072
U_CAPI int32_t uloc_getDisplayVariant(const char *locale, const char *displayLocale, UChar *variant, int32_t variantCapacity, UErrorCode *status)
Gets the variant name suitable for display for the specified locale.
U_CAPI int32_t uloc_getDisplayScript(const char *locale, const char *displayLocale, UChar *script, int32_t scriptCapacity, UErrorCode *status)
Gets the script name suitable for display for the specified locale.
U_CAPI int32_t uloc_getVariant(const char *localeID, char *variant, int32_t variantCapacity, UErrorCode *err)
Gets the variant code for the specified locale.
U_CAPI const char * uloc_getISO3Country(const char *localeID)
Gets the ISO country code for the specified locale.
U_CAPI int32_t uloc_getKeywordValue(const char *localeID, const char *keywordName, char *buffer, int32_t bufferCapacity, UErrorCode *status)
Get the value for a keyword.
U_CAPI const char * uloc_toLegacyType(const char *keyword, const char *value)
Converts the specified keyword value (BCP 47 Unicode locale extension type, or legacy type or type al...
ULayoutType
enums for the return value for the character and line orientation functions.
Definition: uloc.h:1028
U_CAPI int32_t uloc_getLanguage(const char *localeID, char *language, int32_t languageCapacity, UErrorCode *err)
Gets the language code for the specified locale.
U_CAPI uint32_t uloc_getLCID(const char *localeID)
Gets the Win32 LCID value for the specified locale.
U_CAPI int32_t uloc_canonicalize(const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
Gets the full name for the specified locale.
U_CAPI int32_t uloc_minimizeSubtags(const char *localeID, char *minimizedLocaleID, int32_t minimizedLocaleIDCapacity, UErrorCode *err)
Minimize the subtags for a provided locale ID, per the algorithm described in the following CLDR tech...
U_CAPI int32_t uloc_addLikelySubtags(const char *localeID, char *maximizedLocaleID, int32_t maximizedLocaleIDCapacity, UErrorCode *err)
Add the likely subtags for a provided locale ID, per the algorithm described in the following CLDR te...
U_CAPI UEnumeration * uloc_openKeywords(const char *localeID, UErrorCode *status)
Gets an enumeration of keywords for the specified locale.
U_CAPI const char *const * uloc_getISOCountries(void)
Gets a list of all available 2-letter country codes defined in ISO 639.
U_CAPI int32_t uloc_acceptLanguageFromHTTP(char *result, int32_t resultAvailable, UAcceptResult *outResult, const char *httpAcceptLanguage, UEnumeration *availableLocales, UErrorCode *status)
Based on a HTTP header from a web browser and a list of available locales, determine an acceptable lo...
U_CAPI UEnumeration * uloc_openAvailableByType(ULocAvailableType type, UErrorCode *status)
Gets a list of available locales according to the type argument, allowing the user to access differen...
U_CAPI int32_t uloc_getScript(const char *localeID, char *script, int32_t scriptCapacity, UErrorCode *err)
Gets the script code for the specified locale.
U_CAPI ULayoutType uloc_getCharacterOrientation(const char *localeId, UErrorCode *status)
Get the layout character orientation for the specified locale.
U_CAPI void uloc_setDefault(const char *localeID, UErrorCode *status)
Sets ICU's default locale.
U_CAPI int32_t uloc_getCountry(const char *localeID, char *country, int32_t countryCapacity, UErrorCode *err)
Gets the country code for the specified locale.
U_CAPI UBool uloc_isRightToLeft(const char *locale)
Returns whether the locale's script is written right-to-left.
U_CAPI const char * uloc_toUnicodeLocaleKey(const char *keyword)
Converts the specified keyword (legacy key, or BCP 47 Unicode locale extension key) to the equivalent...
U_CAPI int32_t uloc_getParent(const char *localeID, char *parent, int32_t parentCapacity, UErrorCode *err)
Truncate the locale ID string to get the parent locale ID.
U_CAPI int32_t uloc_getBaseName(const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
Gets the full name for the specified locale, like uloc_getName(), but without keywords.
U_CAPI int32_t uloc_getName(const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
Gets the full name for the specified locale.
U_CAPI int32_t uloc_countAvailable(void)
Gets the size of the all available locale list.
U_CAPI int32_t uloc_forLanguageTag(const char *langtag, char *localeID, int32_t localeIDCapacity, int32_t *parsedLength, UErrorCode *err)
Returns a locale ID for the specified BCP47 language tag string.
U_CAPI int32_t uloc_getDisplayKeyword(const char *keyword, const char *displayLocale, UChar *dest, int32_t destCapacity, UErrorCode *status)
Gets the keyword name suitable for display for the specified locale.
ULocDataLocaleType
Constants for *_getLocale() Allow user to select whether she wants information on requested,...
Definition: uloc.h:338
@ ULOC_DATA_LOCALE_TYPE_LIMIT
One more than the highest normal ULocDataLocaleType value.
Definition: uloc.h:358
@ ULOC_ACTUAL_LOCALE
This is locale the data actually comes from.
Definition: uloc.h:342
@ ULOC_VALID_LOCALE
This is the most specific locale supported by ICU.
Definition: uloc.h:346
@ ULOC_REQUESTED_LOCALE
This is the requested locale.
Definition: uloc.h:352
U_CAPI int32_t uloc_getDisplayCountry(const char *locale, const char *displayLocale, UChar *country, int32_t countryCapacity, UErrorCode *status)
Gets the country name suitable for display for the specified locale.
U_CAPI int32_t uloc_setKeywordValue(const char *keywordName, const char *keywordValue, char *buffer, int32_t bufferCapacity, UErrorCode *status)
Sets or removes the value of the specified keyword.
U_CAPI const char * uloc_toLegacyKey(const char *keyword)
Converts the specified keyword (BCP 47 Unicode locale extension key, or legacy key) to the legacy key...
U_CAPI int32_t uloc_getDisplayLanguage(const char *locale, const char *displayLocale, UChar *language, int32_t languageCapacity, UErrorCode *status)
Gets the language name suitable for display for the specified locale.
U_CAPI int32_t uloc_getLocaleForLCID(uint32_t hostID, char *locale, int32_t localeCapacity, UErrorCode *status)
Gets the ICU locale ID for the specified Win32 LCID value.
U_CAPI const char *const * uloc_getISOLanguages(void)
Gets a list of all available 2-letter language codes defined in ISO 639, plus additional 3-letter cod...
ULocAvailableType
Types for uloc_getAvailableByType and uloc_countAvailableByType.
Definition: uloc.h:804
@ ULOC_AVAILABLE_ONLY_LEGACY_ALIASES
Legacy or alias locales that return data when passed to ICU APIs.
Definition: uloc.h:829
@ ULOC_AVAILABLE_COUNT
Definition: uloc.h:843
@ ULOC_AVAILABLE_WITH_LEGACY_ALIASES
The union of the locales in ULOC_AVAILABLE_DEFAULT and ULOC_AVAILABLE_ONLY_LEGACY_ALIAS.
Definition: uloc.h:837
@ ULOC_AVAILABLE_DEFAULT
Locales that return data when passed to ICU APIs, but not including legacy or alias locales.
Definition: uloc.h:811
U_CAPI int32_t uloc_getDisplayKeywordValue(const char *locale, const char *keyword, const char *displayLocale, UChar *dest, int32_t destCapacity, UErrorCode *status)
Gets the value of the keyword suitable for display for the specified locale.
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:269
#define U_CAPI
This is used to declare a function as a public ICU C API.
Definition: umachine.h:110
char16_t UChar
The base type for UTF-16 code units and pointers.
Definition: umachine.h:418
Basic definitions for ICU, for both C and C++ APIs.
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415