1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/uloc.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,1135 @@
1.4 +/*
1.5 +**********************************************************************
1.6 +* Copyright (C) 1997-2013, International Business Machines
1.7 +* Corporation and others. All Rights Reserved.
1.8 +**********************************************************************
1.9 +*
1.10 +* File ULOC.H
1.11 +*
1.12 +* Modification History:
1.13 +*
1.14 +* Date Name Description
1.15 +* 04/01/97 aliu Creation.
1.16 +* 08/22/98 stephen JDK 1.2 sync.
1.17 +* 12/08/98 rtg New C API for Locale
1.18 +* 03/30/99 damiba overhaul
1.19 +* 03/31/99 helena Javadoc for uloc functions.
1.20 +* 04/15/99 Madhu Updated Javadoc
1.21 +********************************************************************************
1.22 +*/
1.23 +
1.24 +#ifndef ULOC_H
1.25 +#define ULOC_H
1.26 +
1.27 +#include "unicode/utypes.h"
1.28 +#include "unicode/uenum.h"
1.29 +
1.30 +/**
1.31 + * \file
1.32 + * \brief C API: Locale
1.33 + *
1.34 + * <h2> ULoc C API for Locale </h2>
1.35 + * A <code>Locale</code> represents a specific geographical, political,
1.36 + * or cultural region. An operation that requires a <code>Locale</code> to perform
1.37 + * its task is called <em>locale-sensitive</em> and uses the <code>Locale</code>
1.38 + * to tailor information for the user. For example, displaying a number
1.39 + * is a locale-sensitive operation--the number should be formatted
1.40 + * according to the customs/conventions of the user's native country,
1.41 + * region, or culture. In the C APIs, a locales is simply a const char string.
1.42 + *
1.43 + * <P>
1.44 + * You create a <code>Locale</code> with one of the three options listed below.
1.45 + * Each of the component is separated by '_' in the locale string.
1.46 + * \htmlonly<blockquote>\endhtmlonly
1.47 + * <pre>
1.48 + * \code
1.49 + * newLanguage
1.50 + *
1.51 + * newLanguage + newCountry
1.52 + *
1.53 + * newLanguage + newCountry + newVariant
1.54 + * \endcode
1.55 + * </pre>
1.56 + * \htmlonly</blockquote>\endhtmlonly
1.57 + * The first option is a valid <STRONG>ISO
1.58 + * Language Code.</STRONG> These codes are the lower-case two-letter
1.59 + * codes as defined by ISO-639.
1.60 + * You can find a full list of these codes at a number of sites, such as:
1.61 + * <BR><a href ="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt">
1.62 + * http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt</a>
1.63 + *
1.64 + * <P>
1.65 + * The second option includes an additonal <STRONG>ISO Country
1.66 + * Code.</STRONG> These codes are the upper-case two-letter codes
1.67 + * as defined by ISO-3166.
1.68 + * You can find a full list of these codes at a number of sites, such as:
1.69 + * <BR><a href="http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html">
1.70 + * http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html</a>
1.71 + *
1.72 + * <P>
1.73 + * The third option requires another additonal information--the
1.74 + * <STRONG>Variant.</STRONG>
1.75 + * The Variant codes are vendor and browser-specific.
1.76 + * For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX.
1.77 + * Where there are two variants, separate them with an underscore, and
1.78 + * put the most important one first. For
1.79 + * example, a Traditional Spanish collation might be referenced, with
1.80 + * "ES", "ES", "Traditional_WIN".
1.81 + *
1.82 + * <P>
1.83 + * Because a <code>Locale</code> is just an identifier for a region,
1.84 + * no validity check is performed when you specify a <code>Locale</code>.
1.85 + * If you want to see whether particular resources are available for the
1.86 + * <code>Locale</code> you asked for, you must query those resources. For
1.87 + * example, ask the <code>UNumberFormat</code> for the locales it supports
1.88 + * using its <code>getAvailable</code> method.
1.89 + * <BR><STRONG>Note:</STRONG> When you ask for a resource for a particular
1.90 + * locale, you get back the best available match, not necessarily
1.91 + * precisely what you asked for. For more information, look at
1.92 + * <code>UResourceBundle</code>.
1.93 + *
1.94 + * <P>
1.95 + * The <code>Locale</code> provides a number of convenient constants
1.96 + * that you can use to specify the commonly used
1.97 + * locales. For example, the following refers to a locale
1.98 + * for the United States:
1.99 + * \htmlonly<blockquote>\endhtmlonly
1.100 + * <pre>
1.101 + * \code
1.102 + * ULOC_US
1.103 + * \endcode
1.104 + * </pre>
1.105 + * \htmlonly</blockquote>\endhtmlonly
1.106 + *
1.107 + * <P>
1.108 + * Once you've specified a locale you can query it for information about
1.109 + * itself. Use <code>uloc_getCountry</code> to get the ISO Country Code and
1.110 + * <code>uloc_getLanguage</code> to get the ISO Language Code. You can
1.111 + * use <code>uloc_getDisplayCountry</code> to get the
1.112 + * name of the country suitable for displaying to the user. Similarly,
1.113 + * you can use <code>uloc_getDisplayLanguage</code> to get the name of
1.114 + * the language suitable for displaying to the user. Interestingly,
1.115 + * the <code>uloc_getDisplayXXX</code> methods are themselves locale-sensitive
1.116 + * and have two versions: one that uses the default locale and one
1.117 + * that takes a locale as an argument and displays the name or country in
1.118 + * a language appropriate to that locale.
1.119 + *
1.120 + * <P>
1.121 + * The ICU provides a number of services that perform locale-sensitive
1.122 + * operations. For example, the <code>unum_xxx</code> functions format
1.123 + * numbers, currency, or percentages in a locale-sensitive manner.
1.124 + * </P>
1.125 + * \htmlonly<blockquote>\endhtmlonly
1.126 + * <pre>
1.127 + * \code
1.128 + * UErrorCode success = U_ZERO_ERROR;
1.129 + * UNumberFormat *nf;
1.130 + * const char* myLocale = "fr_FR";
1.131 + *
1.132 + * nf = unum_open( UNUM_DEFAULT, NULL, success );
1.133 + * unum_close(nf);
1.134 + * nf = unum_open( UNUM_CURRENCY, NULL, success );
1.135 + * unum_close(nf);
1.136 + * nf = unum_open( UNUM_PERCENT, NULL, success );
1.137 + * unum_close(nf);
1.138 + * \endcode
1.139 + * </pre>
1.140 + * \htmlonly</blockquote>\endhtmlonly
1.141 + * Each of these methods has two variants; one with an explicit locale
1.142 + * and one without; the latter using the default locale.
1.143 + * \htmlonly<blockquote>\endhtmlonly
1.144 + * <pre>
1.145 + * \code
1.146 + *
1.147 + * nf = unum_open( UNUM_DEFAULT, myLocale, success );
1.148 + * unum_close(nf);
1.149 + * nf = unum_open( UNUM_CURRENCY, myLocale, success );
1.150 + * unum_close(nf);
1.151 + * nf = unum_open( UNUM_PERCENT, myLocale, success );
1.152 + * unum_close(nf);
1.153 + * \endcode
1.154 + * </pre>
1.155 + * \htmlonly</blockquote>\endhtmlonly
1.156 + * A <code>Locale</code> is the mechanism for identifying the kind of services
1.157 + * (<code>UNumberFormat</code>) that you would like to get. The locale is
1.158 + * <STRONG>just</STRONG> a mechanism for identifying these services.
1.159 + *
1.160 + * <P>
1.161 + * Each international serivce that performs locale-sensitive operations
1.162 + * allows you
1.163 + * to get all the available objects of that type. You can sift
1.164 + * through these objects by language, country, or variant,
1.165 + * and use the display names to present a menu to the user.
1.166 + * For example, you can create a menu of all the collation objects
1.167 + * suitable for a given language. Such classes implement these
1.168 + * three class methods:
1.169 + * \htmlonly<blockquote>\endhtmlonly
1.170 + * <pre>
1.171 + * \code
1.172 + * const char* uloc_getAvailable(int32_t index);
1.173 + * int32_t uloc_countAvailable();
1.174 + * int32_t
1.175 + * uloc_getDisplayName(const char* localeID,
1.176 + * const char* inLocaleID,
1.177 + * UChar* result,
1.178 + * int32_t maxResultSize,
1.179 + * UErrorCode* err);
1.180 + *
1.181 + * \endcode
1.182 + * </pre>
1.183 + * \htmlonly</blockquote>\endhtmlonly
1.184 + * <P>
1.185 + * Concerning POSIX/RFC1766 Locale IDs,
1.186 + * the getLanguage/getCountry/getVariant/getName functions do understand
1.187 + * the POSIX type form of language_COUNTRY.ENCODING\@VARIANT
1.188 + * and if there is not an ICU-stype variant, uloc_getVariant() for example
1.189 + * will return the one listed after the \@at sign. As well, the hyphen
1.190 + * "-" is recognized as a country/variant separator similarly to RFC1766.
1.191 + * So for example, "en-us" will be interpreted as en_US.
1.192 + * As a result, uloc_getName() is far from a no-op, and will have the
1.193 + * effect of converting POSIX/RFC1766 IDs into ICU form, although it does
1.194 + * NOT map any of the actual codes (i.e. russian->ru) in any way.
1.195 + * Applications should call uloc_getName() at the point where a locale ID
1.196 + * is coming from an external source (user entry, OS, web browser)
1.197 + * and pass the resulting string to other ICU functions. For example,
1.198 + * don't use de-de\@EURO as an argument to resourcebundle.
1.199 + *
1.200 + * @see UResourceBundle
1.201 + */
1.202 +
1.203 +/** Useful constant for this language. @stable ICU 2.0 */
1.204 +#define ULOC_CHINESE "zh"
1.205 +/** Useful constant for this language. @stable ICU 2.0 */
1.206 +#define ULOC_ENGLISH "en"
1.207 +/** Useful constant for this language. @stable ICU 2.0 */
1.208 +#define ULOC_FRENCH "fr"
1.209 +/** Useful constant for this language. @stable ICU 2.0 */
1.210 +#define ULOC_GERMAN "de"
1.211 +/** Useful constant for this language. @stable ICU 2.0 */
1.212 +#define ULOC_ITALIAN "it"
1.213 +/** Useful constant for this language. @stable ICU 2.0 */
1.214 +#define ULOC_JAPANESE "ja"
1.215 +/** Useful constant for this language. @stable ICU 2.0 */
1.216 +#define ULOC_KOREAN "ko"
1.217 +/** Useful constant for this language. @stable ICU 2.0 */
1.218 +#define ULOC_SIMPLIFIED_CHINESE "zh_CN"
1.219 +/** Useful constant for this language. @stable ICU 2.0 */
1.220 +#define ULOC_TRADITIONAL_CHINESE "zh_TW"
1.221 +
1.222 +/** Useful constant for this country/region. @stable ICU 2.0 */
1.223 +#define ULOC_CANADA "en_CA"
1.224 +/** Useful constant for this country/region. @stable ICU 2.0 */
1.225 +#define ULOC_CANADA_FRENCH "fr_CA"
1.226 +/** Useful constant for this country/region. @stable ICU 2.0 */
1.227 +#define ULOC_CHINA "zh_CN"
1.228 +/** Useful constant for this country/region. @stable ICU 2.0 */
1.229 +#define ULOC_PRC "zh_CN"
1.230 +/** Useful constant for this country/region. @stable ICU 2.0 */
1.231 +#define ULOC_FRANCE "fr_FR"
1.232 +/** Useful constant for this country/region. @stable ICU 2.0 */
1.233 +#define ULOC_GERMANY "de_DE"
1.234 +/** Useful constant for this country/region. @stable ICU 2.0 */
1.235 +#define ULOC_ITALY "it_IT"
1.236 +/** Useful constant for this country/region. @stable ICU 2.0 */
1.237 +#define ULOC_JAPAN "ja_JP"
1.238 +/** Useful constant for this country/region. @stable ICU 2.0 */
1.239 +#define ULOC_KOREA "ko_KR"
1.240 +/** Useful constant for this country/region. @stable ICU 2.0 */
1.241 +#define ULOC_TAIWAN "zh_TW"
1.242 +/** Useful constant for this country/region. @stable ICU 2.0 */
1.243 +#define ULOC_UK "en_GB"
1.244 +/** Useful constant for this country/region. @stable ICU 2.0 */
1.245 +#define ULOC_US "en_US"
1.246 +
1.247 +/**
1.248 + * Useful constant for the maximum size of the language part of a locale ID.
1.249 + * (including the terminating NULL).
1.250 + * @stable ICU 2.0
1.251 + */
1.252 +#define ULOC_LANG_CAPACITY 12
1.253 +
1.254 +/**
1.255 + * Useful constant for the maximum size of the country part of a locale ID
1.256 + * (including the terminating NULL).
1.257 + * @stable ICU 2.0
1.258 + */
1.259 +#define ULOC_COUNTRY_CAPACITY 4
1.260 +/**
1.261 + * Useful constant for the maximum size of the whole locale ID
1.262 + * (including the terminating NULL and all keywords).
1.263 + * @stable ICU 2.0
1.264 + */
1.265 +#define ULOC_FULLNAME_CAPACITY 157
1.266 +
1.267 +/**
1.268 + * Useful constant for the maximum size of the script part of a locale ID
1.269 + * (including the terminating NULL).
1.270 + * @stable ICU 2.8
1.271 + */
1.272 +#define ULOC_SCRIPT_CAPACITY 6
1.273 +
1.274 +/**
1.275 + * Useful constant for the maximum size of keywords in a locale
1.276 + * @stable ICU 2.8
1.277 + */
1.278 +#define ULOC_KEYWORDS_CAPACITY 50
1.279 +
1.280 +/**
1.281 + * Useful constant for the maximum total size of keywords and their values in a locale
1.282 + * @stable ICU 2.8
1.283 + */
1.284 +#define ULOC_KEYWORD_AND_VALUES_CAPACITY 100
1.285 +
1.286 +/**
1.287 + * Invariant character separating keywords from the locale string
1.288 + * @stable ICU 2.8
1.289 + */
1.290 +#define ULOC_KEYWORD_SEPARATOR '@'
1.291 +
1.292 +/**
1.293 + * Unicode code point for '@' separating keywords from the locale string.
1.294 + * @see ULOC_KEYWORD_SEPARATOR
1.295 + * @stable ICU 4.6
1.296 + */
1.297 +#define ULOC_KEYWORD_SEPARATOR_UNICODE 0x40
1.298 +
1.299 +/**
1.300 + * Invariant character for assigning value to a keyword
1.301 + * @stable ICU 2.8
1.302 + */
1.303 +#define ULOC_KEYWORD_ASSIGN '='
1.304 +
1.305 +/**
1.306 + * Unicode code point for '=' for assigning value to a keyword.
1.307 + * @see ULOC_KEYWORD_ASSIGN
1.308 + * @stable ICU 4.6
1.309 + */
1.310 +#define ULOC_KEYWORD_ASSIGN_UNICODE 0x3D
1.311 +
1.312 +/**
1.313 + * Invariant character separating keywords
1.314 + * @stable ICU 2.8
1.315 + */
1.316 +#define ULOC_KEYWORD_ITEM_SEPARATOR ';'
1.317 +
1.318 +/**
1.319 + * Unicode code point for ';' separating keywords
1.320 + * @see ULOC_KEYWORD_ITEM_SEPARATOR
1.321 + * @stable ICU 4.6
1.322 + */
1.323 +#define ULOC_KEYWORD_ITEM_SEPARATOR_UNICODE 0x3B
1.324 +
1.325 +/**
1.326 + * Constants for *_getLocale()
1.327 + * Allow user to select whether she wants information on
1.328 + * requested, valid or actual locale.
1.329 + * For example, a collator for "en_US_CALIFORNIA" was
1.330 + * requested. In the current state of ICU (2.0),
1.331 + * the requested locale is "en_US_CALIFORNIA",
1.332 + * the valid locale is "en_US" (most specific locale supported by ICU)
1.333 + * and the actual locale is "root" (the collation data comes unmodified
1.334 + * from the UCA)
1.335 + * The locale is considered supported by ICU if there is a core ICU bundle
1.336 + * for that locale (although it may be empty).
1.337 + * @stable ICU 2.1
1.338 + */
1.339 +typedef enum {
1.340 + /** This is locale the data actually comes from
1.341 + * @stable ICU 2.1
1.342 + */
1.343 + ULOC_ACTUAL_LOCALE = 0,
1.344 + /** This is the most specific locale supported by ICU
1.345 + * @stable ICU 2.1
1.346 + */
1.347 + ULOC_VALID_LOCALE = 1,
1.348 +
1.349 +#ifndef U_HIDE_DEPRECATED_API
1.350 + /** This is the requested locale
1.351 + * @deprecated ICU 2.8
1.352 + */
1.353 + ULOC_REQUESTED_LOCALE = 2,
1.354 +#endif /* U_HIDE_DEPRECATED_API */
1.355 +
1.356 + ULOC_DATA_LOCALE_TYPE_LIMIT = 3
1.357 +} ULocDataLocaleType ;
1.358 +
1.359 +#ifndef U_HIDE_SYSTEM_API
1.360 +/**
1.361 + * Gets ICU's default locale.
1.362 + * The returned string is a snapshot in time, and will remain valid
1.363 + * and unchanged even when uloc_setDefault() is called.
1.364 + * The returned storage is owned by ICU, and must not be altered or deleted
1.365 + * by the caller.
1.366 + *
1.367 + * @return the ICU default locale
1.368 + * @system
1.369 + * @stable ICU 2.0
1.370 + */
1.371 +U_STABLE const char* U_EXPORT2
1.372 +uloc_getDefault(void);
1.373 +
1.374 +/**
1.375 + * Sets ICU's default locale.
1.376 + * By default (without calling this function), ICU's default locale will be based
1.377 + * on information obtained from the underlying system environment.
1.378 + * <p>
1.379 + * Changes to ICU's default locale do not propagate back to the
1.380 + * system environment.
1.381 + * <p>
1.382 + * Changes to ICU's default locale to not affect any ICU services that
1.383 + * may already be open based on the previous default locale value.
1.384 + *
1.385 + * @param localeID the new ICU default locale. A value of NULL will try to get
1.386 + * the system's default locale.
1.387 + * @param status the error information if the setting of default locale fails
1.388 + * @system
1.389 + * @stable ICU 2.0
1.390 + */
1.391 +U_STABLE void U_EXPORT2
1.392 +uloc_setDefault(const char* localeID,
1.393 + UErrorCode* status);
1.394 +#endif /* U_HIDE_SYSTEM_API */
1.395 +
1.396 +/**
1.397 + * Gets the language code for the specified locale.
1.398 + *
1.399 + * @param localeID the locale to get the ISO language code with
1.400 + * @param language the language code for localeID
1.401 + * @param languageCapacity the size of the language buffer to store the
1.402 + * language code with
1.403 + * @param err error information if retrieving the language code failed
1.404 + * @return the actual buffer size needed for the language code. If it's greater
1.405 + * than languageCapacity, the returned language code will be truncated.
1.406 + * @stable ICU 2.0
1.407 + */
1.408 +U_STABLE int32_t U_EXPORT2
1.409 +uloc_getLanguage(const char* localeID,
1.410 + char* language,
1.411 + int32_t languageCapacity,
1.412 + UErrorCode* err);
1.413 +
1.414 +/**
1.415 + * Gets the script code for the specified locale.
1.416 + *
1.417 + * @param localeID the locale to get the ISO language code with
1.418 + * @param script the language code for localeID
1.419 + * @param scriptCapacity the size of the language buffer to store the
1.420 + * language code with
1.421 + * @param err error information if retrieving the language code failed
1.422 + * @return the actual buffer size needed for the language code. If it's greater
1.423 + * than scriptCapacity, the returned language code will be truncated.
1.424 + * @stable ICU 2.8
1.425 + */
1.426 +U_STABLE int32_t U_EXPORT2
1.427 +uloc_getScript(const char* localeID,
1.428 + char* script,
1.429 + int32_t scriptCapacity,
1.430 + UErrorCode* err);
1.431 +
1.432 +/**
1.433 + * Gets the country code for the specified locale.
1.434 + *
1.435 + * @param localeID the locale to get the country code with
1.436 + * @param country the country code for localeID
1.437 + * @param countryCapacity the size of the country buffer to store the
1.438 + * country code with
1.439 + * @param err error information if retrieving the country code failed
1.440 + * @return the actual buffer size needed for the country code. If it's greater
1.441 + * than countryCapacity, the returned country code will be truncated.
1.442 + * @stable ICU 2.0
1.443 + */
1.444 +U_STABLE int32_t U_EXPORT2
1.445 +uloc_getCountry(const char* localeID,
1.446 + char* country,
1.447 + int32_t countryCapacity,
1.448 + UErrorCode* err);
1.449 +
1.450 +/**
1.451 + * Gets the variant code for the specified locale.
1.452 + *
1.453 + * @param localeID the locale to get the variant code with
1.454 + * @param variant the variant code for localeID
1.455 + * @param variantCapacity the size of the variant buffer to store the
1.456 + * variant code with
1.457 + * @param err error information if retrieving the variant code failed
1.458 + * @return the actual buffer size needed for the variant code. If it's greater
1.459 + * than variantCapacity, the returned variant code will be truncated.
1.460 + * @stable ICU 2.0
1.461 + */
1.462 +U_STABLE int32_t U_EXPORT2
1.463 +uloc_getVariant(const char* localeID,
1.464 + char* variant,
1.465 + int32_t variantCapacity,
1.466 + UErrorCode* err);
1.467 +
1.468 +
1.469 +/**
1.470 + * Gets the full name for the specified locale.
1.471 + * Note: This has the effect of 'canonicalizing' the ICU locale ID to
1.472 + * a certain extent. Upper and lower case are set as needed.
1.473 + * It does NOT map aliased names in any way.
1.474 + * See the top of this header file.
1.475 + * This API supports preflighting.
1.476 + *
1.477 + * @param localeID the locale to get the full name with
1.478 + * @param name fill in buffer for the name without keywords.
1.479 + * @param nameCapacity capacity of the fill in buffer.
1.480 + * @param err error information if retrieving the full name failed
1.481 + * @return the actual buffer size needed for the full name. If it's greater
1.482 + * than nameCapacity, the returned full name will be truncated.
1.483 + * @stable ICU 2.0
1.484 + */
1.485 +U_STABLE int32_t U_EXPORT2
1.486 +uloc_getName(const char* localeID,
1.487 + char* name,
1.488 + int32_t nameCapacity,
1.489 + UErrorCode* err);
1.490 +
1.491 +/**
1.492 + * Gets the full name for the specified locale.
1.493 + * Note: This has the effect of 'canonicalizing' the string to
1.494 + * a certain extent. Upper and lower case are set as needed,
1.495 + * and if the components were in 'POSIX' format they are changed to
1.496 + * ICU format. It does NOT map aliased names in any way.
1.497 + * See the top of this header file.
1.498 + *
1.499 + * @param localeID the locale to get the full name with
1.500 + * @param name the full name for localeID
1.501 + * @param nameCapacity the size of the name buffer to store the
1.502 + * full name with
1.503 + * @param err error information if retrieving the full name failed
1.504 + * @return the actual buffer size needed for the full name. If it's greater
1.505 + * than nameCapacity, the returned full name will be truncated.
1.506 + * @stable ICU 2.8
1.507 + */
1.508 +U_STABLE int32_t U_EXPORT2
1.509 +uloc_canonicalize(const char* localeID,
1.510 + char* name,
1.511 + int32_t nameCapacity,
1.512 + UErrorCode* err);
1.513 +
1.514 +/**
1.515 + * Gets the ISO language code for the specified locale.
1.516 + *
1.517 + * @param localeID the locale to get the ISO language code with
1.518 + * @return language the ISO language code for localeID
1.519 + * @stable ICU 2.0
1.520 + */
1.521 +U_STABLE const char* U_EXPORT2
1.522 +uloc_getISO3Language(const char* localeID);
1.523 +
1.524 +
1.525 +/**
1.526 + * Gets the ISO country code for the specified locale.
1.527 + *
1.528 + * @param localeID the locale to get the ISO country code with
1.529 + * @return country the ISO country code for localeID
1.530 + * @stable ICU 2.0
1.531 + */
1.532 +U_STABLE const char* U_EXPORT2
1.533 +uloc_getISO3Country(const char* localeID);
1.534 +
1.535 +/**
1.536 + * Gets the Win32 LCID value for the specified locale.
1.537 + * If the ICU locale is not recognized by Windows, 0 will be returned.
1.538 + *
1.539 + * @param localeID the locale to get the Win32 LCID value with
1.540 + * @return country the Win32 LCID for localeID
1.541 + * @stable ICU 2.0
1.542 + */
1.543 +U_STABLE uint32_t U_EXPORT2
1.544 +uloc_getLCID(const char* localeID);
1.545 +
1.546 +/**
1.547 + * Gets the language name suitable for display for the specified locale.
1.548 + *
1.549 + * @param locale the locale to get the ISO language code with
1.550 + * @param displayLocale Specifies the locale to be used to display the name. In other words,
1.551 + * if the locale's language code is "en", passing Locale::getFrench() for
1.552 + * inLocale would result in "Anglais", while passing Locale::getGerman()
1.553 + * for inLocale would result in "Englisch".
1.554 + * @param language the displayable language code for localeID
1.555 + * @param languageCapacity the size of the language buffer to store the
1.556 + * displayable language code with
1.557 + * @param status error information if retrieving the displayable language code failed
1.558 + * @return the actual buffer size needed for the displayable language code. If it's greater
1.559 + * than languageCapacity, the returned language code will be truncated.
1.560 + * @stable ICU 2.0
1.561 + */
1.562 +U_STABLE int32_t U_EXPORT2
1.563 +uloc_getDisplayLanguage(const char* locale,
1.564 + const char* displayLocale,
1.565 + UChar* language,
1.566 + int32_t languageCapacity,
1.567 + UErrorCode* status);
1.568 +
1.569 +/**
1.570 + * Gets the script name suitable for display for the specified locale.
1.571 + *
1.572 + * @param locale the locale to get the displayable script code with. NULL may be used to specify the default.
1.573 + * @param displayLocale Specifies the locale to be used to display the name. In other words,
1.574 + * if the locale's language code is "en", passing Locale::getFrench() for
1.575 + * inLocale would result in "", while passing Locale::getGerman()
1.576 + * for inLocale would result in "". NULL may be used to specify the default.
1.577 + * @param script the displayable country code for localeID
1.578 + * @param scriptCapacity the size of the script buffer to store the
1.579 + * displayable script code with
1.580 + * @param status error information if retrieving the displayable script code failed
1.581 + * @return the actual buffer size needed for the displayable script code. If it's greater
1.582 + * than scriptCapacity, the returned displayable script code will be truncated.
1.583 + * @stable ICU 2.8
1.584 + */
1.585 +U_STABLE int32_t U_EXPORT2
1.586 +uloc_getDisplayScript(const char* locale,
1.587 + const char* displayLocale,
1.588 + UChar* script,
1.589 + int32_t scriptCapacity,
1.590 + UErrorCode* status);
1.591 +
1.592 +/**
1.593 + * Gets the country name suitable for display for the specified locale.
1.594 + *
1.595 + * @param locale the locale to get the displayable country code with. NULL may be used to specify the default.
1.596 + * @param displayLocale Specifies the locale to be used to display the name. In other words,
1.597 + * if the locale's language code is "en", passing Locale::getFrench() for
1.598 + * inLocale would result in "Anglais", while passing Locale::getGerman()
1.599 + * for inLocale would result in "Englisch". NULL may be used to specify the default.
1.600 + * @param country the displayable country code for localeID
1.601 + * @param countryCapacity the size of the country buffer to store the
1.602 + * displayable country code with
1.603 + * @param status error information if retrieving the displayable country code failed
1.604 + * @return the actual buffer size needed for the displayable country code. If it's greater
1.605 + * than countryCapacity, the returned displayable country code will be truncated.
1.606 + * @stable ICU 2.0
1.607 + */
1.608 +U_STABLE int32_t U_EXPORT2
1.609 +uloc_getDisplayCountry(const char* locale,
1.610 + const char* displayLocale,
1.611 + UChar* country,
1.612 + int32_t countryCapacity,
1.613 + UErrorCode* status);
1.614 +
1.615 +
1.616 +/**
1.617 + * Gets the variant name suitable for display for the specified locale.
1.618 + *
1.619 + * @param locale the locale to get the displayable variant code with. NULL may be used to specify the default.
1.620 + * @param displayLocale Specifies the locale to be used to display the name. In other words,
1.621 + * if the locale's language code is "en", passing Locale::getFrench() for
1.622 + * inLocale would result in "Anglais", while passing Locale::getGerman()
1.623 + * for inLocale would result in "Englisch". NULL may be used to specify the default.
1.624 + * @param variant the displayable variant code for localeID
1.625 + * @param variantCapacity the size of the variant buffer to store the
1.626 + * displayable variant code with
1.627 + * @param status error information if retrieving the displayable variant code failed
1.628 + * @return the actual buffer size needed for the displayable variant code. If it's greater
1.629 + * than variantCapacity, the returned displayable variant code will be truncated.
1.630 + * @stable ICU 2.0
1.631 + */
1.632 +U_STABLE int32_t U_EXPORT2
1.633 +uloc_getDisplayVariant(const char* locale,
1.634 + const char* displayLocale,
1.635 + UChar* variant,
1.636 + int32_t variantCapacity,
1.637 + UErrorCode* status);
1.638 +
1.639 +/**
1.640 + * Gets the keyword name suitable for display for the specified locale.
1.641 + * E.g: for the locale string de_DE\@collation=PHONEBOOK, this API gets the display
1.642 + * string for the keyword collation.
1.643 + * Usage:
1.644 + * <code>
1.645 + * UErrorCode status = U_ZERO_ERROR;
1.646 + * const char* keyword =NULL;
1.647 + * int32_t keywordLen = 0;
1.648 + * int32_t keywordCount = 0;
1.649 + * UChar displayKeyword[256];
1.650 + * int32_t displayKeywordLen = 0;
1.651 + * UEnumeration* keywordEnum = uloc_openKeywords("de_DE@collation=PHONEBOOK;calendar=TRADITIONAL", &status);
1.652 + * for(keywordCount = uenum_count(keywordEnum, &status); keywordCount > 0 ; keywordCount--){
1.653 + * if(U_FAILURE(status)){
1.654 + * ...something went wrong so handle the error...
1.655 + * break;
1.656 + * }
1.657 + * // the uenum_next returns NUL terminated string
1.658 + * keyword = uenum_next(keywordEnum, &keywordLen, &status);
1.659 + * displayKeywordLen = uloc_getDisplayKeyword(keyword, "en_US", displayKeyword, 256);
1.660 + * ... do something interesting .....
1.661 + * }
1.662 + * uenum_close(keywordEnum);
1.663 + * </code>
1.664 + * @param keyword The keyword whose display string needs to be returned.
1.665 + * @param displayLocale Specifies the locale to be used to display the name. In other words,
1.666 + * if the locale's language code is "en", passing Locale::getFrench() for
1.667 + * inLocale would result in "Anglais", while passing Locale::getGerman()
1.668 + * for inLocale would result in "Englisch". NULL may be used to specify the default.
1.669 + * @param dest the buffer to which the displayable keyword should be written.
1.670 + * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1.671 + * dest may be NULL and the function will only return the length of the
1.672 + * result without writing any of the result string (pre-flighting).
1.673 + * @param status error information if retrieving the displayable string failed.
1.674 + * Should not be NULL and should not indicate failure on entry.
1.675 + * @return the actual buffer size needed for the displayable variant code.
1.676 + * @see #uloc_openKeywords
1.677 + * @stable ICU 2.8
1.678 + */
1.679 +U_STABLE int32_t U_EXPORT2
1.680 +uloc_getDisplayKeyword(const char* keyword,
1.681 + const char* displayLocale,
1.682 + UChar* dest,
1.683 + int32_t destCapacity,
1.684 + UErrorCode* status);
1.685 +/**
1.686 + * Gets the value of the keyword suitable for display for the specified locale.
1.687 + * E.g: for the locale string de_DE\@collation=PHONEBOOK, this API gets the display
1.688 + * string for PHONEBOOK, in the display locale, when "collation" is specified as the keyword.
1.689 + *
1.690 + * @param locale The locale to get the displayable variant code with. NULL may be used to specify the default.
1.691 + * @param keyword The keyword for whose value should be used.
1.692 + * @param displayLocale Specifies the locale to be used to display the name. In other words,
1.693 + * if the locale's language code is "en", passing Locale::getFrench() for
1.694 + * inLocale would result in "Anglais", while passing Locale::getGerman()
1.695 + * for inLocale would result in "Englisch". NULL may be used to specify the default.
1.696 + * @param dest the buffer to which the displayable keyword should be written.
1.697 + * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1.698 + * dest may be NULL and the function will only return the length of the
1.699 + * result without writing any of the result string (pre-flighting).
1.700 + * @param status error information if retrieving the displayable string failed.
1.701 + * Should not be NULL and must not indicate failure on entry.
1.702 + * @return the actual buffer size needed for the displayable variant code.
1.703 + * @stable ICU 2.8
1.704 + */
1.705 +U_STABLE int32_t U_EXPORT2
1.706 +uloc_getDisplayKeywordValue( const char* locale,
1.707 + const char* keyword,
1.708 + const char* displayLocale,
1.709 + UChar* dest,
1.710 + int32_t destCapacity,
1.711 + UErrorCode* status);
1.712 +/**
1.713 + * Gets the full name suitable for display for the specified locale.
1.714 + *
1.715 + * @param localeID the locale to get the displayable name with. NULL may be used to specify the default.
1.716 + * @param inLocaleID Specifies the locale to be used to display the name. In other words,
1.717 + * if the locale's language code is "en", passing Locale::getFrench() for
1.718 + * inLocale would result in "Anglais", while passing Locale::getGerman()
1.719 + * for inLocale would result in "Englisch". NULL may be used to specify the default.
1.720 + * @param result the displayable name for localeID
1.721 + * @param maxResultSize the size of the name buffer to store the
1.722 + * displayable full name with
1.723 + * @param err error information if retrieving the displayable name failed
1.724 + * @return the actual buffer size needed for the displayable name. If it's greater
1.725 + * than maxResultSize, the returned displayable name will be truncated.
1.726 + * @stable ICU 2.0
1.727 + */
1.728 +U_STABLE int32_t U_EXPORT2
1.729 +uloc_getDisplayName(const char* localeID,
1.730 + const char* inLocaleID,
1.731 + UChar* result,
1.732 + int32_t maxResultSize,
1.733 + UErrorCode* err);
1.734 +
1.735 +
1.736 +/**
1.737 + * Gets the specified locale from a list of all available locales.
1.738 + * The return value is a pointer to an item of
1.739 + * a locale name array. Both this array and the pointers
1.740 + * it contains are owned by ICU and should not be deleted or written through
1.741 + * by the caller. The locale name is terminated by a null pointer.
1.742 + * @param n the specific locale name index of the available locale list
1.743 + * @return a specified locale name of all available locales
1.744 + * @stable ICU 2.0
1.745 + */
1.746 +U_STABLE const char* U_EXPORT2
1.747 +uloc_getAvailable(int32_t n);
1.748 +
1.749 +/**
1.750 + * Gets the size of the all available locale list.
1.751 + *
1.752 + * @return the size of the locale list
1.753 + * @stable ICU 2.0
1.754 + */
1.755 +U_STABLE int32_t U_EXPORT2 uloc_countAvailable(void);
1.756 +
1.757 +/**
1.758 + *
1.759 + * Gets a list of all available 2-letter language codes defined in ISO 639,
1.760 + * plus additional 3-letter codes determined to be useful for locale generation as
1.761 + * defined by Unicode CLDR. This is a pointer
1.762 + * to an array of pointers to arrays of char. All of these pointers are owned
1.763 + * by ICU-- do not delete them, and do not write through them. The array is
1.764 + * terminated with a null pointer.
1.765 + * @return a list of all available language codes
1.766 + * @stable ICU 2.0
1.767 + */
1.768 +U_STABLE const char* const* U_EXPORT2
1.769 +uloc_getISOLanguages(void);
1.770 +
1.771 +/**
1.772 + *
1.773 + * Gets a list of all available 2-letter country codes defined in ISO 639. This is a
1.774 + * pointer to an array of pointers to arrays of char. All of these pointers are
1.775 + * owned by ICU-- do not delete them, and do not write through them. The array is
1.776 + * terminated with a null pointer.
1.777 + * @return a list of all available country codes
1.778 + * @stable ICU 2.0
1.779 + */
1.780 +U_STABLE const char* const* U_EXPORT2
1.781 +uloc_getISOCountries(void);
1.782 +
1.783 +/**
1.784 + * Truncate the locale ID string to get the parent locale ID.
1.785 + * Copies the part of the string before the last underscore.
1.786 + * The parent locale ID will be an empty string if there is no
1.787 + * underscore, or if there is only one underscore at localeID[0].
1.788 + *
1.789 + * @param localeID Input locale ID string.
1.790 + * @param parent Output string buffer for the parent locale ID.
1.791 + * @param parentCapacity Size of the output buffer.
1.792 + * @param err A UErrorCode value.
1.793 + * @return The length of the parent locale ID.
1.794 + * @stable ICU 2.0
1.795 + */
1.796 +U_STABLE int32_t U_EXPORT2
1.797 +uloc_getParent(const char* localeID,
1.798 + char* parent,
1.799 + int32_t parentCapacity,
1.800 + UErrorCode* err);
1.801 +
1.802 +
1.803 +
1.804 +
1.805 +/**
1.806 + * Gets the full name for the specified locale, like uloc_getName(),
1.807 + * but without keywords.
1.808 + *
1.809 + * Note: This has the effect of 'canonicalizing' the string to
1.810 + * a certain extent. Upper and lower case are set as needed,
1.811 + * and if the components were in 'POSIX' format they are changed to
1.812 + * ICU format. It does NOT map aliased names in any way.
1.813 + * See the top of this header file.
1.814 + *
1.815 + * This API strips off the keyword part, so "de_DE\@collation=phonebook"
1.816 + * will become "de_DE".
1.817 + * This API supports preflighting.
1.818 + *
1.819 + * @param localeID the locale to get the full name with
1.820 + * @param name fill in buffer for the name without keywords.
1.821 + * @param nameCapacity capacity of the fill in buffer.
1.822 + * @param err error information if retrieving the full name failed
1.823 + * @return the actual buffer size needed for the full name. If it's greater
1.824 + * than nameCapacity, the returned full name will be truncated.
1.825 + * @stable ICU 2.8
1.826 + */
1.827 +U_STABLE int32_t U_EXPORT2
1.828 +uloc_getBaseName(const char* localeID,
1.829 + char* name,
1.830 + int32_t nameCapacity,
1.831 + UErrorCode* err);
1.832 +
1.833 +/**
1.834 + * Gets an enumeration of keywords for the specified locale. Enumeration
1.835 + * must get disposed of by the client using uenum_close function.
1.836 + *
1.837 + * @param localeID the locale to get the variant code with
1.838 + * @param status error information if retrieving the keywords failed
1.839 + * @return enumeration of keywords or NULL if there are no keywords.
1.840 + * @stable ICU 2.8
1.841 + */
1.842 +U_STABLE UEnumeration* U_EXPORT2
1.843 +uloc_openKeywords(const char* localeID,
1.844 + UErrorCode* status);
1.845 +
1.846 +/**
1.847 + * Get the value for a keyword. Locale name does not need to be normalized.
1.848 + *
1.849 + * @param localeID locale name containing the keyword ("de_DE@currency=EURO;collation=PHONEBOOK")
1.850 + * @param keywordName name of the keyword for which we want the value. Case insensitive.
1.851 + * @param buffer receiving buffer
1.852 + * @param bufferCapacity capacity of receiving buffer
1.853 + * @param status containing error code - buffer not big enough.
1.854 + * @return the length of keyword value
1.855 + * @stable ICU 2.8
1.856 + */
1.857 +U_STABLE int32_t U_EXPORT2
1.858 +uloc_getKeywordValue(const char* localeID,
1.859 + const char* keywordName,
1.860 + char* buffer, int32_t bufferCapacity,
1.861 + UErrorCode* status);
1.862 +
1.863 +
1.864 +/**
1.865 + * Sets or removes the value of the specified keyword.
1.866 + *
1.867 + * For removing all keywords, use uloc_getBaseName().
1.868 + *
1.869 + * NOTE: Unlike almost every other ICU function which takes a
1.870 + * buffer, this function will NOT truncate the output text. If a
1.871 + * BUFFER_OVERFLOW_ERROR is received, it means that the original
1.872 + * buffer is untouched. This is done to prevent incorrect or possibly
1.873 + * even malformed locales from being generated and used.
1.874 + *
1.875 + * @param keywordName name of the keyword to be set. Case insensitive.
1.876 + * @param keywordValue value of the keyword to be set. If 0-length or
1.877 + * NULL, will result in the keyword being removed. No error is given if
1.878 + * that keyword does not exist.
1.879 + * @param buffer input buffer containing locale to be modified.
1.880 + * @param bufferCapacity capacity of receiving buffer
1.881 + * @param status containing error code - buffer not big enough.
1.882 + * @return the length needed for the buffer
1.883 + * @see uloc_getKeywordValue
1.884 + * @stable ICU 3.2
1.885 + */
1.886 +U_STABLE int32_t U_EXPORT2
1.887 +uloc_setKeywordValue(const char* keywordName,
1.888 + const char* keywordValue,
1.889 + char* buffer, int32_t bufferCapacity,
1.890 + UErrorCode* status);
1.891 +
1.892 +/**
1.893 + * enums for the return value for the character and line orientation
1.894 + * functions.
1.895 + * @stable ICU 4.0
1.896 + */
1.897 +typedef enum {
1.898 + ULOC_LAYOUT_LTR = 0, /* left-to-right. */
1.899 + ULOC_LAYOUT_RTL = 1, /* right-to-left. */
1.900 + ULOC_LAYOUT_TTB = 2, /* top-to-bottom. */
1.901 + ULOC_LAYOUT_BTT = 3, /* bottom-to-top. */
1.902 + ULOC_LAYOUT_UNKNOWN
1.903 +} ULayoutType;
1.904 +
1.905 +/**
1.906 + * Get the layout character orientation for the specified locale.
1.907 + *
1.908 + * @param localeId locale name
1.909 + * @param status Error status
1.910 + * @return an enum indicating the layout orientation for characters.
1.911 + * @stable ICU 4.0
1.912 + */
1.913 +U_STABLE ULayoutType U_EXPORT2
1.914 +uloc_getCharacterOrientation(const char* localeId,
1.915 + UErrorCode *status);
1.916 +
1.917 +/**
1.918 + * Get the layout line orientation for the specified locale.
1.919 + *
1.920 + * @param localeId locale name
1.921 + * @param status Error status
1.922 + * @return an enum indicating the layout orientation for lines.
1.923 + * @stable ICU 4.0
1.924 + */
1.925 +U_STABLE ULayoutType U_EXPORT2
1.926 +uloc_getLineOrientation(const char* localeId,
1.927 + UErrorCode *status);
1.928 +
1.929 +/**
1.930 + * enums for the 'outResult' parameter return value
1.931 + * @see uloc_acceptLanguageFromHTTP
1.932 + * @see uloc_acceptLanguage
1.933 + * @stable ICU 3.2
1.934 + */
1.935 +typedef enum {
1.936 + ULOC_ACCEPT_FAILED = 0, /* No exact match was found. */
1.937 + ULOC_ACCEPT_VALID = 1, /* An exact match was found. */
1.938 + ULOC_ACCEPT_FALLBACK = 2 /* A fallback was found, for example,
1.939 + Accept list contained 'ja_JP'
1.940 + which matched available locale 'ja'. */
1.941 +} UAcceptResult;
1.942 +
1.943 +
1.944 +/**
1.945 + * Based on a HTTP header from a web browser and a list of available locales,
1.946 + * determine an acceptable locale for the user.
1.947 + * @param result - buffer to accept the result locale
1.948 + * @param resultAvailable the size of the result buffer.
1.949 + * @param outResult - An out parameter that contains the fallback status
1.950 + * @param httpAcceptLanguage - "Accept-Language:" header as per HTTP.
1.951 + * @param availableLocales - list of available locales to match
1.952 + * @param status Error status, may be BUFFER_OVERFLOW_ERROR
1.953 + * @return length needed for the locale.
1.954 + * @stable ICU 3.2
1.955 + */
1.956 +U_STABLE int32_t U_EXPORT2
1.957 +uloc_acceptLanguageFromHTTP(char *result, int32_t resultAvailable,
1.958 + UAcceptResult *outResult,
1.959 + const char *httpAcceptLanguage,
1.960 + UEnumeration* availableLocales,
1.961 + UErrorCode *status);
1.962 +
1.963 +/**
1.964 + * Based on a list of available locales,
1.965 + * determine an acceptable locale for the user.
1.966 + * @param result - buffer to accept the result locale
1.967 + * @param resultAvailable the size of the result buffer.
1.968 + * @param outResult - An out parameter that contains the fallback status
1.969 + * @param acceptList - list of acceptable languages
1.970 + * @param acceptListCount - count of acceptList items
1.971 + * @param availableLocales - list of available locales to match
1.972 + * @param status Error status, may be BUFFER_OVERFLOW_ERROR
1.973 + * @return length needed for the locale.
1.974 + * @stable ICU 3.2
1.975 + */
1.976 +U_STABLE int32_t U_EXPORT2
1.977 +uloc_acceptLanguage(char *result, int32_t resultAvailable,
1.978 + UAcceptResult *outResult, const char **acceptList,
1.979 + int32_t acceptListCount,
1.980 + UEnumeration* availableLocales,
1.981 + UErrorCode *status);
1.982 +
1.983 +
1.984 +/**
1.985 + * Gets the ICU locale ID for the specified Win32 LCID value.
1.986 + *
1.987 + * @param hostID the Win32 LCID to translate
1.988 + * @param locale the output buffer for the ICU locale ID, which will be NUL-terminated
1.989 + * if there is room.
1.990 + * @param localeCapacity the size of the output buffer
1.991 + * @param status an error is returned if the LCID is unrecognized or the output buffer
1.992 + * is too small
1.993 + * @return actual the actual size of the locale ID, not including NUL-termination
1.994 + * @stable ICU 3.8
1.995 + */
1.996 +U_STABLE int32_t U_EXPORT2
1.997 +uloc_getLocaleForLCID(uint32_t hostID, char *locale, int32_t localeCapacity,
1.998 + UErrorCode *status);
1.999 +
1.1000 +
1.1001 +/**
1.1002 + * Add the likely subtags for a provided locale ID, per the algorithm described
1.1003 + * in the following CLDR technical report:
1.1004 + *
1.1005 + * http://www.unicode.org/reports/tr35/#Likely_Subtags
1.1006 + *
1.1007 + * If localeID is already in the maximal form, or there is no data available
1.1008 + * for maximization, it will be copied to the output buffer. For example,
1.1009 + * "und-Zzzz" cannot be maximized, since there is no reasonable maximization.
1.1010 + *
1.1011 + * Examples:
1.1012 + *
1.1013 + * "en" maximizes to "en_Latn_US"
1.1014 + *
1.1015 + * "de" maximizes to "de_Latn_US"
1.1016 + *
1.1017 + * "sr" maximizes to "sr_Cyrl_RS"
1.1018 + *
1.1019 + * "sh" maximizes to "sr_Latn_RS" (Note this will not reverse.)
1.1020 + *
1.1021 + * "zh_Hani" maximizes to "zh_Hans_CN" (Note this will not reverse.)
1.1022 + *
1.1023 + * @param localeID The locale to maximize
1.1024 + * @param maximizedLocaleID The maximized locale
1.1025 + * @param maximizedLocaleIDCapacity The capacity of the maximizedLocaleID buffer
1.1026 + * @param err Error information if maximizing the locale failed. If the length
1.1027 + * of the localeID and the null-terminator is greater than the maximum allowed size,
1.1028 + * or the localeId is not well-formed, the error code is U_ILLEGAL_ARGUMENT_ERROR.
1.1029 + * @return The actual buffer size needed for the maximized locale. If it's
1.1030 + * greater than maximizedLocaleIDCapacity, the returned ID will be truncated.
1.1031 + * On error, the return value is -1.
1.1032 + * @stable ICU 4.0
1.1033 + */
1.1034 +U_STABLE int32_t U_EXPORT2
1.1035 +uloc_addLikelySubtags(const char* localeID,
1.1036 + char* maximizedLocaleID,
1.1037 + int32_t maximizedLocaleIDCapacity,
1.1038 + UErrorCode* err);
1.1039 +
1.1040 +
1.1041 +/**
1.1042 + * Minimize the subtags for a provided locale ID, per the algorithm described
1.1043 + * in the following CLDR technical report:
1.1044 + *
1.1045 + * http://www.unicode.org/reports/tr35/#Likely_Subtags
1.1046 + *
1.1047 + * If localeID is already in the minimal form, or there is no data available
1.1048 + * for minimization, it will be copied to the output buffer. Since the
1.1049 + * minimization algorithm relies on proper maximization, see the comments
1.1050 + * for uloc_addLikelySubtags for reasons why there might not be any data.
1.1051 + *
1.1052 + * Examples:
1.1053 + *
1.1054 + * "en_Latn_US" minimizes to "en"
1.1055 + *
1.1056 + * "de_Latn_US" minimizes to "de"
1.1057 + *
1.1058 + * "sr_Cyrl_RS" minimizes to "sr"
1.1059 + *
1.1060 + * "zh_Hant_TW" minimizes to "zh_TW" (The region is preferred to the
1.1061 + * script, and minimizing to "zh" would imply "zh_Hans_CN".)
1.1062 + *
1.1063 + * @param localeID The locale to minimize
1.1064 + * @param minimizedLocaleID The minimized locale
1.1065 + * @param minimizedLocaleIDCapacity The capacity of the minimizedLocaleID buffer
1.1066 + * @param err Error information if minimizing the locale failed. If the length
1.1067 + * of the localeID and the null-terminator is greater than the maximum allowed size,
1.1068 + * or the localeId is not well-formed, the error code is U_ILLEGAL_ARGUMENT_ERROR.
1.1069 + * @return The actual buffer size needed for the minimized locale. If it's
1.1070 + * greater than minimizedLocaleIDCapacity, the returned ID will be truncated.
1.1071 + * On error, the return value is -1.
1.1072 + * @stable ICU 4.0
1.1073 + */
1.1074 +U_STABLE int32_t U_EXPORT2
1.1075 +uloc_minimizeSubtags(const char* localeID,
1.1076 + char* minimizedLocaleID,
1.1077 + int32_t minimizedLocaleIDCapacity,
1.1078 + UErrorCode* err);
1.1079 +
1.1080 +/**
1.1081 + * Returns a locale ID for the specified BCP47 language tag string.
1.1082 + * If the specified language tag contains any ill-formed subtags,
1.1083 + * the first such subtag and all following subtags are ignored.
1.1084 + * <p>
1.1085 + * This implements the 'Language-Tag' production of BCP47, and so
1.1086 + * supports grandfathered (regular and irregular) as well as private
1.1087 + * use language tags. Private use tags are represented as 'x-whatever',
1.1088 + * and grandfathered tags are converted to their canonical replacements
1.1089 + * where they exist. Note that a few grandfathered tags have no modern
1.1090 + * replacement, these will be converted using the fallback described in
1.1091 + * the first paragraph, so some information might be lost.
1.1092 + * @param langtag the input BCP47 language tag.
1.1093 + * @param localeID the output buffer receiving a locale ID for the
1.1094 + * specified BCP47 language tag.
1.1095 + * @param localeIDCapacity the size of the locale ID output buffer.
1.1096 + * @param parsedLength if not NULL, successfully parsed length
1.1097 + * for the input language tag is set.
1.1098 + * @param err error information if receiving the locald ID
1.1099 + * failed.
1.1100 + * @return the length of the locale ID.
1.1101 + * @stable ICU 4.2
1.1102 + */
1.1103 +U_STABLE int32_t U_EXPORT2
1.1104 +uloc_forLanguageTag(const char* langtag,
1.1105 + char* localeID,
1.1106 + int32_t localeIDCapacity,
1.1107 + int32_t* parsedLength,
1.1108 + UErrorCode* err);
1.1109 +
1.1110 +/**
1.1111 + * Returns a well-formed language tag for this locale ID.
1.1112 + * <p>
1.1113 + * <b>Note</b>: When <code>strict</code> is FALSE, any locale
1.1114 + * fields which do not satisfy the BCP47 syntax requirement will
1.1115 + * be omitted from the result. When <code>strict</code> is
1.1116 + * TRUE, this function sets U_ILLEGAL_ARGUMENT_ERROR to the
1.1117 + * <code>err</code> if any locale fields do not satisfy the
1.1118 + * BCP47 syntax requirement.
1.1119 + * @param localeID the input locale ID
1.1120 + * @param langtag the output buffer receiving BCP47 language
1.1121 + * tag for the locale ID.
1.1122 + * @param langtagCapacity the size of the BCP47 language tag
1.1123 + * output buffer.
1.1124 + * @param strict boolean value indicating if the function returns
1.1125 + * an error for an ill-formed input locale ID.
1.1126 + * @param err error information if receiving the language
1.1127 + * tag failed.
1.1128 + * @return The length of the BCP47 language tag.
1.1129 + * @stable ICU 4.2
1.1130 + */
1.1131 +U_STABLE int32_t U_EXPORT2
1.1132 +uloc_toLanguageTag(const char* localeID,
1.1133 + char* langtag,
1.1134 + int32_t langtagCapacity,
1.1135 + UBool strict,
1.1136 + UErrorCode* err);
1.1137 +
1.1138 +#endif /*_ULOC*/
