X-Git-Url: https://git.saurik.com/apple/icu.git/blobdiff_plain/f59164e3d128c7675a4d3934206346a3384e53a5..f3c0d7a59d99c2a94c6b8822291f0e42be3773c9:/icuSources/common/unicode/uloc.h?ds=sidebyside diff --git a/icuSources/common/unicode/uloc.h b/icuSources/common/unicode/uloc.h index a96b1cd8..bc1d74fc 100644 --- a/icuSources/common/unicode/uloc.h +++ b/icuSources/common/unicode/uloc.h @@ -1,3 +1,5 @@ +// © 2016 and later: Unicode, Inc. and others. +// License & terms of use: http://www.unicode.org/copyright.html /* ********************************************************************** * Copyright (C) 1997-2016, International Business Machines @@ -59,7 +61,7 @@ * http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt * *

- * The second option includes an additonal ISO Country + * The second option includes an additional ISO Country * Code. These codes are the upper-case two-letter codes * as defined by ISO-3166. * You can find a full list of these codes at a number of sites, such as: @@ -67,7 +69,7 @@ * http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html * *

- * The third option requires another additonal information--the + * The third option requires another additional information--the * Variant. * The Variant codes are vendor and browser-specific. * For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX. @@ -155,7 +157,7 @@ * just a mechanism for identifying these services. * *

- * Each international serivce that performs locale-sensitive operations + * Each international service that performs locale-sensitive operations * allows you * to get all the available objects of that type. You can sift * through these objects by language, country, or variant, @@ -348,10 +350,14 @@ typedef enum { * @deprecated ICU 2.8 */ ULOC_REQUESTED_LOCALE = 2, -#endif /* U_HIDE_DEPRECATED_API */ - ULOC_DATA_LOCALE_TYPE_LIMIT = 3 -} ULocDataLocaleType ; + /** + * One more than the highest normal ULocDataLocaleType value. + * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. + */ + ULOC_DATA_LOCALE_TYPE_LIMIT = 3 +#endif // U_HIDE_DEPRECATED_API +} ULocDataLocaleType; #ifndef U_HIDE_SYSTEM_API /** @@ -533,6 +539,9 @@ uloc_getISO3Country(const char* localeID); * Gets the Win32 LCID value for the specified locale. * If the ICU locale is not recognized by Windows, 0 will be returned. * + * LCIDs were deprecated with Windows Vista and Microsoft recommends + * that developers use BCP47 style tags instead (uloc_toLanguageTag). + * * @param localeID the locale to get the Win32 LCID value with * @return country the Win32 LCID for localeID * @stable ICU 2.0 @@ -571,7 +580,7 @@ uloc_getDisplayLanguage(const char* locale, * if the locale's language code is "en", passing Locale::getFrench() for * inLocale would result in "", while passing Locale::getGerman() * for inLocale would result in "". NULL may be used to specify the default. - * @param script the displayable country code for localeID + * @param script the displayable script for the localeID * @param scriptCapacity the size of the script buffer to store the * displayable script code with * @param status error information if retrieving the displayable script code failed @@ -847,10 +856,12 @@ uloc_openKeywords(const char* localeID, * Get the value for a keyword. Locale name does not need to be normalized. * * @param localeID locale name containing the keyword ("de_DE@currency=EURO;collation=PHONEBOOK") - * @param keywordName name of the keyword for which we want the value. Case insensitive. + * @param keywordName name of the keyword for which we want the value; must not be + * NULL or empty, and must consist only of [A-Za-z0-9]. Case insensitive. * @param buffer receiving buffer * @param bufferCapacity capacity of receiving buffer - * @param status containing error code - buffer not big enough. + * @param status containing error code: e.g. buffer not big enough or ill-formed localeID + * or keywordName parameters. * @return the length of keyword value * @stable ICU 2.8 */ @@ -867,18 +878,26 @@ uloc_getKeywordValue(const char* localeID, * For removing all keywords, use uloc_getBaseName(). * * NOTE: Unlike almost every other ICU function which takes a - * buffer, this function will NOT truncate the output text. If a - * BUFFER_OVERFLOW_ERROR is received, it means that the original - * buffer is untouched. This is done to prevent incorrect or possibly - * even malformed locales from being generated and used. + * buffer, this function will NOT truncate the output text, and will + * not update the buffer with unterminated text setting a status of + * U_STRING_NOT_TERMINATED_WARNING. If a BUFFER_OVERFLOW_ERROR is received, + * it means a terminated version of the updated locale ID would not fit + * in the buffer, and the original buffer is untouched. This is done to + * prevent incorrect or possibly even malformed locales from being generated + * and used. * - * @param keywordName name of the keyword to be set. Case insensitive. + * @param keywordName name of the keyword to be set; must not be + * NULL or empty, and must consist only of [A-Za-z0-9]. Case insensitive. * @param keywordValue value of the keyword to be set. If 0-length or - * NULL, will result in the keyword being removed. No error is given if - * that keyword does not exist. - * @param buffer input buffer containing locale to be modified. + * NULL, will result in the keyword being removed; no error is given if + * that keyword does not exist. Otherwise, must consist only of + * [A-Za-z0-9] and [/_+-]. + * @param buffer input buffer containing well-formed locale ID to be + * modified. * @param bufferCapacity capacity of receiving buffer - * @param status containing error code - buffer not big enough. + * @param status containing error code: e.g. buffer not big enough + * or ill-formed keywordName or keywordValue parameters, or ill-formed + * locale ID in buffer on input. * @return the length needed for the buffer * @see uloc_getKeywordValue * @stable ICU 3.2