ICU-491.11.3.tar.gz

[apple/icu.git] / icuSources / common / unicode / uloc.h

diff --git a/icuSources/common/unicode/uloc.h b/icuSources/common/unicode/uloc.h
index 2912f6770ef73f8d8317854e6233d085f20d47a9..29c0d6523f348e6a50ec57221c170c07a9342cf5 100644 (file)
--- a/icuSources/common/unicode/uloc.h
+++ b/icuSources/common/unicode/uloc.h
@@ -1,6 +1,6 @@
 /*
 **********************************************************************
 /*
 **********************************************************************

-*   Copyright (C) 1997-2007, International Business Machines
+*   Copyright (C) 1997-2012, International Business Machines

 *   Corporation and others.  All Rights Reserved.
 **********************************************************************
 *
 *   Corporation and others.  All Rights Reserved.
 **********************************************************************
 *


@@ -256,10 +256,10 @@
 #define ULOC_COUNTRY_CAPACITY 4
 /**
  * Useful constant for the maximum size of the whole locale ID
 #define ULOC_COUNTRY_CAPACITY 4
 /**
  * Useful constant for the maximum size of the whole locale ID

- * (including the terminating NULL).
+ * (including the terminating NULL and all keywords).

  * @stable ICU 2.0
  */
  * @stable ICU 2.0
  */

-#define ULOC_FULLNAME_CAPACITY 56
+#define ULOC_FULLNAME_CAPACITY 157

 
 /**
  * Useful constant for the maximum size of the script part of a locale ID
 
 /**
  * Useful constant for the maximum size of the script part of a locale ID


@@ -275,28 +275,50 @@
 #define ULOC_KEYWORDS_CAPACITY 50
 
 /**
 #define ULOC_KEYWORDS_CAPACITY 50
 
 /**

- * Useful constant for the maximum SIZE of keywords in a locale
+ * Useful constant for the maximum total size of keywords and their values in a locale

  * @stable ICU 2.8
  */
 #define ULOC_KEYWORD_AND_VALUES_CAPACITY 100
 
 /**
  * @stable ICU 2.8
  */
 #define ULOC_KEYWORD_AND_VALUES_CAPACITY 100
 
 /**

- * Character separating keywords from the locale string
- * different for EBCDIC - TODO
+ * Invariant character separating keywords from the locale string

  * @stable ICU 2.8
  */
 #define ULOC_KEYWORD_SEPARATOR '@'
  * @stable ICU 2.8
  */
 #define ULOC_KEYWORD_SEPARATOR '@'

+
+/**
+  * Unicode code point for '@' separating keywords from the locale string.
+  * @see ULOC_KEYWORD_SEPARATOR
+  * @stable ICU 4.6
+  */
+#define ULOC_KEYWORD_SEPARATOR_UNICODE 0x40
+

 /**
 /**

- * Character for assigning value to a keyword
+ * Invariant character for assigning value to a keyword

  * @stable ICU 2.8
  */
 #define ULOC_KEYWORD_ASSIGN '='
  * @stable ICU 2.8
  */
 #define ULOC_KEYWORD_ASSIGN '='

+
+/**
+  * Unicode code point for '=' for assigning value to a keyword.
+  * @see ULOC_KEYWORD_ASSIGN
+  * @stable ICU 4.6 
+  */
+#define ULOC_KEYWORD_ASSIGN_UNICODE 0x3D
+

 /**
 /**

- * Character separating keywords
+ * Invariant character separating keywords

  * @stable ICU 2.8
  */
 #define ULOC_KEYWORD_ITEM_SEPARATOR ';'
 
  * @stable ICU 2.8
  */
 #define ULOC_KEYWORD_ITEM_SEPARATOR ';'
 

