| | 1 | /* |
| | 2 | ***************************************************************************************** |
| | 3 | * Copyright (C) 2014-2015 Apple Inc. All Rights Reserved. |
| | 4 | ***************************************************************************************** |
| | 5 | */ |
| | 6 | |
| | 7 | #ifndef UALOC_H |
| | 8 | #define UALOC_H |
| | 9 | |
| | 10 | #include "unicode/utypes.h" |
| | 11 | |
| | 12 | #ifndef U_HIDE_DRAFT_API |
| | 13 | |
| | 14 | /** |
| | 15 | * Codes for language status in a country or region. |
| | 16 | * @draft ICU 54 |
| | 17 | */ |
| | 18 | typedef enum { |
| | 19 | /** |
| | 20 | * The status is unknown, or the language has no special status. |
| | 21 | * @draft ICU 54 */ |
| | 22 | UALANGSTATUS_UNSPECIFIED = 0, |
| | 23 | /** |
| | 24 | * The language is official in a region of the specified country, |
| | 25 | * e.g. Hawaiian for U.S. |
| | 26 | * @draft ICU 54 */ |
| | 27 | UALANGSTATUS_REGIONAL_OFFICIAL = 4, |
| | 28 | /** |
| | 29 | * The language is de-facto official for the specified country or region, |
| | 30 | * e.g. English for U.S. |
| | 31 | * @draft ICU 54 */ |
| | 32 | UALANGSTATUS_DEFACTO_OFFICIAL = 8, |
| | 33 | /** |
| | 34 | * The language is explicitly official for the specified country or region. |
| | 35 | * @draft ICU 54 */ |
| | 36 | UALANGSTATUS_OFFICIAL = 12 |
| | 37 | } UALanguageStatus; |
| | 38 | |
| | 39 | /** |
| | 40 | * UALANGDATA_CODELEN is the maximum length of a language code |
| | 41 | * (language subtag, possible extension, possible script subtag) |
| | 42 | * in the UALanguageEntry struct. |
| | 43 | * @draft ICU 54 |
| | 44 | */ |
| | 45 | #define UALANGDATA_CODELEN 23 |
| | 46 | |
| | 47 | /** |
| | 48 | * The UALanguageEntry structure provides information about |
| | 49 | * one of the languages for a specified region. |
| | 50 | * @draft ICU 54 |
| | 51 | */ |
| | 52 | typedef struct { |
| | 53 | char languageCode[UALANGDATA_CODELEN + 1]; /**< language code, may include script or |
| | 54 | other subtags after primary language. |
| | 55 | This may be "und" (undetermined) for |
| | 56 | some regions such as AQ Antarctica. |
| | 57 | @draft ICU 54 */ |
| | 58 | double userFraction; /**< fraction of region's population (from 0.0 to 1.0) that |
| | 59 | uses this language (not necessarily as a first language). |
| | 60 | This may be 0.0 if the fraction is known to be very small. |
| | 61 | @draft ICU 54 */ |
| | 62 | UALanguageStatus status; /**< status of the language, if any. |
| | 63 | @draft ICU 54 */ |
| | 64 | } UALanguageEntry; |
| | 65 | |
| | 66 | /** |
| | 67 | * Fills out a provided UALanguageEntry entry with information about the languages |
| | 68 | * used in a specified region. |
| | 69 | * |
| | 70 | * @param regionID |
| | 71 | * The specified regionID (currently only ISO-3166-style IDs are supported). |
| | 72 | * @param minimumFraction |
| | 73 | * The minimum fraction of language users for a language to be included |
| | 74 | * in the UALanguageEntry array. Must be in the range 0.0 to 1.0; set to |
| | 75 | * 0.0 if no minimum threshold is desired. As an example, as of March 2014 |
| | 76 | * ICU lists 74 languages for India; setting minimumFraction to 0.001 (0.1%) |
| | 77 | * skips 27, keeping the top 47 languages for inclusion in the entries array |
| | 78 | * (depending on entriesCapacity); setting minimumFraction to 0.01 (1%) |
| | 79 | * skips 54, keeping the top 20 for inclusion. |
| | 80 | * @param entries |
| | 81 | * Caller-provided array of UALanguageEntry elements. This will be filled |
| | 82 | * out with information for languages of the specified region that meet |
| | 83 | * the minimumFraction threshold, sorted in descending order by |
| | 84 | * userFraction, up to the number of elements specified by entriesCapacity |
| | 85 | * (so the number of languages for which data is provided can be limited by |
| | 86 | * total count, by userFraction, or both). |
| | 87 | * Preflight option: You may set this to NULL (and entriesCapacity to 0) |
| | 88 | * to just obtain a count of all of the languages that meet the specified |
| | 89 | * minimumFraction, without actually getting data for any of them. |
| | 90 | * @param entriesCapacity |
| | 91 | * The number of elements in the provided entries array. Must be 0 if |
| | 92 | * entries is NULL (preflight option). |
| | 93 | * @param status |
| | 94 | * A pointer to a UErrorCode to receive any errors, for example |
| | 95 | * U_MISSING_RESOURCE_ERROR if there is no data available for the |
| | 96 | * specified region. |
| | 97 | * @return |
| | 98 | * The number of elements in entries filled out with data, or if |
| | 99 | * entries is NULL and entriesCapacity is 0 (preflight option ), the total |
| | 100 | * number of languages for the specified region that meet the minimumFraction |
| | 101 | * threshold. |
| | 102 | * @draft ICU 54 |
| | 103 | */ |
| | 104 | U_DRAFT int32_t U_EXPORT2 |
| | 105 | ualoc_getLanguagesForRegion(const char *regionID, double minimumFraction, |
| | 106 | UALanguageEntry *entries, int32_t entriesCapacity, |
| | 107 | UErrorCode *err); |
| | 108 | |
| | 109 | |
| | 110 | /** |
| | 111 | * Gets the desired lproj parent locale ID for the specified locale, |
| | 112 | * using ICU inheritance chain plus Apple additions (for zh*). For |
| | 113 | * example, provided any ID in the following chains it would return |
| | 114 | * the next one to the right: |
| | 115 | * |
| | 116 | * en_US → en → root; |
| | 117 | * en_HK → en_GB → en_001 → en → root; |
| | 118 | * en_IN → en_GB → en_001 → en → root; |
| | 119 | * es_ES → es → root; |
| | 120 | * es_MX → es_419 → es → root; |
| | 121 | * haw → root; |
| | 122 | * pt_BR → pt → root; |
| | 123 | * pt_PT → pt → root; |
| | 124 | * sr_Cyrl → sr → root; |
| | 125 | * sr_Latn → root; |
| | 126 | * zh_Hans → zh → zh_CN → root; |
| | 127 | * zh_Hant_MO → zh_Hant_HK → zh_Hant → zh_TW → root; |
| | 128 | * zh_HK → zh_Hant_HK → zh_Hant → zh_TW → root; |
| | 129 | * root → root; |
| | 130 | * tlh → root; |
| | 131 | * |
| | 132 | * @param localeID The locale whose parent to get. This can use either '-' or '_' for separator. |
| | 133 | * @param parent Buffer into which the parent localeID will be copied. |
| | 134 | * This will always use '_' for separator. |
| | 135 | * @param parentCapacity The size of the buffer for parent localeID (including room for null terminator). |
| | 136 | * @param err Pointer to UErrorCode. If on input it indicates failure, function will return 0. |
| | 137 | * If on output it indicates an error the contents of parent buffer are undefined. |
| | 138 | * @return The actual buffer length of the parent localeID. If it is greater than parentCapacity, |
| | 139 | * an overflow error will be set and the contents of parent buffer are undefined. |
| | 140 | * @draft ICU 53 |
| | 141 | */ |
| | 142 | U_DRAFT int32_t U_EXPORT2 |
| | 143 | ualoc_getAppleParent(const char* localeID, |
| | 144 | char * parent, |
| | 145 | int32_t parentCapacity, |
| | 146 | UErrorCode* err); |
| | 147 | |
| | 148 | /** |
| | 149 | * ualoc_localizationsToUse - map preferred languages to |
| | 150 | * available localizations. |
| | 151 | * ========================= |
| | 152 | * BEHAVIOR EXAMPLES |
| | 153 | * Each block gives up to 6 sets of available lprojs, and then shows how various |
| | 154 | * preferred language requests would be mapped into one of the lprojs in each set. |
| | 155 | * The en entriy marked * is currently not working as intended (get just "en" |
| | 156 | * instead of the indicated values) |
| | 157 | * |
| | 158 | * -------- |
| | 159 | * lproj sets → list1 list2 list3 list4 list5 list6 |
| | 160 | * zh_CN zh_CN zh_CN zh_Hans zh_CN zh_CN |
| | 161 | * zh_TW zh_TW zh_TW zh_Hant zh_TW zh_TW |
| | 162 | * zh_HK zh_HK zh_Hant_HK zh_Hans zh_HK |
| | 163 | * zh_MO zh_Hant zh_Hans |
| | 164 | * zh_Hant |
| | 165 | * zh_Hant_HK |
| | 166 | * language ↓ |
| | 167 | * zh zh_CN zh_CN zh_CN zh_Hans zh_Hans zh_Hans |
| | 168 | * zh-Hans zh_CN zh_CN zh_CN zh_Hans zh_Hans zh_Hans |
| | 169 | * zh-Hant zh_TW zh_TW zh_TW zh_Hant zh_Hant zh_Hant |
| | 170 | * zh-Hans-CN zh_CN zh_CN zh_CN zh_Hans zh_CN, zh_CN, |
| | 171 | * zh_Hans zh_Hans |
| | 172 | * zh-Hans-SG zh_CN zh_CN zh_CN zh_Hans zh_Hans zh_Hans |
| | 173 | * zh-Hant-TW zh_TW zh_TW zh_TW zh_Hant zh_TW, zh_TW, |
| | 174 | * zh_Hant zh_Hant |
| | 175 | * zh-Hant-HK zh_TW zh_HK, zh_HK, zh_Hant_HK, zh_Hant zh_Hant_HK, |
| | 176 | * zh_TW zh_TW zh_Hant zh_Hant |
| | 177 | * zh-Hant-MO zh_TW zh_HK, zh_MO, zh_Hant_HK, zh_Hant zh_Hant_HK, |
| | 178 | * zh_TW zh_HK,zh_TW zh_Hant zh_Hant |
| | 179 | * zh-Hans-HK zh_CN zh_CN zh_CN zh_Hans zh_Hans zh_Hans |
| | 180 | * zh-CN zh_CN zh_CN zh_CN zh_Hans zh_CN, zh_CN, |
| | 181 | * zh_Hans zh_Hans |
| | 182 | * zh-SG zh_CN zh_CN zh_CN zh_Hans zh_Hans zh_Hans |
| | 183 | * zh-TW zh_TW zh_TW zh_TW zh_Hant zh_TW, zh_TW, |
| | 184 | * zh_Hant zh_Hant |
| | 185 | * zh-HK zh_TW zh_HK zh_HK, zh_Hant_HK, zh_Hant zh_HK, |
| | 186 | * zh_TW zh_Hant zh_Hant_HK,zh_Hant |
| | 187 | * zh-MO zh_TW zh_HK zh_MO, zh_Hant_HK, zh_Hant zh_Hant_HK, |
| | 188 | * zh_HK,zh_TW zh_Hant zh_Hant_HK,zh_Hant |
| | 189 | * -------- |
| | 190 | * lproj sets → list1 list2 list3 list4 list5 list6 |
| | 191 | * English en en en en en |
| | 192 | * en_AU en_AU en_AU en_AU en_AU |
| | 193 | * en_GB en_GB en_GB en_GB en_GB |
| | 194 | * en_CA en_CA en_001 en_001 |
| | 195 | * en_IN en_150 |
| | 196 | * en_US |
| | 197 | * language ↓ |
| | 198 | * en English en en en en en |
| | 199 | * en-US English en en en_US, en en |
| | 200 | * en |
| | 201 | * en-AU English en_AU, en_AU, en_AU, en_AU,en_GB, en_AU,en_GB, |
| | 202 | * en_GB,en en_GB,en en_GB,en en_001,en en_001,en |
| | 203 | * en-CA English en en_CA, en_CA, en_001, en_001, |
| | 204 | * en en en en |
| | 205 | * en-GB English en_GB, en_GB, en_GB, en_GB, en_GB, |
| | 206 | * en en en en_001,en en_001,en |
| | 207 | * en-IN English en_GB, en_GB, en_IN, en_GB, en_GB, |
| | 208 | * en en en_GB,en en_001,en en_001,en |
| | 209 | * en-US English en en en_US, en en |
| | 210 | * en |
| | 211 | * en-FR English en_GB, en_GB, en_GB, en_GB, en_150,en_GB, |
| | 212 | * en en en en_001,en en_001,en |
| | 213 | * en-IL English en en en en_001, en_001, |
| | 214 | * en en |
| | 215 | * en-001 English en en en en_001, en_001, |
| | 216 | * en en |
| | 217 | * en-150 English en_GB, en_GB, en_GB, en_GB, en_150,en_GB, |
| | 218 | * en en en en_001,en en_001,en |
| | 219 | * en-Latn English en en en en en |
| | 220 | * en-Latn_US English en en en_US,* en en |
| | 221 | * en |
| | 222 | * -------- |
| | 223 | * lproj sets → list1 list2 list3 list4 list5 list6 |
| | 224 | * Spanish es es es es es |
| | 225 | * es_MX es_419 es_419 es_ES es_ES |
| | 226 | * es_MX es_MX es_419 |
| | 227 | * es_MX |
| | 228 | * language ↓ |
| | 229 | * es Spanish es es es es es |
| | 230 | * es-ES Spanish es es es es_ES, es_ES, |
| | 231 | * es es |
| | 232 | * es-419 Spanish es es_419, es_419, es es_419, |
| | 233 | * es es es |
| | 234 | * es-MX Spanish es_MX, es_419, es_MX, es_MX, es_MX, |
| | 235 | * es es es_419,es es es_419,es |
| | 236 | * es-AR Spanish es es_419, es_419, es es_419, |
| | 237 | * es es es |
| | 238 | * -------- |
| | 239 | * lproj sets → list1 list2 list3 list4 list5 list6 |
| | 240 | * Portuguese pt pt pt |
| | 241 | * pt_PT pt_BR pt_BR |
| | 242 | * pt_PT |
| | 243 | * language ↓ |
| | 244 | * pt Portuguese pt pt pt |
| | 245 | * pt-BR Portuguese pt pt_BR, pt_BR, |
| | 246 | * pt pt |
| | 247 | * pt-PT Portuguese pt_PT, pt_PT, pt |
| | 248 | * pt pt |
| | 249 | * pt-MO Portuguese pt_PT, pt_PT, pt |
| | 250 | * pt pt |
| | 251 | * ========================= |
| | 252 | * |
| | 253 | * @param preferredLanguages |
| | 254 | * Ordered array of pointers to user's preferred language |
| | 255 | * codes (BCP47 style null-terminated ASCII strings), in |
| | 256 | * order from most preferred; intended to accept the |
| | 257 | * contents of AppleLanguages. Must not be NULL. |
| | 258 | * Entries with the following values will be ignored: |
| | 259 | * NULL, "", "root", any entry beginning with '-' or '_'. |
| | 260 | * @param preferredLanguagesCount |
| | 261 | * Count of entries in preferredLanguages. |
| | 262 | * @param availableLocalizations |
| | 263 | * Unordered array of pointers to identifiers for available |
| | 264 | * localizations (lprojs); handles old Apple-style |
| | 265 | * identifiers such as "English", as well as currently- |
| | 266 | * superseded identifiers such as "no", "tl". Must not be |
| | 267 | * NULL. Entries with the following values will be ignored: |
| | 268 | * NULL, "", "root", any entry beginning with '-' or '_'. |
| | 269 | * @param availableLocalizationsCount |
| | 270 | * Count of entries in availableLocalizations. |
| | 271 | * @param localizationsToUse |
| | 272 | * Caller-provided array to be filled with pointers to |
| | 273 | * localizations to use in the availableLocalizations |
| | 274 | * array; these are entries from availableLocalizations |
| | 275 | * that correspond to the first language in |
| | 276 | * preferredLanguages for which there is any entry in |
| | 277 | * availableLocalizations that is a reasonable match, |
| | 278 | * with the best-matching localization first in |
| | 279 | * localizationsToUse, followed by any other possible |
| | 280 | * fallback localizations (for example, "en_IN" in |
| | 281 | * preferredLanguages might produce { "en_GB, "en" } in |
| | 282 | * localizationsToUse). Must not be NULL. This need not |
| | 283 | * large enough to accomodate all of the localizations |
| | 284 | * that might be returned; it is perfectly reasonable |
| | 285 | * (and more efficient) to only provide an array with |
| | 286 | * one entry, if that is all that you are planning to use. |
| | 287 | * @param localizationsToUseCapacity |
| | 288 | * The capacity of localizationsToUse. |
| | 289 | * @param status |
| | 290 | * A pointer to a UErrorCode to receive any errors. |
| | 291 | * @return |
| | 292 | * The number of entries filled out in localizationsToUse. |
| | 293 | * @draft ICU 55 |
| | 294 | */ |
| | 295 | U_DRAFT int32_t U_EXPORT2 |
| | 296 | ualoc_localizationsToUse( const char* const *preferredLanguages, |
| | 297 | int32_t preferredLanguagesCount, |
| | 298 | const char* const *availableLocalizations, |
| | 299 | int32_t availableLocalizationsCount, |
| | 300 | const char* *localizationsToUse, |
| | 301 | int32_t localizationsToUseCapacity, |
| | 302 | UErrorCode *status ); |
| | 303 | |
| | 304 | #endif /* U_HIDE_DRAFT_API */ |
| | 305 | #endif /*UALOC_H*/ |
projects / apple / icu.git / blame_incremental