1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/textandloc/fontservices/textshaperplugin/IcuSource/common/unicode/uloc.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,920 @@
1.4 +/*
1.5 +**********************************************************************
1.6 +* Copyright (C) 1997-2005, 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).
1.263 + * @stable ICU 2.0
1.264 + */
1.265 +#define ULOC_FULLNAME_CAPACITY 56
1.266 +
1.267 +
1.268 +#ifndef U_HIDE_DRAFT_API
1.269 +
1.270 +/**
1.271 + * Useful constant for the maximum size of the script part of a locale ID
1.272 + * (including the terminating NULL).
1.273 + * @internal ICU 2.8
1.274 + */
1.275 +#define ULOC_SCRIPT_CAPACITY 6
1.276 +
1.277 +/**
1.278 + * Useful constant for the maximum size of keywords in a locale
1.279 + * @internal ICU 2.8
1.280 + */
1.281 +#define ULOC_KEYWORDS_CAPACITY 50
1.282 +
1.283 +/**
1.284 + * Useful constant for the maximum size of keywords in a locale
1.285 + * @internal ICU 2.8
1.286 + */
1.287 +#define ULOC_KEYWORD_AND_VALUES_CAPACITY 100
1.288 +
1.289 +/**
1.290 + * Character separating keywords from the locale string
1.291 + * different for EBCDIC - TODO
1.292 + * @stable ICU 2.8
1.293 + */
1.294 +#define ULOC_KEYWORD_SEPARATOR '@'
1.295 +/**
1.296 + * Character for assigning value to a keyword
1.297 + * @stable ICU 2.8
1.298 + */
1.299 +#define ULOC_KEYWORD_ASSIGN '='
1.300 +/**
1.301 + * Character separating keywords
1.302 + * @stable ICU 2.8
1.303 + */
1.304 +#define ULOC_KEYWORD_ITEM_SEPARATOR ';'
1.305 +
1.306 +#endif /*U_HIDE_DRAFT_API*/
1.307 +
1.308 +/**
1.309 + * Constants for *_getLocale()
1.310 + * Allow user to select whether she wants information on
1.311 + * requested, valid or actual locale.
1.312 + * For example, a collator for "en_US_CALIFORNIA" was
1.313 + * requested. In the current state of ICU (2.0),
1.314 + * the requested locale is "en_US_CALIFORNIA",
1.315 + * the valid locale is "en_US" (most specific locale supported by ICU)
1.316 + * and the actual locale is "root" (the collation data comes unmodified
1.317 + * from the UCA)
1.318 + * The locale is considered supported by ICU if there is a core ICU bundle
1.319 + * for that locale (although it may be empty).
1.320 + * @stable ICU 2.1
1.321 + */
1.322 +typedef enum {
1.323 + /** This is locale the data actually comes from
1.324 + * @stable ICU 2.1
1.325 + */
1.326 + ULOC_ACTUAL_LOCALE = 0,
1.327 + /** This is the most specific locale supported by ICU
1.328 + * @stable ICU 2.1
1.329 + */
1.330 + ULOC_VALID_LOCALE = 1,
1.331 +
1.332 +#ifndef U_HIDE_DEPRECATED_API
1.333 + /** This is the requested locale
1.334 + * @deprecated ICU 2.8
1.335 + */
1.336 + ULOC_REQUESTED_LOCALE = 2,
1.337 +#endif /* U_HIDE_DEPRECATED_API */
1.338 +
1.339 + ULOC_DATA_LOCALE_TYPE_LIMIT
1.340 +} ULocDataLocaleType ;
1.341 +
1.342 +
1.343 +/**
1.344 + * Gets ICU's default locale.
1.345 + * The returned string is a snapshot in time, and will remain valid
1.346 + * and unchanged even when uloc_setDefault() is called.
1.347 + * The returned storage is owned by ICU, and must not be altered or deleted
1.348 + * by the caller.
1.349 + *
1.350 + * @return the ICU default locale
1.351 + * @system
1.352 + * @stable ICU 2.0
1.353 + */
1.354 +U_STABLE const char* U_EXPORT2
1.355 +uloc_getDefault(void);
1.356 +
1.357 +/**
1.358 + * Sets ICU's default locale.
1.359 + * By default (without calling this function), ICU's default locale will be based
1.360 + * on information obtained from the underlying system environment.
1.361 + * <p>
1.362 + * Changes to ICU's default locale do not propagate back to the
1.363 + * system environment.
1.364 + * <p>
1.365 + * Changes to ICU's default locale to not affect any ICU services that
1.366 + * may already be open based on the previous default locale value.
1.367 + *
1.368 + * @param localeID the new ICU default locale. A value of NULL will try to get
1.369 + * the system's default locale.
1.370 + * @param status the error information if the setting of default locale fails
1.371 + * @system
1.372 + * @stable ICU 2.0
1.373 + */
1.374 +U_STABLE void U_EXPORT2
1.375 +uloc_setDefault(const char* localeID,
1.376 + UErrorCode* status);
1.377 +
1.378 +/**
1.379 + * Gets the language code for the specified locale.
1.380 + *
1.381 + * @param localeID the locale to get the ISO language code with
1.382 + * @param language the language code for localeID
1.383 + * @param languageCapacity the size of the language buffer to store the
1.384 + * language code with
1.385 + * @param err error information if retrieving the language code failed
1.386 + * @return the actual buffer size needed for the language code. If it's greater
1.387 + * than languageCapacity, the returned language code will be truncated.
1.388 + * @stable ICU 2.0
1.389 + */
1.390 +U_STABLE int32_t U_EXPORT2
1.391 +uloc_getLanguage(const char* localeID,
1.392 + char* language,
1.393 + int32_t languageCapacity,
1.394 + UErrorCode* err);
1.395 +
1.396 +/**
1.397 + * Gets the script code for the specified locale.
1.398 + *
1.399 + * @param localeID the locale to get the ISO language code with
1.400 + * @param script the language code for localeID
1.401 + * @param scriptCapacity 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 scriptCapacity, the returned language code will be truncated.
1.406 + * @stable ICU 2.8
1.407 + */
1.408 +U_STABLE int32_t U_EXPORT2
1.409 +uloc_getScript(const char* localeID,
1.410 + char* script,
1.411 + int32_t scriptCapacity,
1.412 + UErrorCode* err);
1.413 +
1.414 +/**
1.415 + * Gets the country code for the specified locale.
1.416 + *
1.417 + * @param localeID the locale to get the country code with
1.418 + * @param country the country code for localeID
1.419 + * @param countryCapacity the size of the country buffer to store the
1.420 + * country code with
1.421 + * @param err error information if retrieving the country code failed
1.422 + * @return the actual buffer size needed for the country code. If it's greater
1.423 + * than countryCapacity, the returned country code will be truncated.
1.424 + * @stable ICU 2.0
1.425 + */
1.426 +U_DRAFT int32_t U_EXPORT2
1.427 +uloc_getCountry(const char* localeID,
1.428 + char* country,
1.429 + int32_t countryCapacity,
1.430 + UErrorCode* err);
1.431 +
1.432 +/**
1.433 + * Gets the variant code for the specified locale.
1.434 + *
1.435 + * @param localeID the locale to get the variant code with
1.436 + * @param variant the variant code for localeID
1.437 + * @param variantCapacity the size of the variant buffer to store the
1.438 + * variant code with
1.439 + * @param err error information if retrieving the variant code failed
1.440 + * @return the actual buffer size needed for the variant code. If it's greater
1.441 + * than variantCapacity, the returned variant code will be truncated.
1.442 + * @stable ICU 2.0
1.443 + */
1.444 +U_STABLE int32_t U_EXPORT2
1.445 +uloc_getVariant(const char* localeID,
1.446 + char* variant,
1.447 + int32_t variantCapacity,
1.448 + UErrorCode* err);
1.449 +
1.450 +
1.451 +/**
1.452 + * Gets the full name for the specified locale.
1.453 + * Note: This has the effect of 'canonicalizing' the ICU locale ID to
1.454 + * a certain extent. Upper and lower case are set as needed.
1.455 + * It does NOT map aliased names in any way.
1.456 + * See the top of this header file.
1.457 + * This API supports preflighting.
1.458 + *
1.459 + * @param localeID the locale to get the full name with
1.460 + * @param name fill in buffer for the name without keywords.
1.461 + * @param nameCapacity capacity of the fill in buffer.
1.462 + * @param err error information if retrieving the full name failed
1.463 + * @return the actual buffer size needed for the full name. If it's greater
1.464 + * than nameCapacity, the returned full name will be truncated.
1.465 + * @stable ICU 2.0
1.466 + */
1.467 +U_STABLE int32_t U_EXPORT2
1.468 +uloc_getName(const char* localeID,
1.469 + char* name,
1.470 + int32_t nameCapacity,
1.471 + UErrorCode* err);
1.472 +
1.473 +/**
1.474 + * Gets the full name for the specified locale.
1.475 + * Note: This has the effect of 'canonicalizing' the string to
1.476 + * a certain extent. Upper and lower case are set as needed,
1.477 + * and if the components were in 'POSIX' format they are changed to
1.478 + * ICU format. It does NOT map aliased names in any way.
1.479 + * See the top of this header file.
1.480 + *
1.481 + * @param localeID the locale to get the full name with
1.482 + * @param name the full name for localeID
1.483 + * @param nameCapacity the size of the name buffer to store the
1.484 + * full name with
1.485 + * @param err error information if retrieving the full name failed
1.486 + * @return the actual buffer size needed for the full name. If it's greater
1.487 + * than nameCapacity, the returned full name will be truncated.
1.488 + * @stable ICU 2.8
1.489 + */
1.490 +U_STABLE int32_t U_EXPORT2
1.491 +uloc_canonicalize(const char* localeID,
1.492 + char* name,
1.493 + int32_t nameCapacity,
1.494 + UErrorCode* err);
1.495 +
1.496 +/**
1.497 + * Gets the ISO language code for the specified locale.
1.498 + *
1.499 + * @param localeID the locale to get the ISO language code with
1.500 + * @return language the ISO language code for localeID
1.501 + * @stable ICU 2.0
1.502 + */
1.503 +U_STABLE const char* U_EXPORT2
1.504 +uloc_getISO3Language(const char* localeID);
1.505 +
1.506 +
1.507 +/**
1.508 + * Gets the ISO country code for the specified locale.
1.509 + *
1.510 + * @param localeID the locale to get the ISO country code with
1.511 + * @return country the ISO country code for localeID
1.512 + * @stable ICU 2.0
1.513 + */
1.514 +U_STABLE const char* U_EXPORT2
1.515 +uloc_getISO3Country(const char* localeID);
1.516 +
1.517 +/**
1.518 + * Gets the Win32 LCID value for the specified locale.
1.519 + * If the ICU locale is not recognized by Windows, 0 will be returned.
1.520 + *
1.521 + * @param localeID the locale to get the Win32 LCID value with
1.522 + * @return country the Win32 LCID for localeID
1.523 + * @stable ICU 2.0
1.524 + */
1.525 +U_STABLE uint32_t U_EXPORT2
1.526 +uloc_getLCID(const char* localeID);
1.527 +
1.528 +/**
1.529 + * Gets the language name suitable for display for the specified locale.
1.530 + *
1.531 + * @param locale the locale to get the ISO language code with
1.532 + * @param displayLocale Specifies the locale to be used to display the name. In other words,
1.533 + * if the locale's language code is "en", passing Locale::getFrench() for
1.534 + * inLocale would result in "Anglais", while passing Locale::getGerman()
1.535 + * for inLocale would result in "Englisch".
1.536 + * @param language the displayable language code for localeID
1.537 + * @param languageCapacity the size of the language buffer to store the
1.538 + * displayable language code with
1.539 + * @param status error information if retrieving the displayable language code failed
1.540 + * @return the actual buffer size needed for the displayable language code. If it's greater
1.541 + * than languageCapacity, the returned language code will be truncated.
1.542 + * @stable ICU 2.0
1.543 + */
1.544 +U_STABLE int32_t U_EXPORT2
1.545 +uloc_getDisplayLanguage(const char* locale,
1.546 + const char* displayLocale,
1.547 + UChar* language,
1.548 + int32_t languageCapacity,
1.549 + UErrorCode* status);
1.550 +
1.551 +/**
1.552 + * Gets the script name suitable for display for the specified locale.
1.553 + *
1.554 + * @param locale the locale to get the displayable script code with. NULL may be used to specify the default.
1.555 + * @param displayLocale Specifies the locale to be used to display the name. In other words,
1.556 + * if the locale's language code is "en", passing Locale::getFrench() for
1.557 + * inLocale would result in "", while passing Locale::getGerman()
1.558 + * for inLocale would result in "". NULL may be used to specify the default.
1.559 + * @param script the displayable country code for localeID
1.560 + * @param scriptCapacity the size of the script buffer to store the
1.561 + * displayable script code with
1.562 + * @param status error information if retrieving the displayable script code failed
1.563 + * @return the actual buffer size needed for the displayable script code. If it's greater
1.564 + * than scriptCapacity, the returned displayable script code will be truncated.
1.565 + * @stable ICU 2.8
1.566 + */
1.567 +U_STABLE int32_t U_EXPORT2
1.568 +uloc_getDisplayScript(const char* locale,
1.569 + const char* displayLocale,
1.570 + UChar* script,
1.571 + int32_t scriptCapacity,
1.572 + UErrorCode* status);
1.573 +
1.574 +/**
1.575 + * Gets the country name suitable for display for the specified locale.
1.576 + *
1.577 + * @param locale the locale to get the displayable country code with. NULL may be used to specify the default.
1.578 + * @param displayLocale Specifies the locale to be used to display the name. In other words,
1.579 + * if the locale's language code is "en", passing Locale::getFrench() for
1.580 + * inLocale would result in "Anglais", while passing Locale::getGerman()
1.581 + * for inLocale would result in "Englisch". NULL may be used to specify the default.
1.582 + * @param country the displayable country code for localeID
1.583 + * @param countryCapacity the size of the country buffer to store the
1.584 + * displayable country code with
1.585 + * @param status error information if retrieving the displayable country code failed
1.586 + * @return the actual buffer size needed for the displayable country code. If it's greater
1.587 + * than countryCapacity, the returned displayable country code will be truncated.
1.588 + * @stable ICU 2.0
1.589 + */
1.590 +U_STABLE int32_t U_EXPORT2
1.591 +uloc_getDisplayCountry(const char* locale,
1.592 + const char* displayLocale,
1.593 + UChar* country,
1.594 + int32_t countryCapacity,
1.595 + UErrorCode* status);
1.596 +
1.597 +
1.598 +/**
1.599 + * Gets the variant name suitable for display for the specified locale.
1.600 + *
1.601 + * @param locale the locale to get the displayable variant code with. NULL may be used to specify the default.
1.602 + * @param displayLocale Specifies the locale to be used to display the name. In other words,
1.603 + * if the locale's language code is "en", passing Locale::getFrench() for
1.604 + * inLocale would result in "Anglais", while passing Locale::getGerman()
1.605 + * for inLocale would result in "Englisch". NULL may be used to specify the default.
1.606 + * @param variant the displayable variant code for localeID
1.607 + * @param variantCapacity the size of the variant buffer to store the
1.608 + * displayable variant code with
1.609 + * @param status error information if retrieving the displayable variant code failed
1.610 + * @return the actual buffer size needed for the displayable variant code. If it's greater
1.611 + * than variantCapacity, the returned displayable variant code will be truncated.
1.612 + * @stable ICU 2.0
1.613 + */
1.614 +U_STABLE int32_t U_EXPORT2
1.615 +uloc_getDisplayVariant(const char* locale,
1.616 + const char* displayLocale,
1.617 + UChar* variant,
1.618 + int32_t variantCapacity,
1.619 + UErrorCode* status);
1.620 +
1.621 +/**
1.622 + * Gets the keyword name suitable for display for the specified locale.
1.623 + * E.g: for the locale string de_DE\@collation=PHONEBOOK, this API gets the display
1.624 + * string for the keyword collation.
1.625 + * Usage:
1.626 + * <code>
1.627 + * UErrorCode status = U_ZERO_ERROR;
1.628 + * const char* keyword =NULL;
1.629 + * int32_t keywordLen = 0;
1.630 + * int32_t keywordCount = 0;
1.631 + * UChar displayKeyword[256];
1.632 + * int32_t displayKeywordLen = 0;
1.633 + * UEnumeration* keywordEnum = uloc_openKeywords("de_DE@collation=PHONEBOOK;calendar=TRADITIONAL", &status);
1.634 + * for(keywordCount = uenum_count(keywordEnum, &status); keywordCount > 0 ; keywordCount--){
1.635 + * if(U_FAILURE(status)){
1.636 + * ...something went wrong so handle the error...
1.637 + * break;
1.638 + * }
1.639 + * // the uenum_next returns NUL terminated string
1.640 + * keyword = uenum_next(keywordEnum, &keywordLen, &status);
1.641 + * displayKeywordLen = uloc_getDisplayKeyword(keyword, "en_US", displayKeyword, 256);
1.642 + * ... do something interesting .....
1.643 + * }
1.644 + * uenum_close(keywordEnum);
1.645 + * </code>
1.646 + * @param keyword The keyword whose display string needs to be returned.
1.647 + * @param displayLocale Specifies the locale to be used to display the name. In other words,
1.648 + * if the locale's language code is "en", passing Locale::getFrench() for
1.649 + * inLocale would result in "Anglais", while passing Locale::getGerman()
1.650 + * for inLocale would result in "Englisch". NULL may be used to specify the default.
1.651 + * @param dest the buffer to which the displayable keyword should be written.
1.652 + * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1.653 + * dest may be NULL and the function will only return the length of the
1.654 + * result without writing any of the result string (pre-flighting).
1.655 + * @param status error information if retrieving the displayable string failed.
1.656 + * Should not be NULL and should not indicate failure on entry.
1.657 + * @return the actual buffer size needed for the displayable variant code.
1.658 + * @see #uloc_openKeywords
1.659 + * @stable ICU 2.8
1.660 + */
1.661 +U_STABLE int32_t U_EXPORT2
1.662 +uloc_getDisplayKeyword(const char* keyword,
1.663 + const char* displayLocale,
1.664 + UChar* dest,
1.665 + int32_t destCapacity,
1.666 + UErrorCode* status);
1.667 +/**
1.668 + * Gets the value of the keyword suitable for display for the specified locale.
1.669 + * E.g: for the locale string de_DE\@collation=PHONEBOOK, this API gets the display
1.670 + * string for PHONEBOOK, in the display locale, when "collation" is specified as the keyword.
1.671 + *
1.672 + * @param locale The locale to get the displayable variant code with. NULL may be used to specify the default.
1.673 + * @param keyword The keyword for whose value should be used.
1.674 + * @param displayLocale Specifies the locale to be used to display the name. In other words,
1.675 + * if the locale's language code is "en", passing Locale::getFrench() for
1.676 + * inLocale would result in "Anglais", while passing Locale::getGerman()
1.677 + * for inLocale would result in "Englisch". NULL may be used to specify the default.
1.678 + * @param dest the buffer to which the displayable keyword should be written.
1.679 + * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1.680 + * dest may be NULL and the function will only return the length of the
1.681 + * result without writing any of the result string (pre-flighting).
1.682 + * @param status error information if retrieving the displayable string failed.
1.683 + * Should not be NULL and must not indicate failure on entry.
1.684 + * @return the actual buffer size needed for the displayable variant code.
1.685 + * @stable ICU 2.8
1.686 + */
1.687 +U_STABLE int32_t U_EXPORT2
1.688 +uloc_getDisplayKeywordValue( const char* locale,
1.689 + const char* keyword,
1.690 + const char* displayLocale,
1.691 + UChar* dest,
1.692 + int32_t destCapacity,
1.693 + UErrorCode* status);
1.694 +/**
1.695 + * Gets the full name suitable for display for the specified locale.
1.696 + *
1.697 + * @param localeID the locale to get the displayable name with. NULL may be used to specify the default.
1.698 + * @param inLocaleID Specifies the locale to be used to display the name. In other words,
1.699 + * if the locale's language code is "en", passing Locale::getFrench() for
1.700 + * inLocale would result in "Anglais", while passing Locale::getGerman()
1.701 + * for inLocale would result in "Englisch". NULL may be used to specify the default.
1.702 + * @param result the displayable name for localeID
1.703 + * @param maxResultSize the size of the name buffer to store the
1.704 + * displayable full name with
1.705 + * @param err error information if retrieving the displayable name failed
1.706 + * @return the actual buffer size needed for the displayable name. If it's greater
1.707 + * than maxResultSize, the returned displayable name will be truncated.
1.708 + * @stable ICU 2.0
1.709 + */
1.710 +U_STABLE int32_t U_EXPORT2
1.711 +uloc_getDisplayName(const char* localeID,
1.712 + const char* inLocaleID,
1.713 + UChar* result,
1.714 + int32_t maxResultSize,
1.715 + UErrorCode* err);
1.716 +
1.717 +
1.718 +/**
1.719 + * Gets the specified locale from a list of all available locales.
1.720 + * The return value is a pointer to an item of
1.721 + * a locale name array. Both this array and the pointers
1.722 + * it contains are owned by ICU and should not be deleted or written through
1.723 + * by the caller. The locale name is terminated by a null pointer.
1.724 + * @param n the specific locale name index of the available locale list
1.725 + * @return a specified locale name of all available locales
1.726 + * @stable ICU 2.0
1.727 + */
1.728 +U_STABLE const char* U_EXPORT2
1.729 +uloc_getAvailable(int32_t n);
1.730 +
1.731 +/**
1.732 + * Gets the size of the all available locale list.
1.733 + *
1.734 + * @return the size of the locale list
1.735 + * @stable ICU 2.0
1.736 + */
1.737 +U_STABLE int32_t U_EXPORT2 uloc_countAvailable(void);
1.738 +
1.739 +/**
1.740 + *
1.741 + * Gets a list of all available language codes defined in ISO 639. This is a pointer
1.742 + * to an array of pointers to arrays of char. All of these pointers are owned
1.743 + * by ICU-- do not delete them, and do not write through them. The array is
1.744 + * terminated with a null pointer.
1.745 + * @return a list of all available language codes
1.746 + * @stable ICU 2.0
1.747 + */
1.748 +U_STABLE const char* const* U_EXPORT2
1.749 +uloc_getISOLanguages(void);
1.750 +
1.751 +/**
1.752 + *
1.753 + * Gets a list of all available 2-letter country codes defined in ISO 639. This is a
1.754 + * pointer to an array of pointers to arrays of char. All of these pointers are
1.755 + * owned by ICU-- do not delete them, and do not write through them. The array is
1.756 + * terminated with a null pointer.
1.757 + * @return a list of all available country codes
1.758 + * @stable ICU 2.0
1.759 + */
1.760 +U_STABLE const char* const* U_EXPORT2
1.761 +uloc_getISOCountries(void);
1.762 +
1.763 +/**
1.764 + * Truncate the locale ID string to get the parent locale ID.
1.765 + * Copies the part of the string before the last underscore.
1.766 + * The parent locale ID will be an empty string if there is no
1.767 + * underscore, or if there is only one underscore at localeID[0].
1.768 + *
1.769 + * @param localeID Input locale ID string.
1.770 + * @param parent Output string buffer for the parent locale ID.
1.771 + * @param parentCapacity Size of the output buffer.
1.772 + * @param err A UErrorCode value.
1.773 + * @return The length of the parent locale ID.
1.774 + * @stable ICU 2.0
1.775 + */
1.776 +U_STABLE int32_t U_EXPORT2
1.777 +uloc_getParent(const char* localeID,
1.778 + char* parent,
1.779 + int32_t parentCapacity,
1.780 + UErrorCode* err);
1.781 +
1.782 +
1.783 +
1.784 +
1.785 +/**
1.786 + * Gets the full name for the specified locale.
1.787 + * Note: This has the effect of 'canonicalizing' the string to
1.788 + * a certain extent. Upper and lower case are set as needed,
1.789 + * and if the components were in 'POSIX' format they are changed to
1.790 + * ICU format. It does NOT map aliased names in any way.
1.791 + * See the top of this header file.
1.792 + * This API strips off the keyword part, so "de_DE\@collation=phonebook"
1.793 + * will become "de_DE".
1.794 + * This API supports preflighting.
1.795 + *
1.796 + * @param localeID the locale to get the full name with
1.797 + * @param name fill in buffer for the name without keywords.
1.798 + * @param nameCapacity capacity of the fill in buffer.
1.799 + * @param err error information if retrieving the full name failed
1.800 + * @return the actual buffer size needed for the full name. If it's greater
1.801 + * than nameCapacity, the returned full name will be truncated.
1.802 + * @stable ICU 2.8
1.803 + */
1.804 +U_STABLE int32_t U_EXPORT2
1.805 +uloc_getBaseName(const char* localeID,
1.806 + char* name,
1.807 + int32_t nameCapacity,
1.808 + UErrorCode* err);
1.809 +
1.810 +/**
1.811 + * Gets an enumeration of keywords for the specified locale. Enumeration
1.812 + * must get disposed of by the client using uenum_close function.
1.813 + *
1.814 + * @param localeID the locale to get the variant code with
1.815 + * @param status error information if retrieving the keywords failed
1.816 + * @return enumeration of keywords or NULL if there are no keywords.
1.817 + * @stable ICU 2.8
1.818 + */
1.819 +U_STABLE UEnumeration* U_EXPORT2
1.820 +uloc_openKeywords(const char* localeID,
1.821 + UErrorCode* status);
1.822 +
1.823 +/**
1.824 + * Get the value for a keyword. Locale name does not need to be normalized.
1.825 + *
1.826 + * @param localeID locale name containing the keyword ("de_DE@currency=EURO;collation=PHONEBOOK")
1.827 + * @param keywordName name of the keyword for which we want the value. Case insensitive.
1.828 + * @param buffer receiving buffer
1.829 + * @param bufferCapacity capacity of receiving buffer
1.830 + * @param status containing error code - buffer not big enough.
1.831 + * @return the length of keyword value
1.832 + * @stable ICU 2.8
1.833 + */
1.834 +U_STABLE int32_t U_EXPORT2
1.835 +uloc_getKeywordValue(const char* localeID,
1.836 + const char* keywordName,
1.837 + char* buffer, int32_t bufferCapacity,
1.838 + UErrorCode* status);
1.839 +
1.840 +
1.841 +/**
1.842 + * Set the value of the specified keyword.
1.843 + * NOTE: Unlike almost every other ICU function which takes a
1.844 + * buffer, this function will NOT truncate the output text. If a
1.845 + * BUFFER_OVERFLOW_ERROR is received, it means that the original
1.846 + * buffer is untouched. This is done to prevent incorrect or possibly
1.847 + * even malformed locales from being generated and used.
1.848 + *
1.849 + * @param keywordName name of the keyword to be set. Case insensitive.
1.850 + * @param keywordValue value of the keyword to be set. If 0-length or
1.851 + * NULL, will result in the keyword being removed. No error is given if
1.852 + * that keyword does not exist.
1.853 + * @param buffer input buffer containing locale to be modified.
1.854 + * @param bufferCapacity capacity of receiving buffer
1.855 + * @param status containing error code - buffer not big enough.
1.856 + * @return the length needed for the buffer
1.857 + * @see uloc_getKeywordValue
1.858 + * @draft ICU 3.2
1.859 + */
1.860 +U_DRAFT int32_t U_EXPORT2
1.861 +uloc_setKeywordValue(const char* keywordName,
1.862 + const char* keywordValue,
1.863 + char* buffer, int32_t bufferCapacity,
1.864 + UErrorCode* status);
1.865 +
1.866 +/**
1.867 + * enums for the 'outResult' parameter return value
1.868 + * @see uloc_acceptLanguageFromHTTP
1.869 + * @see uloc_acceptLanguage
1.870 + * @draft ICU 3.2
1.871 + */
1.872 +typedef enum {
1.873 + ULOC_ACCEPT_FAILED = 0, /* No exact match was found. */
1.874 + ULOC_ACCEPT_VALID = 1, /* An exact match was found. */
1.875 + ULOC_ACCEPT_FALLBACK = 2 /* A fallback was found, for example,
1.876 + Accept list contained 'ja_JP'
1.877 + which matched available locale 'ja'. */
1.878 +} UAcceptResult;
1.879 +
1.880 +
1.881 +/**
1.882 + * Based on a HTTP header from a web browser and a list of available locales,
1.883 + * determine an acceptable locale for the user.
1.884 + * @param result - buffer to accept the result locale
1.885 + * @param resultAvailable the size of the result buffer.
1.886 + * @param outResult - An out parameter that contains the fallback status
1.887 + * @param httpAcceptLanguage - "Accept-Language:" header as per HTTP.
1.888 + * @param availableLocales - list of available locales to match
1.889 + * @param status Error status, may be BUFFER_OVERFLOW_ERROR
1.890 + * @return length needed for the locale.
1.891 + * @draft ICU 3.2
1.892 + */
1.893 +U_DRAFT int32_t U_EXPORT2
1.894 +uloc_acceptLanguageFromHTTP(char *result, int32_t resultAvailable,
1.895 + UAcceptResult *outResult,
1.896 + const char *httpAcceptLanguage,
1.897 + UEnumeration* availableLocales,
1.898 + UErrorCode *status);
1.899 +
1.900 +/**
1.901 + * Based on a list of available locales,
1.902 + * determine an acceptable locale for the user.
1.903 + * @param result - buffer to accept the result locale
1.904 + * @param resultAvailable the size of the result buffer.
1.905 + * @param outResult - An out parameter that contains the fallback status
1.906 + * @param acceptList - list of acceptable languages
1.907 + * @param acceptListCount - count of acceptList items
1.908 + * @param availableLocales - list of available locales to match
1.909 + * @param status Error status, may be BUFFER_OVERFLOW_ERROR
1.910 + * @return length needed for the locale.
1.911 + * @draft ICU 3.2
1.912 + */
1.913 +U_DRAFT int32_t U_EXPORT2
1.914 +uloc_acceptLanguage(char *result, int32_t resultAvailable,
1.915 + UAcceptResult *outResult, const char **acceptList,
1.916 + int32_t acceptListCount,
1.917 + UEnumeration* availableLocales,
1.918 + UErrorCode *status);
1.919 +
1.920 +
1.921 +#endif /*_ULOC*/
1.922 +
1.923 +