+/**
+  * Unicode code point for ';' separating keywords
+  * @see ULOC_KEYWORD_ITEM_SEPARATOR
+  * @stable ICU 4.6
+  */
+#define ULOC_KEYWORD_ITEM_SEPARATOR_UNICODE 0x3B
+

 /**
  * Constants for *_getLocale()
  * Allow user to select whether she wants information on 
 /**
  * Constants for *_getLocale()
  * Allow user to select whether she wants information on 


@@ -331,7 +353,7 @@ typedef enum {
   ULOC_DATA_LOCALE_TYPE_LIMIT = 3
 } ULocDataLocaleType ;
 
   ULOC_DATA_LOCALE_TYPE_LIMIT = 3
 } ULocDataLocaleType ;
 

-
+#ifndef U_HIDE_SYSTEM_API

 /**
  * Gets ICU's default locale.  
  * The returned string is a snapshot in time, and will remain valid
 /**
  * Gets ICU's default locale.  
  * The returned string is a snapshot in time, and will remain valid


@@ -366,6 +388,7 @@ uloc_getDefault(void);
 U_STABLE void U_EXPORT2
 uloc_setDefault(const char* localeID,
         UErrorCode*       status);
 U_STABLE void U_EXPORT2
 uloc_setDefault(const char* localeID,
         UErrorCode*       status);

+#endif  /* U_HIDE_SYSTEM_API */

 
 /**
  * Gets the language code for the specified locale.
 
 /**
  * Gets the language code for the specified locale.


@@ -855,6 +878,43 @@ uloc_setKeywordValue(const char* keywordName,
                      char* buffer, int32_t bufferCapacity,
                      UErrorCode* status);
 
                      char* buffer, int32_t bufferCapacity,
                      UErrorCode* status);
 

+/**
+ * enums for the  return value for the character and line orientation
+ * functions.
+ * @stable ICU 4.0
+ */
+typedef enum {
+  ULOC_LAYOUT_LTR   = 0,  /* left-to-right. */
+  ULOC_LAYOUT_RTL    = 1,  /* right-to-left. */
+  ULOC_LAYOUT_TTB    = 2,  /* top-to-bottom. */
+  ULOC_LAYOUT_BTT    = 3,   /* bottom-to-top. */
+  ULOC_LAYOUT_UNKNOWN
+} ULayoutType;
+
+/**
+ * Get the layout character orientation for the specified locale.
+ * 
+ * @param localeId locale name
+ * @param status Error status
+ * @return an enum indicating the layout orientation for characters.
+ * @stable ICU 4.0
+ */
+U_STABLE ULayoutType U_EXPORT2
+uloc_getCharacterOrientation(const char* localeId,
+                             UErrorCode *status);
+
+/**
+ * Get the layout line orientation for the specified locale.
+ * 
+ * @param localeId locale name
+ * @param status Error status
+ * @return an enum indicating the layout orientation for lines.
+ * @stable ICU 4.0
+ */
+U_STABLE ULayoutType U_EXPORT2
+uloc_getLineOrientation(const char* localeId,
+                        UErrorCode *status);
+

 /**
  * enums for the 'outResult' parameter return value
  * @see uloc_acceptLanguageFromHTTP
 /**
  * enums for the 'outResult' parameter return value
  * @see uloc_acceptLanguageFromHTTP


@@ -920,12 +980,148 @@ uloc_acceptLanguage(char *result, int32_t resultAvailable,
  * @param status an error is returned if the LCID is unrecognized or the output buffer
  *  is too small
  * @return actual the actual size of the locale ID, not including NUL-termination 
  * @param status an error is returned if the LCID is unrecognized or the output buffer
  *  is too small
  * @return actual the actual size of the locale ID, not including NUL-termination 

- * @draft ICU 3.8
+ * @stable ICU 3.8

  */
  */

-U_DRAFT int32_t U_EXPORT2
-uloc_getLocaleForLCID(uint32_t hostid, char *locale, int32_t localeCapacity,
+U_STABLE int32_t U_EXPORT2
+uloc_getLocaleForLCID(uint32_t hostID, char *locale, int32_t localeCapacity,

                     UErrorCode *status);
 
                     UErrorCode *status);
 

-#endif /*_ULOC*/

 
 

