ICU 65.1  65.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"
204 
205 #define ULOC_ENGLISH "en"
206 
207 #define ULOC_FRENCH "fr"
208 
209 #define ULOC_GERMAN "de"
210 
211 #define ULOC_ITALIAN "it"
212 
213 #define ULOC_JAPANESE "ja"
214 
215 #define ULOC_KOREAN "ko"
216 
217 #define ULOC_SIMPLIFIED_CHINESE "zh_CN"
218 
219 #define ULOC_TRADITIONAL_CHINESE "zh_TW"
220 
222 #define ULOC_CANADA "en_CA"
223 
224 #define ULOC_CANADA_FRENCH "fr_CA"
225 
226 #define ULOC_CHINA "zh_CN"
227 
228 #define ULOC_PRC "zh_CN"
229 
230 #define ULOC_FRANCE "fr_FR"
231 
232 #define ULOC_GERMANY "de_DE"
233 
234 #define ULOC_ITALY "it_IT"
235 
236 #define ULOC_JAPAN "ja_JP"
237 
238 #define ULOC_KOREA "ko_KR"
239 
240 #define ULOC_TAIWAN "zh_TW"
241 
242 #define ULOC_UK "en_GB"
243 
244 #define ULOC_US "en_US"
245 
251 #define ULOC_LANG_CAPACITY 12
252 
258 #define ULOC_COUNTRY_CAPACITY 4
259 
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
349 
353 
359 #endif // U_HIDE_DEPRECATED_API
361 
362 #ifndef U_HIDE_SYSTEM_API
363 
374 U_STABLE const char* U_EXPORT2
375 uloc_getDefault(void);
376 
394 U_STABLE void U_EXPORT2
395 uloc_setDefault(const char* localeID,
396  UErrorCode* status);
397 #endif /* U_HIDE_SYSTEM_API */
398 
411 U_STABLE int32_t U_EXPORT2
412 uloc_getLanguage(const char* localeID,
413  char* language,
414  int32_t languageCapacity,
415  UErrorCode* err);
416 
429 U_STABLE int32_t U_EXPORT2
430 uloc_getScript(const char* localeID,
431  char* script,
432  int32_t scriptCapacity,
433  UErrorCode* err);
434 
447 U_STABLE int32_t U_EXPORT2
448 uloc_getCountry(const char* localeID,
449  char* country,
450  int32_t countryCapacity,
451  UErrorCode* err);
452 
465 U_STABLE int32_t U_EXPORT2
466 uloc_getVariant(const char* localeID,
467  char* variant,
468  int32_t variantCapacity,
469  UErrorCode* err);
470 
471 
488 U_STABLE int32_t U_EXPORT2
489 uloc_getName(const char* localeID,
490  char* name,
491  int32_t nameCapacity,
492  UErrorCode* err);
493 
511 U_STABLE int32_t U_EXPORT2
512 uloc_canonicalize(const char* localeID,
513  char* name,
514  int32_t nameCapacity,
515  UErrorCode* err);
516 
524 U_STABLE const char* U_EXPORT2
525 uloc_getISO3Language(const char* localeID);
526 
527 
535 U_STABLE const char* U_EXPORT2
536 uloc_getISO3Country(const char* localeID);
537 
549 U_STABLE uint32_t U_EXPORT2
550 uloc_getLCID(const char* localeID);
551 
568 U_STABLE int32_t U_EXPORT2
569 uloc_getDisplayLanguage(const char* locale,
570  const char* displayLocale,
571  UChar* language,
572  int32_t languageCapacity,
573  UErrorCode* status);
574 
591 U_STABLE int32_t U_EXPORT2
592 uloc_getDisplayScript(const char* locale,
593  const char* displayLocale,
594  UChar* script,
595  int32_t scriptCapacity,
596  UErrorCode* status);
597 
616 U_STABLE int32_t U_EXPORT2
617 uloc_getDisplayCountry(const char* locale,
618  const char* displayLocale,
619  UChar* country,
620  int32_t countryCapacity,
621  UErrorCode* status);
622 
623 
640 U_STABLE int32_t U_EXPORT2
641 uloc_getDisplayVariant(const char* locale,
642  const char* displayLocale,
643  UChar* variant,
644  int32_t variantCapacity,
645  UErrorCode* status);
646 
687 U_STABLE int32_t U_EXPORT2
688 uloc_getDisplayKeyword(const char* keyword,
689  const char* displayLocale,
690  UChar* dest,
691  int32_t destCapacity,
692  UErrorCode* status);
713 U_STABLE int32_t U_EXPORT2
714 uloc_getDisplayKeywordValue( const char* locale,
715  const char* keyword,
716  const char* displayLocale,
717  UChar* dest,
718  int32_t destCapacity,
719  UErrorCode* status);
736 U_STABLE int32_t U_EXPORT2
737 uloc_getDisplayName(const char* localeID,
738  const char* inLocaleID,
739  UChar* result,
740  int32_t maxResultSize,
741  UErrorCode* err);
742 
743 
760 U_STABLE const char* U_EXPORT2
761 uloc_getAvailable(int32_t n);
762 
769 U_STABLE int32_t U_EXPORT2 uloc_countAvailable(void);
770 
771 #ifndef U_HIDE_DRAFT_API
772 
778 typedef enum ULocAvailableType {
786 
804 
812 
813 #ifndef U_HIDE_INTERNAL_API
814 
818 #endif
820 
832 U_DRAFT UEnumeration* U_EXPORT2
834 
835 #endif // U_HIDE_DRAFT_API
836 
848 U_STABLE const char* const* U_EXPORT2
850 
860 U_STABLE const char* const* U_EXPORT2
862 
876 U_STABLE int32_t U_EXPORT2
877 uloc_getParent(const char* localeID,
878  char* parent,
879  int32_t parentCapacity,
880  UErrorCode* err);
881 
882 
883 
884 
907 U_STABLE int32_t U_EXPORT2
908 uloc_getBaseName(const char* localeID,
909  char* name,
910  int32_t nameCapacity,
911  UErrorCode* err);
912 
922 U_STABLE UEnumeration* U_EXPORT2
923 uloc_openKeywords(const char* localeID,
924  UErrorCode* status);
925 
939 U_STABLE int32_t U_EXPORT2
940 uloc_getKeywordValue(const char* localeID,
941  const char* keywordName,
942  char* buffer, int32_t bufferCapacity,
943  UErrorCode* status);
944 
945 
976 U_STABLE int32_t U_EXPORT2
977 uloc_setKeywordValue(const char* keywordName,
978  const char* keywordValue,
979  char* buffer, int32_t bufferCapacity,
980  UErrorCode* status);
981 
996 U_STABLE UBool U_EXPORT2
997 uloc_isRightToLeft(const char *locale);
998 
1004 typedef enum {
1005  ULOC_LAYOUT_LTR = 0, /* left-to-right. */
1006  ULOC_LAYOUT_RTL = 1, /* right-to-left. */
1007  ULOC_LAYOUT_TTB = 2, /* top-to-bottom. */
1008  ULOC_LAYOUT_BTT = 3, /* bottom-to-top. */
1009  ULOC_LAYOUT_UNKNOWN
1010 } ULayoutType;
1011 
1020 U_STABLE ULayoutType U_EXPORT2
1021 uloc_getCharacterOrientation(const char* localeId,
1022  UErrorCode *status);
1023 
1032 U_STABLE ULayoutType U_EXPORT2
1033 uloc_getLineOrientation(const char* localeId,
1034  UErrorCode *status);
1035 
1042 typedef enum {
1043  ULOC_ACCEPT_FAILED = 0, /* No exact match was found. */
1044  ULOC_ACCEPT_VALID = 1, /* An exact match was found. */
1045  ULOC_ACCEPT_FALLBACK = 2 /* A fallback was found, for example,
1046  Accept list contained 'ja_JP'
1047  which matched available locale 'ja'. */
1048 } UAcceptResult;
1049 
1050 
1063 U_STABLE int32_t U_EXPORT2
1064 uloc_acceptLanguageFromHTTP(char *result, int32_t resultAvailable,
1065  UAcceptResult *outResult,
1066  const char *httpAcceptLanguage,
1067  UEnumeration* availableLocales,
1068  UErrorCode *status);
1069 
1083 U_STABLE int32_t U_EXPORT2
1084 uloc_acceptLanguage(char *result, int32_t resultAvailable,
1085  UAcceptResult *outResult, const char **acceptList,
1086  int32_t acceptListCount,
1087  UEnumeration* availableLocales,
1088  UErrorCode *status);
1089 
1090 
1103 U_STABLE int32_t U_EXPORT2
1104 uloc_getLocaleForLCID(uint32_t hostID, char *locale, int32_t localeCapacity,
1105  UErrorCode *status);
1106 
1107 
1141 U_STABLE int32_t U_EXPORT2
1142 uloc_addLikelySubtags(const char* localeID,
1143  char* maximizedLocaleID,
1144  int32_t maximizedLocaleIDCapacity,
1145  UErrorCode* err);
1146 
1147 
1181 U_STABLE int32_t U_EXPORT2
1182 uloc_minimizeSubtags(const char* localeID,
1183  char* minimizedLocaleID,
1184  int32_t minimizedLocaleIDCapacity,
1185  UErrorCode* err);
1186 
1210 U_STABLE int32_t U_EXPORT2
1211 uloc_forLanguageTag(const char* langtag,
1212  char* localeID,
1213  int32_t localeIDCapacity,
1214  int32_t* parsedLength,
1215  UErrorCode* err);
1216 
1238 U_STABLE int32_t U_EXPORT2
1239 uloc_toLanguageTag(const char* localeID,
1240  char* langtag,
1241  int32_t langtagCapacity,
1242  UBool strict,
1243  UErrorCode* err);
1244 
1266 U_STABLE const char* U_EXPORT2
1267 uloc_toUnicodeLocaleKey(const char* keyword);
1268 
1297 U_STABLE const char* U_EXPORT2
1298 uloc_toUnicodeLocaleType(const char* keyword, const char* value);
1299 
1312 U_STABLE const char* U_EXPORT2
1313 uloc_toLegacyKey(const char* keyword);
1314 
1341 U_STABLE const char* U_EXPORT2
1342 uloc_toLegacyType(const char* keyword, const char* value);
1343 
1344 #endif /*_ULOC*/
uloc_getBaseName
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.
ULOC_AVAILABLE_WITH_LEGACY_ALIASES
The union of the locales in ULOC_AVAILABLE_DEFAULT and ULOC_AVAILABLE_ONLY_LEGACY_ALIAS.
Definition: uloc.h:811
uloc_getParent
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.
uloc_getCharacterOrientation
ULayoutType uloc_getCharacterOrientation(const char *localeId, UErrorCode *status)
Get the layout character orientation for the specified locale.
uloc_isRightToLeft
UBool uloc_isRightToLeft(const char *locale)
Returns whether the locale's script is written right-to-left.
uloc_forLanguageTag
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.
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
uloc_getDisplayScript
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.
ULOC_ACTUAL_LOCALE
This is locale the data actually comes from.
Definition: uloc.h:342
UBool
int8_t UBool
The ICU boolean type.
Definition: umachine.h:261
uloc_acceptLanguage
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.
ULocDataLocaleType
ULocDataLocaleType
Constants for *_getLocale() Allow user to select whether she wants information on requested,...
Definition: uloc.h:338
uloc_getISOLanguages
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...
uloc_acceptLanguageFromHTTP
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...
uloc_toLegacyType
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
ULayoutType
enums for the return value for the character and line orientation functions.
Definition: uloc.h:1004
uloc_setDefault
void uloc_setDefault(const char *localeID, UErrorCode *status)
Sets ICU's default locale.
uloc_getDisplayVariant
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.
uloc_getScript
int32_t uloc_getScript(const char *localeID, char *script, int32_t scriptCapacity, UErrorCode *err)
Gets the script code for the specified locale.
uloc_getISOCountries
const char *const * uloc_getISOCountries(void)
Gets a list of all available 2-letter country codes defined in ISO 639.
uloc_minimizeSubtags
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...
uloc_getName
int32_t uloc_getName(const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
Gets the full name for the specified locale.
uloc_getISO3Language
const char * uloc_getISO3Language(const char *localeID)
Gets the ISO language code for the specified locale.
uloc_getDefault
const char * uloc_getDefault(void)
Gets ICU's default locale.
UErrorCode
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
uloc_getKeywordValue
int32_t uloc_getKeywordValue(const char *localeID, const char *keywordName, char *buffer, int32_t bufferCapacity, UErrorCode *status)
Get the value for a keyword.
uloc_openKeywords
UEnumeration * uloc_openKeywords(const char *localeID, UErrorCode *status)
Gets an enumeration of keywords for the specified locale.
ULOC_AVAILABLE_COUNT
Definition: uloc.h:817
uloc_getAvailable
const char * uloc_getAvailable(int32_t n)
Gets the specified locale from a list of available locales.
uloc_getDisplayLanguage
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.
uloc_getCountry
int32_t uloc_getCountry(const char *localeID, char *country, int32_t countryCapacity, UErrorCode *err)
Gets the country code for the specified locale.
ULOC_VALID_LOCALE
This is the most specific locale supported by ICU.
Definition: uloc.h:346
ULOC_AVAILABLE_ONLY_LEGACY_ALIASES
Legacy or alias locales that return data when passed to ICU APIs.
Definition: uloc.h:803
ULOC_AVAILABLE_DEFAULT
Locales that return data when passed to ICU APIs, but not including legacy or alias locales.
Definition: uloc.h:785
uloc_toLanguageTag
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.
uloc_addLikelySubtags
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...
uloc_getDisplayName
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.
uloc_getLanguage
int32_t uloc_getLanguage(const char *localeID, char *language, int32_t languageCapacity, UErrorCode *err)
Gets the language code for the specified locale.
uloc_countAvailable
int32_t uloc_countAvailable(void)
Gets the size of the all available locale list.
uloc_getVariant
int32_t uloc_getVariant(const char *localeID, char *variant, int32_t variantCapacity, UErrorCode *err)
Gets the variant code for the specified locale.
uloc_openAvailableByType
UEnumeration * uloc_openAvailableByType(ULocAvailableType type, UErrorCode *status)
Gets a list of available locales according to the type argument, allowing the user to access differen...
uloc_setKeywordValue
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.
ULOC_DATA_LOCALE_TYPE_LIMIT
One more than the highest normal ULocDataLocaleType value.
Definition: uloc.h:358
U_DRAFT
#define U_DRAFT
This is used to declare a function as a draft public ICU C API
Definition: umachine.h:113
U_STABLE
#define U_STABLE
This is used to declare a function as a stable public ICU C API.
Definition: umachine.h:111
uloc_getISO3Country
const char * uloc_getISO3Country(const char *localeID)
Gets the ISO country code for the specified locale.
uloc_toUnicodeLocaleKey
const char * uloc_toUnicodeLocaleKey(const char *keyword)
Converts the specified keyword (legacy key, or BCP 47 Unicode locale extension key) to the equivalent...
UChar
uint16_t UChar
Definition: umachine.h:378
uloc_getLCID
uint32_t uloc_getLCID(const char *localeID)
Gets the Win32 LCID value for the specified locale.
ULocAvailableType
ULocAvailableType
Types for uloc_getAvailableByType and uloc_countAvailableByType.
Definition: uloc.h:778
uloc_getLineOrientation
ULayoutType uloc_getLineOrientation(const char *localeId, UErrorCode *status)
Get the layout line orientation for the specified locale.
UEnumeration
struct UEnumeration UEnumeration
structure representing an enumeration object instance
Definition: uenum.h:43
uloc_getDisplayKeywordValue
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.
uloc_getDisplayKeyword
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.
uloc_getLocaleForLCID
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.
ULOC_REQUESTED_LOCALE
This is the requested locale.
Definition: uloc.h:352
uloc_toLegacyKey
const char * uloc_toLegacyKey(const char *keyword)
Converts the specified keyword (BCP 47 Unicode locale extension key, or legacy key) to the legacy key...
uloc_canonicalize
int32_t uloc_canonicalize(const char *localeID, char *name, int32_t nameCapacity, UErrorCode *err)
Gets the full name for the specified locale.
UAcceptResult
UAcceptResult
enums for the 'outResult' parameter return value
Definition: uloc.h:1042
uenum.h
C API: String Enumeration.
uloc_toUnicodeLocaleType
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...
uloc_getDisplayCountry
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.