+/**
+ * Add the likely subtags for a provided locale ID, per the algorithm described
+ * in the following CLDR technical report:
+ *
+ *   http://www.unicode.org/reports/tr35/#Likely_Subtags
+ *
+ * If localeID is already in the maximal form, or there is no data available
+ * for maximization, it will be copied to the output buffer.  For example,
+ * "und-Zzzz" cannot be maximized, since there is no reasonable maximization.
+ *
+ * Examples:
+ *
+ * "en" maximizes to "en_Latn_US"
+ *
+ * "de" maximizes to "de_Latn_US"
+ *
+ * "sr" maximizes to "sr_Cyrl_RS"
+ *
+ * "sh" maximizes to "sr_Latn_RS" (Note this will not reverse.)
+ *
+ * "zh_Hani" maximizes to "zh_Hans_CN" (Note this will not reverse.)
+ *
+ * @param localeID The locale to maximize
+ * @param maximizedLocaleID The maximized locale
+ * @param maximizedLocaleIDCapacity The capacity of the maximizedLocaleID buffer
+ * @param err Error information if maximizing the locale failed.  If the length
+ * of the localeID and the null-terminator is greater than the maximum allowed size,
+ * or the localeId is not well-formed, the error code is U_ILLEGAL_ARGUMENT_ERROR.
+ * @return The actual buffer size needed for the maximized locale.  If it's
+ * greater than maximizedLocaleIDCapacity, the returned ID will be truncated.
+ * On error, the return value is -1.
+ * @stable ICU 4.0
+ */
+U_STABLE int32_t U_EXPORT2
+uloc_addLikelySubtags(const char*    localeID,
+         char* maximizedLocaleID,
+         int32_t maximizedLocaleIDCapacity,
+         UErrorCode* err);
+
+
+/**
+ * Minimize the subtags for a provided locale ID, per the algorithm described
+ * in the following CLDR technical report:
+ *
+ *   http://www.unicode.org/reports/tr35/#Likely_Subtags
+ *
+ * If localeID is already in the minimal form, or there is no data available
+ * for minimization, it will be copied to the output buffer.  Since the
+ * minimization algorithm relies on proper maximization, see the comments
+ * for uloc_addLikelySubtags for reasons why there might not be any data.
+ *
+ * Examples:
+ *
+ * "en_Latn_US" minimizes to "en"
+ *
+ * "de_Latn_US" minimizes to "de"
+ *
+ * "sr_Cyrl_RS" minimizes to "sr"
+ *
+ * "zh_Hant_TW" minimizes to "zh_TW" (The region is preferred to the
+ * script, and minimizing to "zh" would imply "zh_Hans_CN".)
+ *
+ * @param localeID The locale to minimize
+ * @param minimizedLocaleID The minimized locale
+ * @param minimizedLocaleIDCapacity The capacity of the minimizedLocaleID buffer
+ * @param err Error information if minimizing the locale failed.  If the length
+ * of the localeID and the null-terminator is greater than the maximum allowed size,
+ * or the localeId is not well-formed, the error code is U_ILLEGAL_ARGUMENT_ERROR.
+ * @return The actual buffer size needed for the minimized locale.  If it's
+ * greater than minimizedLocaleIDCapacity, the returned ID will be truncated.
+ * On error, the return value is -1.
+ * @stable ICU 4.0
+ */
+U_STABLE int32_t U_EXPORT2
+uloc_minimizeSubtags(const char*    localeID,
+         char* minimizedLocaleID,
+         int32_t minimizedLocaleIDCapacity,
+         UErrorCode* err);

 
 

+/**
+ * Returns a locale ID for the specified BCP47 language tag string.
+ * If the specified language tag contains any ill-formed subtags,
+ * the first such subtag and all following subtags are ignored.
+ * <p> 
+ * This implements the 'Language-Tag' production of BCP47, and so
+ * supports grandfathered (regular and irregular) as well as private
+ * use language tags.  Private use tags are represented as 'x-whatever',
+ * and grandfathered tags are converted to their canonical replacements
+ * where they exist.  Note that a few grandfathered tags have no modern
+ * replacement, these will be converted using the fallback described in
+ * the first paragraph, so some information might be lost.
+ * @param langtag   the input BCP47 language tag.
+ * @param localeID  the output buffer receiving a locale ID for the
+ *                  specified BCP47 language tag.
+ * @param localeIDCapacity  the size of the locale ID output buffer.
+ * @param parsedLength  if not NULL, successfully parsed length
+ *                      for the input language tag is set.
+ * @param err       error information if receiving the locald ID
+ *                  failed.
+ * @return          the length of the locale ID.
+ * @stable ICU 4.2
+ */
+U_DRAFT int32_t U_EXPORT2
+uloc_forLanguageTag(const char* langtag,
+                    char* localeID,
+                    int32_t localeIDCapacity,
+                    int32_t* parsedLength,
+                    UErrorCode* err);
+
+/**
+ * Returns a well-formed language tag for this locale ID. 
+ * <p> 
+ * <b>Note</b>: When <code>strict</code> is FALSE, any locale
+ * fields which do not satisfy the BCP47 syntax requirement will
+ * be omitted from the result.  When <code>strict</code> is
+ * TRUE, this function sets U_ILLEGAL_ARGUMENT_ERROR to the
+ * <code>err</code> if any locale fields do not satisfy the
+ * BCP47 syntax requirement.
+ * @param localeID  the input locale ID
+ * @param langtag   the output buffer receiving BCP47 language
+ *                  tag for the locale ID.
+ * @param langtagCapacity   the size of the BCP47 language tag
+ *                          output buffer.
+ * @param strict    boolean value indicating if the function returns
+ *                  an error for an ill-formed input locale ID.
+ * @param err       error information if receiving the language
+ *                  tag failed.
+ * @return          The length of the BCP47 language tag.
+ * @stable ICU 4.2
+ */
+U_DRAFT int32_t U_EXPORT2
+uloc_toLanguageTag(const char* localeID,
+                   char* langtag,
+                   int32_t langtagCapacity,
+                   UBool strict,
+                   UErrorCode* err);
+
+#endif /*_ULOC*/