| 1 | /* |
|---|---|
| 2 | ******************************************************************************* |
| 3 | * Copyright (c) 1996-2014, International Business Machines Corporation and others. |
| 4 | * All Rights Reserved. |
| 5 | ******************************************************************************* |
| 6 | */ |
| 7 | |
| 8 | #ifndef UCOL_H |
| 9 | #define UCOL_H |
| 10 | |
| 11 | #include "unicode/utypes.h" |
| 12 | |
| 13 | #if !UCONFIG_NO_COLLATION |
| 14 | |
| 15 | #include "unicode/unorm.h" |
| 16 | #include "unicode/localpointer.h" |
| 17 | #include "unicode/parseerr.h" |
| 18 | #include "unicode/uloc.h" |
| 19 | #include "unicode/uset.h" |
| 20 | #include "unicode/uscript.h" |
| 21 | |
| 22 | /** |
| 23 | * \file |
| 24 | * \brief C API: Collator |
| 25 | * |
| 26 | * <h2> Collator C API </h2> |
| 27 | * |
| 28 | * The C API for Collator performs locale-sensitive |
| 29 | * string comparison. You use this service to build |
| 30 | * searching and sorting routines for natural language text. |
| 31 | * <p> |
| 32 | * For more information about the collation service see |
| 33 | * <a href="http://userguide.icu-project.org/collation">the User Guide</a>. |
| 34 | * <p> |
| 35 | * Collation service provides correct sorting orders for most locales supported in ICU. |
| 36 | * If specific data for a locale is not available, the orders eventually falls back |
| 37 | * to the <a href="http://www.unicode.org/reports/tr35/tr35-collation.html#Root_Collation">CLDR root sort order</a>. |
| 38 | * <p> |
| 39 | * Sort ordering may be customized by providing your own set of rules. For more on |
| 40 | * this subject see the <a href="http://userguide.icu-project.org/collation/customization"> |
| 41 | * Collation Customization</a> section of the User Guide. |
| 42 | * <p> |
| 43 | * @see UCollationResult |
| 44 | * @see UNormalizationMode |
| 45 | * @see UCollationStrength |
| 46 | * @see UCollationElements |
| 47 | */ |
| 48 | |
| 49 | /** A collator. |
| 50 | * For usage in C programs. |
| 51 | */ |
| 52 | struct UCollator; |
| 53 | /** structure representing a collator object instance |
| 54 | * @stable ICU 2.0 |
| 55 | */ |
| 56 | typedef struct UCollator UCollator; |
| 57 | |
| 58 | |
| 59 | /** |
| 60 | * UCOL_LESS is returned if source string is compared to be less than target |
| 61 | * string in the ucol_strcoll() method. |
| 62 | * UCOL_EQUAL is returned if source string is compared to be equal to target |
| 63 | * string in the ucol_strcoll() method. |
| 64 | * UCOL_GREATER is returned if source string is compared to be greater than |
| 65 | * target string in the ucol_strcoll() method. |
| 66 | * @see ucol_strcoll() |
| 67 | * <p> |
| 68 | * Possible values for a comparison result |
| 69 | * @stable ICU 2.0 |
| 70 | */ |
| 71 | typedef enum { |
| 72 | /** string a == string b */ |
| 73 | UCOL_EQUAL = 0, |
| 74 | /** string a > string b */ |
| 75 | UCOL_GREATER = 1, |
| 76 | /** string a < string b */ |
| 77 | UCOL_LESS = -1 |
| 78 | } UCollationResult ; |
| 79 | |
| 80 | |
| 81 | /** Enum containing attribute values for controling collation behavior. |
| 82 | * Here are all the allowable values. Not every attribute can take every value. The only |
| 83 | * universal value is UCOL_DEFAULT, which resets the attribute value to the predefined |
| 84 | * value for that locale |
| 85 | * @stable ICU 2.0 |
| 86 | */ |
| 87 | typedef enum { |
| 88 | /** accepted by most attributes */ |
| 89 | UCOL_DEFAULT = -1, |
| 90 | |
| 91 | /** Primary collation strength */ |
| 92 | UCOL_PRIMARY = 0, |
| 93 | /** Secondary collation strength */ |
| 94 | UCOL_SECONDARY = 1, |
| 95 | /** Tertiary collation strength */ |
| 96 | UCOL_TERTIARY = 2, |
| 97 | /** Default collation strength */ |
| 98 | UCOL_DEFAULT_STRENGTH = UCOL_TERTIARY, |
| 99 | UCOL_CE_STRENGTH_LIMIT, |
| 100 | /** Quaternary collation strength */ |
| 101 | UCOL_QUATERNARY=3, |
| 102 | /** Identical collation strength */ |
| 103 | UCOL_IDENTICAL=15, |
| 104 | UCOL_STRENGTH_LIMIT, |
| 105 | |
| 106 | /** Turn the feature off - works for UCOL_FRENCH_COLLATION, |
| 107 | UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MODE |
| 108 | & UCOL_DECOMPOSITION_MODE*/ |
| 109 | UCOL_OFF = 16, |
| 110 | /** Turn the feature on - works for UCOL_FRENCH_COLLATION, |
| 111 | UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MODE |
| 112 | & UCOL_DECOMPOSITION_MODE*/ |
| 113 | UCOL_ON = 17, |
| 114 | |
| 115 | /** Valid for UCOL_ALTERNATE_HANDLING. Alternate handling will be shifted */ |
| 116 | UCOL_SHIFTED = 20, |
| 117 | /** Valid for UCOL_ALTERNATE_HANDLING. Alternate handling will be non ignorable */ |
| 118 | UCOL_NON_IGNORABLE = 21, |
| 119 | |
| 120 | /** Valid for UCOL_CASE_FIRST - |
| 121 | lower case sorts before upper case */ |
| 122 | UCOL_LOWER_FIRST = 24, |
| 123 | /** upper case sorts before lower case */ |
| 124 | UCOL_UPPER_FIRST = 25, |
| 125 | |
| 126 | UCOL_ATTRIBUTE_VALUE_COUNT |
| 127 | |
| 128 | } UColAttributeValue; |
| 129 | |
| 130 | /** |
| 131 | * Enum containing the codes for reordering segments of the collation table that are not script |
| 132 | * codes. These reordering codes are to be used in conjunction with the script codes. |
| 133 | * @see ucol_getReorderCodes |
| 134 | * @see ucol_setReorderCodes |
| 135 | * @see ucol_getEquivalentReorderCodes |
| 136 | * @see UScriptCode |
| 137 | * @stable ICU 4.8 |
| 138 | */ |
| 139 | typedef enum { |
| 140 | /** |
| 141 | * A special reordering code that is used to specify the default |
| 142 | * reordering codes for a locale. |
| 143 | * @stable ICU 4.8 |
| 144 | */ |
| 145 | UCOL_REORDER_CODE_DEFAULT = -1, |
| 146 | /** |
| 147 | * A special reordering code that is used to specify no reordering codes. |
| 148 | * @stable ICU 4.8 |
| 149 | */ |
| 150 | UCOL_REORDER_CODE_NONE = USCRIPT_UNKNOWN, |
| 151 | /** |
| 152 | * A special reordering code that is used to specify all other codes used for |
| 153 | * reordering except for the codes lised as UColReorderCode values and those |
| 154 | * listed explicitly in a reordering. |
| 155 | * @stable ICU 4.8 |
| 156 | */ |
| 157 | UCOL_REORDER_CODE_OTHERS = USCRIPT_UNKNOWN, |
| 158 | /** |
| 159 | * Characters with the space property. |
| 160 | * This is equivalent to the rule value "space". |
| 161 | * @stable ICU 4.8 |
| 162 | */ |
| 163 | UCOL_REORDER_CODE_SPACE = 0x1000, |
| 164 | /** |
| 165 | * The first entry in the enumeration of reordering groups. This is intended for use in |
| 166 | * range checking and enumeration of the reorder codes. |
| 167 | * @stable ICU 4.8 |
| 168 | */ |
| 169 | UCOL_REORDER_CODE_FIRST = UCOL_REORDER_CODE_SPACE, |
| 170 | /** |
| 171 | * Characters with the punctuation property. |
| 172 | * This is equivalent to the rule value "punct". |
| 173 | * @stable ICU 4.8 |
| 174 | */ |
| 175 | UCOL_REORDER_CODE_PUNCTUATION = 0x1001, |
| 176 | /** |
| 177 | * Characters with the symbol property. |
| 178 | * This is equivalent to the rule value "symbol". |
| 179 | * @stable ICU 4.8 |
| 180 | */ |
| 181 | UCOL_REORDER_CODE_SYMBOL = 0x1002, |
| 182 | /** |
| 183 | * Characters with the currency property. |
| 184 | * This is equivalent to the rule value "currency". |
| 185 | * @stable ICU 4.8 |
| 186 | */ |
| 187 | UCOL_REORDER_CODE_CURRENCY = 0x1003, |
| 188 | /** |
| 189 | * Characters with the digit property. |
| 190 | * This is equivalent to the rule value "digit". |
| 191 | * @stable ICU 4.8 |
| 192 | */ |
| 193 | UCOL_REORDER_CODE_DIGIT = 0x1004, |
| 194 | /** |
| 195 | * The limit of the reorder codes. This is intended for use in range checking |
| 196 | * and enumeration of the reorder codes. |
| 197 | * @stable ICU 4.8 |
| 198 | */ |
| 199 | UCOL_REORDER_CODE_LIMIT = 0x1005 |
| 200 | } UColReorderCode; |
| 201 | |
| 202 | /** |
| 203 | * Base letter represents a primary difference. Set comparison |
| 204 | * level to UCOL_PRIMARY to ignore secondary and tertiary differences. |
| 205 | * Use this to set the strength of a Collator object. |
| 206 | * Example of primary difference, "abc" < "abd" |
| 207 | * |
| 208 | * Diacritical differences on the same base letter represent a secondary |
| 209 | * difference. Set comparison level to UCOL_SECONDARY to ignore tertiary |
| 210 | * differences. Use this to set the strength of a Collator object. |
| 211 | * Example of secondary difference, "ä" >> "a". |
| 212 | * |
| 213 | * Uppercase and lowercase versions of the same character represents a |
| 214 | * tertiary difference. Set comparison level to UCOL_TERTIARY to include |
| 215 | * all comparison differences. Use this to set the strength of a Collator |
| 216 | * object. |
| 217 | * Example of tertiary difference, "abc" <<< "ABC". |
| 218 | * |
| 219 | * Two characters are considered "identical" when they have the same |
| 220 | * unicode spellings. UCOL_IDENTICAL. |
| 221 | * For example, "ä" == "ä". |
| 222 | * |
| 223 | * UCollationStrength is also used to determine the strength of sort keys |
| 224 | * generated from UCollator objects |
| 225 | * These values can be now found in the UColAttributeValue enum. |
| 226 | * @stable ICU 2.0 |
| 227 | **/ |
| 228 | typedef UColAttributeValue UCollationStrength; |
| 229 | |
| 230 | /** Attributes that collation service understands. All the attributes can take UCOL_DEFAULT |
| 231 | * value, as well as the values specific to each one. |
| 232 | * @stable ICU 2.0 |
| 233 | */ |
| 234 | typedef enum { |
| 235 | /** Attribute for direction of secondary weights - used in Canadian French. |
| 236 | * Acceptable values are UCOL_ON, which results in secondary weights |
| 237 | * being considered backwards and UCOL_OFF which treats secondary |
| 238 | * weights in the order they appear. |
| 239 | * @stable ICU 2.0 |
| 240 | */ |
| 241 | UCOL_FRENCH_COLLATION, |
| 242 | /** Attribute for handling variable elements. |
| 243 | * Acceptable values are UCOL_NON_IGNORABLE (default) |
| 244 | * which treats all the codepoints with non-ignorable |
| 245 | * primary weights in the same way, |
| 246 | * and UCOL_SHIFTED which causes codepoints with primary |
| 247 | * weights that are equal or below the variable top value |
| 248 | * to be ignored on primary level and moved to the quaternary |
| 249 | * level. |
| 250 | * @stable ICU 2.0 |
| 251 | */ |
| 252 | UCOL_ALTERNATE_HANDLING, |
| 253 | /** Controls the ordering of upper and lower case letters. |
| 254 | * Acceptable values are UCOL_OFF (default), which orders |
| 255 | * upper and lower case letters in accordance to their tertiary |
| 256 | * weights, UCOL_UPPER_FIRST which forces upper case letters to |
| 257 | * sort before lower case letters, and UCOL_LOWER_FIRST which does |
| 258 | * the opposite. |
| 259 | * @stable ICU 2.0 |
| 260 | */ |
| 261 | UCOL_CASE_FIRST, |
| 262 | /** Controls whether an extra case level (positioned before the third |
| 263 | * level) is generated or not. Acceptable values are UCOL_OFF (default), |
| 264 | * when case level is not generated, and UCOL_ON which causes the case |
| 265 | * level to be generated. Contents of the case level are affected by |
| 266 | * the value of UCOL_CASE_FIRST attribute. A simple way to ignore |
| 267 | * accent differences in a string is to set the strength to UCOL_PRIMARY |
| 268 | * and enable case level. |
| 269 | * @stable ICU 2.0 |
| 270 | */ |
| 271 | UCOL_CASE_LEVEL, |
| 272 | /** Controls whether the normalization check and necessary normalizations |
| 273 | * are performed. When set to UCOL_OFF (default) no normalization check |
| 274 | * is performed. The correctness of the result is guaranteed only if the |
| 275 | * input data is in so-called FCD form (see users manual for more info). |
| 276 | * When set to UCOL_ON, an incremental check is performed to see whether |
| 277 | * the input data is in the FCD form. If the data is not in the FCD form, |
| 278 | * incremental NFD normalization is performed. |
| 279 | * @stable ICU 2.0 |
| 280 | */ |
| 281 | UCOL_NORMALIZATION_MODE, |
| 282 | /** An alias for UCOL_NORMALIZATION_MODE attribute. |
| 283 | * @stable ICU 2.0 |
| 284 | */ |
| 285 | UCOL_DECOMPOSITION_MODE = UCOL_NORMALIZATION_MODE, |
| 286 | /** The strength attribute. Can be either UCOL_PRIMARY, UCOL_SECONDARY, |
| 287 | * UCOL_TERTIARY, UCOL_QUATERNARY or UCOL_IDENTICAL. The usual strength |
| 288 | * for most locales (except Japanese) is tertiary. |
| 289 | * |
| 290 | * Quaternary strength |
| 291 | * is useful when combined with shifted setting for alternate handling |
| 292 | * attribute and for JIS X 4061 collation, when it is used to distinguish |
| 293 | * between Katakana and Hiragana. |
| 294 | * Otherwise, quaternary level |
| 295 | * is affected only by the number of non-ignorable code points in |
| 296 | * the string. |
| 297 | * |
| 298 | * Identical strength is rarely useful, as it amounts |
| 299 | * to codepoints of the NFD form of the string. |
| 300 | * @stable ICU 2.0 |
| 301 | */ |
| 302 | UCOL_STRENGTH, |
| 303 | #ifndef U_HIDE_DEPRECATED_API |
| 304 | /** When turned on, this attribute positions Hiragana before all |
| 305 | * non-ignorables on quaternary level This is a sneaky way to produce JIS |
| 306 | * sort order. |
| 307 | * |
| 308 | * This attribute was an implementation detail of the CLDR Japanese tailoring. |
| 309 | * Since ICU 50, this attribute is not settable any more via API functions. |
| 310 | * Since CLDR 25/ICU 53, explicit quaternary relations are used |
| 311 | * to achieve the same Japanese sort order. |
| 312 | * |
| 313 | * @deprecated ICU 50 Implementation detail, cannot be set via API, was removed from implementation. |
| 314 | */ |
| 315 | UCOL_HIRAGANA_QUATERNARY_MODE = UCOL_STRENGTH + 1, |
| 316 | #endif /* U_HIDE_DEPRECATED_API */ |
| 317 | /** |
| 318 | * When turned on, this attribute makes |
| 319 | * substrings of digits sort according to their numeric values. |
| 320 | * |
| 321 | * This is a way to get '100' to sort AFTER '2'. Note that the longest |
| 322 | * digit substring that can be treated as a single unit is |
| 323 | * 254 digits (not counting leading zeros). If a digit substring is |
| 324 | * longer than that, the digits beyond the limit will be treated as a |
| 325 | * separate digit substring. |
| 326 | * |
| 327 | * A "digit" in this sense is a code point with General_Category=Nd, |
| 328 | * which does not include circled numbers, roman numerals, etc. |
| 329 | * Only a contiguous digit substring is considered, that is, |
| 330 | * non-negative integers without separators. |
| 331 | * There is no support for plus/minus signs, decimals, exponents, etc. |
| 332 | * |
| 333 | * @stable ICU 2.8 |
| 334 | */ |
| 335 | UCOL_NUMERIC_COLLATION = UCOL_STRENGTH + 2, |
| 336 | /** |
| 337 | * The number of UColAttribute constants. |
| 338 | * @stable ICU 2.0 |
| 339 | */ |
| 340 | UCOL_ATTRIBUTE_COUNT |
| 341 | } UColAttribute; |
| 342 | |
| 343 | /** Options for retrieving the rule string |
| 344 | * @stable ICU 2.0 |
| 345 | */ |
| 346 | typedef enum { |
| 347 | /** |
| 348 | * Retrieves the tailoring rules only. |
| 349 | * Same as calling the version of getRules() without UColRuleOption. |
| 350 | * @stable ICU 2.0 |
| 351 | */ |
| 352 | UCOL_TAILORING_ONLY, |
| 353 | /** |
| 354 | * Retrieves the "UCA rules" concatenated with the tailoring rules. |
| 355 | * The "UCA rules" are an <i>approximation</i> of the root collator's sort order. |
| 356 | * They are almost never used or useful at runtime and can be removed from the data. |
| 357 | * See http://userguide.icu-project.org/collation/customization#TOC-Building-on-Existing-Locales |
| 358 | * @stable ICU 2.0 |
| 359 | */ |
| 360 | UCOL_FULL_RULES |
| 361 | } UColRuleOption ; |
| 362 | |
| 363 | /** |
| 364 | * Open a UCollator for comparing strings. |
| 365 | * The UCollator pointer is used in all the calls to the Collation |
| 366 | * service. After finished, collator must be disposed of by calling |
| 367 | * {@link #ucol_close }. |
| 368 | * @param loc The locale containing the required collation rules. |
| 369 | * Special values for locales can be passed in - |
| 370 | * if NULL is passed for the locale, the default locale |
| 371 | * collation rules will be used. If empty string ("") or |
| 372 | * "root" are passed, the root collator will be returned. |
| 373 | * @param status A pointer to a UErrorCode to receive any errors |
| 374 | * @return A pointer to a UCollator, or 0 if an error occurred. |
| 375 | * @see ucol_openRules |
| 376 | * @see ucol_safeClone |
| 377 | * @see ucol_close |
| 378 | * @stable ICU 2.0 |
| 379 | */ |
| 380 | U_STABLE UCollator* U_EXPORT2 |
| 381 | ucol_open(const char *loc, UErrorCode *status); |
| 382 | |
| 383 | /** |
| 384 | * Produce a UCollator instance according to the rules supplied. |
| 385 | * The rules are used to change the default ordering, defined in the |
| 386 | * UCA in a process called tailoring. The resulting UCollator pointer |
| 387 | * can be used in the same way as the one obtained by {@link #ucol_strcoll }. |
| 388 | * @param rules A string describing the collation rules. For the syntax |
| 389 | * of the rules please see users guide. |
| 390 | * @param rulesLength The length of rules, or -1 if null-terminated. |
| 391 | * @param normalizationMode The normalization mode: One of |
| 392 | * UCOL_OFF (expect the text to not need normalization), |
| 393 | * UCOL_ON (normalize), or |
| 394 | * UCOL_DEFAULT (set the mode according to the rules) |
| 395 | * @param strength The default collation strength; one of UCOL_PRIMARY, UCOL_SECONDARY, |
| 396 | * UCOL_TERTIARY, UCOL_IDENTICAL,UCOL_DEFAULT_STRENGTH - can be also set in the rules. |
| 397 | * @param parseError A pointer to UParseError to recieve information about errors |
| 398 | * occurred during parsing. This argument can currently be set |
| 399 | * to NULL, but at users own risk. Please provide a real structure. |
| 400 | * @param status A pointer to a UErrorCode to receive any errors |
| 401 | * @return A pointer to a UCollator. It is not guaranteed that NULL be returned in case |
| 402 | * of error - please use status argument to check for errors. |
| 403 | * @see ucol_open |
| 404 | * @see ucol_safeClone |
| 405 | * @see ucol_close |
| 406 | * @stable ICU 2.0 |
| 407 | */ |
| 408 | U_STABLE UCollator* U_EXPORT2 |
| 409 | ucol_openRules( const UChar *rules, |
| 410 | int32_t rulesLength, |
| 411 | UColAttributeValue normalizationMode, |
| 412 | UCollationStrength strength, |
| 413 | UParseError *parseError, |
| 414 | UErrorCode *status); |
| 415 | |
| 416 | /** |
| 417 | * Open a collator defined by a short form string. |
| 418 | * The structure and the syntax of the string is defined in the "Naming collators" |
| 419 | * section of the users guide: |
| 420 | * http://userguide.icu-project.org/collation/concepts#TOC-Collator-naming-scheme |
| 421 | * Attributes are overriden by the subsequent attributes. So, for "S2_S3", final |
| 422 | * strength will be 3. 3066bis locale overrides individual locale parts. |
| 423 | * The call to this function is equivalent to a call to ucol_open, followed by a |
| 424 | * series of calls to ucol_setAttribute and ucol_setVariableTop. |
| 425 | * @param definition A short string containing a locale and a set of attributes. |
| 426 | * Attributes not explicitly mentioned are left at the default |
| 427 | * state for a locale. |
| 428 | * @param parseError if not NULL, structure that will get filled with error's pre |
| 429 | * and post context in case of error. |
| 430 | * @param forceDefaults if FALSE, the settings that are the same as the collator |
| 431 | * default settings will not be applied (for example, setting |
| 432 | * French secondary on a French collator would not be executed). |
| 433 | * If TRUE, all the settings will be applied regardless of the |
| 434 | * collator default value. If the definition |
| 435 | * strings are to be cached, should be set to FALSE. |
| 436 | * @param status Error code. Apart from regular error conditions connected to |
| 437 | * instantiating collators (like out of memory or similar), this |
| 438 | * API will return an error if an invalid attribute or attribute/value |
| 439 | * combination is specified. |
| 440 | * @return A pointer to a UCollator or 0 if an error occured (including an |
| 441 | * invalid attribute). |
| 442 | * @see ucol_open |
| 443 | * @see ucol_setAttribute |
| 444 | * @see ucol_setVariableTop |
| 445 | * @see ucol_getShortDefinitionString |
| 446 | * @see ucol_normalizeShortDefinitionString |
| 447 | * @stable ICU 3.0 |
| 448 | * |
| 449 | */ |
| 450 | U_STABLE UCollator* U_EXPORT2 |
| 451 | ucol_openFromShortString( const char *definition, |
| 452 | UBool forceDefaults, |
| 453 | UParseError *parseError, |
| 454 | UErrorCode *status); |
| 455 | |
| 456 | #ifndef U_HIDE_DEPRECATED_API |
| 457 | /** |
| 458 | * Get a set containing the contractions defined by the collator. The set includes |
| 459 | * both the root collator's contractions and the contractions defined by the collator. This set |
| 460 | * will contain only strings. If a tailoring explicitly suppresses contractions from |
| 461 | * the root collator (like Russian), removed contractions will not be in the resulting set. |
| 462 | * @param coll collator |
| 463 | * @param conts the set to hold the result. It gets emptied before |
| 464 | * contractions are added. |
| 465 | * @param status to hold the error code |
| 466 | * @return the size of the contraction set |
| 467 | * |
| 468 | * @deprecated ICU 3.4, use ucol_getContractionsAndExpansions instead |
| 469 | */ |
| 470 | U_DEPRECATED int32_t U_EXPORT2 |
| 471 | ucol_getContractions( const UCollator *coll, |
| 472 | USet *conts, |
| 473 | UErrorCode *status); |
| 474 | #endif /* U_HIDE_DEPRECATED_API */ |
| 475 | |
| 476 | /** |
| 477 | * Get a set containing the expansions defined by the collator. The set includes |
| 478 | * both the root collator's expansions and the expansions defined by the tailoring |
| 479 | * @param coll collator |
| 480 | * @param contractions if not NULL, the set to hold the contractions |
| 481 | * @param expansions if not NULL, the set to hold the expansions |
| 482 | * @param addPrefixes add the prefix contextual elements to contractions |
| 483 | * @param status to hold the error code |
| 484 | * |
| 485 | * @stable ICU 3.4 |
| 486 | */ |
| 487 | U_STABLE void U_EXPORT2 |
| 488 | ucol_getContractionsAndExpansions( const UCollator *coll, |
| 489 | USet *contractions, USet *expansions, |
| 490 | UBool addPrefixes, UErrorCode *status); |
| 491 | |
| 492 | /** |
| 493 | * Close a UCollator. |
| 494 | * Once closed, a UCollator should not be used. Every open collator should |
| 495 | * be closed. Otherwise, a memory leak will result. |
| 496 | * @param coll The UCollator to close. |
| 497 | * @see ucol_open |
| 498 | * @see ucol_openRules |
| 499 | * @see ucol_safeClone |
| 500 | * @stable ICU 2.0 |
| 501 | */ |
| 502 | U_STABLE void U_EXPORT2 |
| 503 | ucol_close(UCollator *coll); |
| 504 | |
| 505 | #if U_SHOW_CPLUSPLUS_API |
| 506 | |
| 507 | U_NAMESPACE_BEGIN |
| 508 | |
| 509 | /** |
| 510 | * \class LocalUCollatorPointer |
| 511 | * "Smart pointer" class, closes a UCollator via ucol_close(). |
| 512 | * For most methods see the LocalPointerBase base class. |
| 513 | * |
| 514 | * @see LocalPointerBase |
| 515 | * @see LocalPointer |
| 516 | * @stable ICU 4.4 |
| 517 | */ |
| 518 | U_DEFINE_LOCAL_OPEN_POINTER(LocalUCollatorPointer, UCollator, ucol_close); |
| 519 | |
| 520 | U_NAMESPACE_END |
| 521 | |
| 522 | #endif |
| 523 | |
| 524 | /** |
| 525 | * Compare two strings. |
| 526 | * The strings will be compared using the options already specified. |
| 527 | * @param coll The UCollator containing the comparison rules. |
| 528 | * @param source The source string. |
| 529 | * @param sourceLength The length of source, or -1 if null-terminated. |
| 530 | * @param target The target string. |
| 531 | * @param targetLength The length of target, or -1 if null-terminated. |
| 532 | * @return The result of comparing the strings; one of UCOL_EQUAL, |
| 533 | * UCOL_GREATER, UCOL_LESS |
| 534 | * @see ucol_greater |
| 535 | * @see ucol_greaterOrEqual |
| 536 | * @see ucol_equal |
| 537 | * @stable ICU 2.0 |
| 538 | */ |
| 539 | U_STABLE UCollationResult U_EXPORT2 |
| 540 | ucol_strcoll( const UCollator *coll, |
| 541 | const UChar *source, |
| 542 | int32_t sourceLength, |
| 543 | const UChar *target, |
| 544 | int32_t targetLength); |
| 545 | |
| 546 | /** |
| 547 | * Compare two strings in UTF-8. |
| 548 | * The strings will be compared using the options already specified. |
| 549 | * Note: When input string contains malformed a UTF-8 byte sequence, |
| 550 | * this function treats these bytes as REPLACEMENT CHARACTER (U+FFFD). |
| 551 | * @param coll The UCollator containing the comparison rules. |
| 552 | * @param source The source UTF-8 string. |
| 553 | * @param sourceLength The length of source, or -1 if null-terminated. |
| 554 | * @param target The target UTF-8 string. |
| 555 | * @param targetLength The length of target, or -1 if null-terminated. |
| 556 | * @param status A pointer to a UErrorCode to receive any errors |
| 557 | * @return The result of comparing the strings; one of UCOL_EQUAL, |
| 558 | * UCOL_GREATER, UCOL_LESS |
| 559 | * @see ucol_greater |
| 560 | * @see ucol_greaterOrEqual |
| 561 | * @see ucol_equal |
| 562 | * @stable ICU 50 |
| 563 | */ |
| 564 | U_STABLE UCollationResult U_EXPORT2 |
| 565 | ucol_strcollUTF8( |
| 566 | const UCollator *coll, |
| 567 | const char *source, |
| 568 | int32_t sourceLength, |
| 569 | const char *target, |
| 570 | int32_t targetLength, |
| 571 | UErrorCode *status); |
| 572 | |
| 573 | /** |
| 574 | * Determine if one string is greater than another. |
| 575 | * This function is equivalent to {@link #ucol_strcoll } == UCOL_GREATER |
| 576 | * @param coll The UCollator containing the comparison rules. |
| 577 | * @param source The source string. |
| 578 | * @param sourceLength The length of source, or -1 if null-terminated. |
| 579 | * @param target The target string. |
| 580 | * @param targetLength The length of target, or -1 if null-terminated. |
| 581 | * @return TRUE if source is greater than target, FALSE otherwise. |
| 582 | * @see ucol_strcoll |
| 583 | * @see ucol_greaterOrEqual |
| 584 | * @see ucol_equal |
| 585 | * @stable ICU 2.0 |
| 586 | */ |
| 587 | U_STABLE UBool U_EXPORT2 |
| 588 | ucol_greater(const UCollator *coll, |
| 589 | const UChar *source, int32_t sourceLength, |
| 590 | const UChar *target, int32_t targetLength); |
| 591 | |
| 592 | /** |
| 593 | * Determine if one string is greater than or equal to another. |
| 594 | * This function is equivalent to {@link #ucol_strcoll } != UCOL_LESS |
| 595 | * @param coll The UCollator containing the comparison rules. |
| 596 | * @param source The source string. |
| 597 | * @param sourceLength The length of source, or -1 if null-terminated. |
| 598 | * @param target The target string. |
| 599 | * @param targetLength The length of target, or -1 if null-terminated. |
| 600 | * @return TRUE if source is greater than or equal to target, FALSE otherwise. |
| 601 | * @see ucol_strcoll |
| 602 | * @see ucol_greater |
| 603 | * @see ucol_equal |
| 604 | * @stable ICU 2.0 |
| 605 | */ |
| 606 | U_STABLE UBool U_EXPORT2 |
| 607 | ucol_greaterOrEqual(const UCollator *coll, |
| 608 | const UChar *source, int32_t sourceLength, |
| 609 | const UChar *target, int32_t targetLength); |
| 610 | |
| 611 | /** |
| 612 | * Compare two strings for equality. |
| 613 | * This function is equivalent to {@link #ucol_strcoll } == UCOL_EQUAL |
| 614 | * @param coll The UCollator containing the comparison rules. |
| 615 | * @param source The source string. |
| 616 | * @param sourceLength The length of source, or -1 if null-terminated. |
| 617 | * @param target The target string. |
| 618 | * @param targetLength The length of target, or -1 if null-terminated. |
| 619 | * @return TRUE if source is equal to target, FALSE otherwise |
| 620 | * @see ucol_strcoll |
| 621 | * @see ucol_greater |
| 622 | * @see ucol_greaterOrEqual |
| 623 | * @stable ICU 2.0 |
| 624 | */ |
| 625 | U_STABLE UBool U_EXPORT2 |
| 626 | ucol_equal(const UCollator *coll, |
| 627 | const UChar *source, int32_t sourceLength, |
| 628 | const UChar *target, int32_t targetLength); |
| 629 | |
| 630 | /** |
| 631 | * Compare two UTF-8 encoded trings. |
| 632 | * The strings will be compared using the options already specified. |
| 633 | * @param coll The UCollator containing the comparison rules. |
| 634 | * @param sIter The source string iterator. |
| 635 | * @param tIter The target string iterator. |
| 636 | * @return The result of comparing the strings; one of UCOL_EQUAL, |
| 637 | * UCOL_GREATER, UCOL_LESS |
| 638 | * @param status A pointer to a UErrorCode to receive any errors |
| 639 | * @see ucol_strcoll |
| 640 | * @stable ICU 2.6 |
| 641 | */ |
| 642 | U_STABLE UCollationResult U_EXPORT2 |
| 643 | ucol_strcollIter( const UCollator *coll, |
| 644 | UCharIterator *sIter, |
| 645 | UCharIterator *tIter, |
| 646 | UErrorCode *status); |
| 647 | |
| 648 | /** |
| 649 | * Get the collation strength used in a UCollator. |
| 650 | * The strength influences how strings are compared. |
| 651 | * @param coll The UCollator to query. |
| 652 | * @return The collation strength; one of UCOL_PRIMARY, UCOL_SECONDARY, |
| 653 | * UCOL_TERTIARY, UCOL_QUATERNARY, UCOL_IDENTICAL |
| 654 | * @see ucol_setStrength |
| 655 | * @stable ICU 2.0 |
| 656 | */ |
| 657 | U_STABLE UCollationStrength U_EXPORT2 |
| 658 | ucol_getStrength(const UCollator *coll); |
| 659 | |
| 660 | /** |
| 661 | * Set the collation strength used in a UCollator. |
| 662 | * The strength influences how strings are compared. |
| 663 | * @param coll The UCollator to set. |
| 664 | * @param strength The desired collation strength; one of UCOL_PRIMARY, |
| 665 | * UCOL_SECONDARY, UCOL_TERTIARY, UCOL_QUATERNARY, UCOL_IDENTICAL, UCOL_DEFAULT |
| 666 | * @see ucol_getStrength |
| 667 | * @stable ICU 2.0 |
| 668 | */ |
| 669 | U_STABLE void U_EXPORT2 |
| 670 | ucol_setStrength(UCollator *coll, |
| 671 | UCollationStrength strength); |
| 672 | |
| 673 | /** |
| 674 | * Retrieves the reordering codes for this collator. |
| 675 | * These reordering codes are a combination of UScript codes and UColReorderCode entries. |
| 676 | * @param coll The UCollator to query. |
| 677 | * @param dest The array to fill with the script ordering. |
| 678 | * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the function |
| 679 | * will only return the length of the result without writing any of the result string (pre-flighting). |
| 680 | * @param pErrorCode Must be a valid pointer to an error code value, which must not indicate a |
| 681 | * failure before the function call. |
| 682 | * @return The number of reordering codes written to the dest array. |
| 683 | * @see ucol_setReorderCodes |
| 684 | * @see ucol_getEquivalentReorderCodes |
| 685 | * @see UScriptCode |
| 686 | * @see UColReorderCode |
| 687 | * @stable ICU 4.8 |
| 688 | */ |
| 689 | U_STABLE int32_t U_EXPORT2 |
| 690 | ucol_getReorderCodes(const UCollator* coll, |
| 691 | int32_t* dest, |
| 692 | int32_t destCapacity, |
| 693 | UErrorCode *pErrorCode); |
| 694 | /** |
| 695 | * Sets the reordering codes for this collator. |
| 696 | * Collation reordering allows scripts and some other defined blocks of characters |
| 697 | * to be moved relative to each other as a block. This reordering is done on top of |
| 698 | * the DUCET/CLDR standard collation order. Reordering can specify groups to be placed |
| 699 | * at the start and/or the end of the collation order. These groups are specified using |
| 700 | * UScript codes and UColReorderCode entries. |
| 701 | * <p>By default, reordering codes specified for the start of the order are placed in the |
| 702 | * order given after a group of "special" non-script blocks. These special groups of characters |
| 703 | * are space, punctuation, symbol, currency, and digit. These special groups are represented with |
| 704 | * UColReorderCode entries. Script groups can be intermingled with |
| 705 | * these special non-script blocks if those special blocks are explicitly specified in the reordering. |
| 706 | * <p>The special code OTHERS stands for any script that is not explicitly |
| 707 | * mentioned in the list of reordering codes given. Anything that is after OTHERS |
| 708 | * will go at the very end of the reordering in the order given. |
| 709 | * <p>The special reorder code DEFAULT will reset the reordering for this collator |
| 710 | * to the default for this collator. The default reordering may be the DUCET/CLDR order or may be a reordering that |
| 711 | * was specified when this collator was created from resource data or from rules. The |
| 712 | * DEFAULT code <b>must</b> be the sole code supplied when it used. If not |
| 713 | * that will result in a U_ILLEGAL_ARGUMENT_ERROR being set. |
| 714 | * <p>The special reorder code NONE will remove any reordering for this collator. |
| 715 | * The result of setting no reordering will be to have the DUCET/CLDR ordering used. The |
| 716 | * NONE code <b>must</b> be the sole code supplied when it used. |
| 717 | * @param coll The UCollator to set. |
| 718 | * @param reorderCodes An array of script codes in the new order. This can be NULL if the |
| 719 | * length is also set to 0. An empty array will clear any reordering codes on the collator. |
| 720 | * @param reorderCodesLength The length of reorderCodes. |
| 721 | * @param pErrorCode Must be a valid pointer to an error code value, which must not indicate a |
| 722 | * failure before the function call. |
| 723 | * @see ucol_getReorderCodes |
| 724 | * @see ucol_getEquivalentReorderCodes |
| 725 | * @see UScriptCode |
| 726 | * @see UColReorderCode |
| 727 | * @stable ICU 4.8 |
| 728 | */ |
| 729 | U_STABLE void U_EXPORT2 |
| 730 | ucol_setReorderCodes(UCollator* coll, |
| 731 | const int32_t* reorderCodes, |
| 732 | int32_t reorderCodesLength, |
| 733 | UErrorCode *pErrorCode); |
| 734 | |
| 735 | /** |
| 736 | * Retrieves the reorder codes that are grouped with the given reorder code. Some reorder |
| 737 | * codes will be grouped and must reorder together. |
| 738 | * @param reorderCode The reorder code to determine equivalence for. |
| 739 | * @param dest The array to fill with the script ordering. |
| 740 | * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the function |
| 741 | * will only return the length of the result without writing any of the result string (pre-flighting). |
| 742 | * @param pErrorCode Must be a valid pointer to an error code value, which must not indicate |
| 743 | * a failure before the function call. |
| 744 | * @return The number of reordering codes written to the dest array. |
| 745 | * @see ucol_setReorderCodes |
| 746 | * @see ucol_getReorderCodes |
| 747 | * @see UScriptCode |
| 748 | * @see UColReorderCode |
| 749 | * @stable ICU 4.8 |
| 750 | */ |
| 751 | U_STABLE int32_t U_EXPORT2 |
| 752 | ucol_getEquivalentReorderCodes(int32_t reorderCode, |
| 753 | int32_t* dest, |
| 754 | int32_t destCapacity, |
| 755 | UErrorCode *pErrorCode); |
| 756 | |
| 757 | /** |
| 758 | * Get the display name for a UCollator. |
| 759 | * The display name is suitable for presentation to a user. |
| 760 | * @param objLoc The locale of the collator in question. |
| 761 | * @param dispLoc The locale for display. |
| 762 | * @param result A pointer to a buffer to receive the attribute. |
| 763 | * @param resultLength The maximum size of result. |
| 764 | * @param status A pointer to a UErrorCode to receive any errors |
| 765 | * @return The total buffer size needed; if greater than resultLength, |
| 766 | * the output was truncated. |
| 767 | * @stable ICU 2.0 |
| 768 | */ |
| 769 | U_STABLE int32_t U_EXPORT2 |
| 770 | ucol_getDisplayName( const char *objLoc, |
| 771 | const char *dispLoc, |
| 772 | UChar *result, |
| 773 | int32_t resultLength, |
| 774 | UErrorCode *status); |
| 775 | |
| 776 | /** |
| 777 | * Get a locale for which collation rules are available. |
| 778 | * A UCollator in a locale returned by this function will perform the correct |
| 779 | * collation for the locale. |
| 780 | * @param localeIndex The index of the desired locale. |
| 781 | * @return A locale for which collation rules are available, or 0 if none. |
| 782 | * @see ucol_countAvailable |
| 783 | * @stable ICU 2.0 |
| 784 | */ |
| 785 | U_STABLE const char* U_EXPORT2 |
| 786 | ucol_getAvailable(int32_t localeIndex); |
| 787 | |
| 788 | /** |
| 789 | * Determine how many locales have collation rules available. |
| 790 | * This function is most useful as determining the loop ending condition for |
| 791 | * calls to {@link #ucol_getAvailable }. |
| 792 | * @return The number of locales for which collation rules are available. |
| 793 | * @see ucol_getAvailable |
| 794 | * @stable ICU 2.0 |
| 795 | */ |
| 796 | U_STABLE int32_t U_EXPORT2 |
| 797 | ucol_countAvailable(void); |
| 798 | |
| 799 | #if !UCONFIG_NO_SERVICE |
| 800 | /** |
| 801 | * Create a string enumerator of all locales for which a valid |
| 802 | * collator may be opened. |
| 803 | * @param status input-output error code |
| 804 | * @return a string enumeration over locale strings. The caller is |
| 805 | * responsible for closing the result. |
| 806 | * @stable ICU 3.0 |
| 807 | */ |
| 808 | U_STABLE UEnumeration* U_EXPORT2 |
| 809 | ucol_openAvailableLocales(UErrorCode *status); |
| 810 | #endif |
| 811 | |
| 812 | /** |
| 813 | * Create a string enumerator of all possible keywords that are relevant to |
| 814 | * collation. At this point, the only recognized keyword for this |
| 815 | * service is "collation". |
| 816 | * @param status input-output error code |
| 817 | * @return a string enumeration over locale strings. The caller is |
| 818 | * responsible for closing the result. |
| 819 | * @stable ICU 3.0 |
| 820 | */ |
| 821 | U_STABLE UEnumeration* U_EXPORT2 |
| 822 | ucol_getKeywords(UErrorCode *status); |
| 823 | |
| 824 | /** |
| 825 | * Given a keyword, create a string enumeration of all values |
| 826 | * for that keyword that are currently in use. |
| 827 | * @param keyword a particular keyword as enumerated by |
| 828 | * ucol_getKeywords. If any other keyword is passed in, *status is set |
| 829 | * to U_ILLEGAL_ARGUMENT_ERROR. |
| 830 | * @param status input-output error code |
| 831 | * @return a string enumeration over collation keyword values, or NULL |
| 832 | * upon error. The caller is responsible for closing the result. |
| 833 | * @stable ICU 3.0 |
| 834 | */ |
| 835 | U_STABLE UEnumeration* U_EXPORT2 |
| 836 | ucol_getKeywordValues(const char *keyword, UErrorCode *status); |
| 837 | |
| 838 | /** |
| 839 | * Given a key and a locale, returns an array of string values in a preferred |
| 840 | * order that would make a difference. These are all and only those values where |
| 841 | * the open (creation) of the service with the locale formed from the input locale |
| 842 | * plus input keyword and that value has different behavior than creation with the |
| 843 | * input locale alone. |
| 844 | * @param key one of the keys supported by this service. For now, only |
| 845 | * "collation" is supported. |
| 846 | * @param locale the locale |
| 847 | * @param commonlyUsed if set to true it will return only commonly used values |
| 848 | * with the given locale in preferred order. Otherwise, |
| 849 | * it will return all the available values for the locale. |
| 850 | * @param status error status |
| 851 | * @return a string enumeration over keyword values for the given key and the locale. |
| 852 | * @stable ICU 4.2 |
| 853 | */ |
| 854 | U_STABLE UEnumeration* U_EXPORT2 |
| 855 | ucol_getKeywordValuesForLocale(const char* key, |
| 856 | const char* locale, |
| 857 | UBool commonlyUsed, |
| 858 | UErrorCode* status); |
| 859 | |
| 860 | /** |
| 861 | * Return the functionally equivalent locale for the given |
| 862 | * requested locale, with respect to given keyword, for the |
| 863 | * collation service. If two locales return the same result, then |
| 864 | * collators instantiated for these locales will behave |
| 865 | * equivalently. The converse is not always true; two collators |
| 866 | * may in fact be equivalent, but return different results, due to |
| 867 | * internal details. The return result has no other meaning than |
| 868 | * that stated above, and implies nothing as to the relationship |
| 869 | * between the two locales. This is intended for use by |
| 870 | * applications who wish to cache collators, or otherwise reuse |
| 871 | * collators when possible. The functional equivalent may change |
| 872 | * over time. For more information, please see the <a |
| 873 | * href="http://userguide.icu-project.org/locale#TOC-Locales-and-Services"> |
| 874 | * Locales and Services</a> section of the ICU User Guide. |
| 875 | * @param result fillin for the functionally equivalent locale |
| 876 | * @param resultCapacity capacity of the fillin buffer |
| 877 | * @param keyword a particular keyword as enumerated by |
| 878 | * ucol_getKeywords. |
| 879 | * @param locale the requested locale |
| 880 | * @param isAvailable if non-NULL, pointer to a fillin parameter that |
| 881 | * indicates whether the requested locale was 'available' to the |
| 882 | * collation service. A locale is defined as 'available' if it |
| 883 | * physically exists within the collation locale data. |
| 884 | * @param status pointer to input-output error code |
| 885 | * @return the actual buffer size needed for the locale. If greater |
| 886 | * than resultCapacity, the returned full name will be truncated and |
| 887 | * an error code will be returned. |
| 888 | * @stable ICU 3.0 |
| 889 | */ |
| 890 | U_STABLE int32_t U_EXPORT2 |
| 891 | ucol_getFunctionalEquivalent(char* result, int32_t resultCapacity, |
| 892 | const char* keyword, const char* locale, |
| 893 | UBool* isAvailable, UErrorCode* status); |
| 894 | |
| 895 | /** |
| 896 | * Get the collation tailoring rules from a UCollator. |
| 897 | * The rules will follow the rule syntax. |
| 898 | * @param coll The UCollator to query. |
| 899 | * @param length |
| 900 | * @return The collation tailoring rules. |
| 901 | * @stable ICU 2.0 |
| 902 | */ |
| 903 | U_STABLE const UChar* U_EXPORT2 |
| 904 | ucol_getRules( const UCollator *coll, |
| 905 | int32_t *length); |
| 906 | |
| 907 | /** Get the short definition string for a collator. This API harvests the collator's |
| 908 | * locale and the attribute set and produces a string that can be used for opening |
| 909 | * a collator with the same attributes using the ucol_openFromShortString API. |
| 910 | * This string will be normalized. |
| 911 | * The structure and the syntax of the string is defined in the "Naming collators" |
| 912 | * section of the users guide: |
| 913 | * http://userguide.icu-project.org/collation/concepts#TOC-Collator-naming-scheme |
| 914 | * This API supports preflighting. |
| 915 | * @param coll a collator |
| 916 | * @param locale a locale that will appear as a collators locale in the resulting |
| 917 | * short string definition. If NULL, the locale will be harvested |
| 918 | * from the collator. |
| 919 | * @param buffer space to hold the resulting string |
| 920 | * @param capacity capacity of the buffer |
| 921 | * @param status for returning errors. All the preflighting errors are featured |
| 922 | * @return length of the resulting string |
| 923 | * @see ucol_openFromShortString |
| 924 | * @see ucol_normalizeShortDefinitionString |
| 925 | * @stable ICU 3.0 |
| 926 | */ |
| 927 | U_STABLE int32_t U_EXPORT2 |
| 928 | ucol_getShortDefinitionString(const UCollator *coll, |
| 929 | const char *locale, |
| 930 | char *buffer, |
| 931 | int32_t capacity, |
| 932 | UErrorCode *status); |
| 933 | |
| 934 | /** Verifies and normalizes short definition string. |
| 935 | * Normalized short definition string has all the option sorted by the argument name, |
| 936 | * so that equivalent definition strings are the same. |
| 937 | * This API supports preflighting. |
| 938 | * @param source definition string |
| 939 | * @param destination space to hold the resulting string |
| 940 | * @param capacity capacity of the buffer |
| 941 | * @param parseError if not NULL, structure that will get filled with error's pre |
| 942 | * and post context in case of error. |
| 943 | * @param status Error code. This API will return an error if an invalid attribute |
| 944 | * or attribute/value combination is specified. All the preflighting |
| 945 | * errors are also featured |
| 946 | * @return length of the resulting normalized string. |
| 947 | * |
| 948 | * @see ucol_openFromShortString |
| 949 | * @see ucol_getShortDefinitionString |
| 950 | * |
| 951 | * @stable ICU 3.0 |
| 952 | */ |
| 953 | |
| 954 | U_STABLE int32_t U_EXPORT2 |
| 955 | ucol_normalizeShortDefinitionString(const char *source, |
| 956 | char *destination, |
| 957 | int32_t capacity, |
| 958 | UParseError *parseError, |
| 959 | UErrorCode *status); |
| 960 | |
| 961 | |
| 962 | /** |
| 963 | * Get a sort key for a string from a UCollator. |
| 964 | * Sort keys may be compared using <TT>strcmp</TT>. |
| 965 | * |
| 966 | * Like ICU functions that write to an output buffer, the buffer contents |
| 967 | * is undefined if the buffer capacity (resultLength parameter) is too small. |
| 968 | * Unlike ICU functions that write a string to an output buffer, |
| 969 | * the terminating zero byte is counted in the sort key length. |
| 970 | * @param coll The UCollator containing the collation rules. |
| 971 | * @param source The string to transform. |
| 972 | * @param sourceLength The length of source, or -1 if null-terminated. |
| 973 | * @param result A pointer to a buffer to receive the attribute. |
| 974 | * @param resultLength The maximum size of result. |
| 975 | * @return The size needed to fully store the sort key. |
| 976 | * If there was an internal error generating the sort key, |
| 977 | * a zero value is returned. |
| 978 | * @see ucol_keyHashCode |
| 979 | * @stable ICU 2.0 |
| 980 | */ |
| 981 | U_STABLE int32_t U_EXPORT2 |
| 982 | ucol_getSortKey(const UCollator *coll, |
| 983 | const UChar *source, |
| 984 | int32_t sourceLength, |
| 985 | uint8_t *result, |
| 986 | int32_t resultLength); |
| 987 | |
| 988 | |
| 989 | /** Gets the next count bytes of a sort key. Caller needs |
| 990 | * to preserve state array between calls and to provide |
| 991 | * the same type of UCharIterator set with the same string. |
| 992 | * The destination buffer provided must be big enough to store |
| 993 | * the number of requested bytes. |
| 994 | * |
| 995 | * The generated sort key may or may not be compatible with |
| 996 | * sort keys generated using ucol_getSortKey(). |
| 997 | * @param coll The UCollator containing the collation rules. |
| 998 | * @param iter UCharIterator containing the string we need |
| 999 | * the sort key to be calculated for. |
| 1000 | * @param state Opaque state of sortkey iteration. |
| 1001 | * @param dest Buffer to hold the resulting sortkey part |
| 1002 | * @param count number of sort key bytes required. |
| 1003 | * @param status error code indicator. |
| 1004 | * @return the actual number of bytes of a sortkey. It can be |
| 1005 | * smaller than count if we have reached the end of |
| 1006 | * the sort key. |
| 1007 | * @stable ICU 2.6 |
| 1008 | */ |
| 1009 | U_STABLE int32_t U_EXPORT2 |
| 1010 | ucol_nextSortKeyPart(const UCollator *coll, |
| 1011 | UCharIterator *iter, |
| 1012 | uint32_t state[2], |
| 1013 | uint8_t *dest, int32_t count, |
| 1014 | UErrorCode *status); |
| 1015 | |
| 1016 | /** enum that is taken by ucol_getBound API |
| 1017 | * See below for explanation |
| 1018 | * do not change the values assigned to the |
| 1019 | * members of this enum. Underlying code |
| 1020 | * depends on them having these numbers |
| 1021 | * @stable ICU 2.0 |
| 1022 | */ |
| 1023 | typedef enum { |
| 1024 | /** lower bound */ |
| 1025 | UCOL_BOUND_LOWER = 0, |
| 1026 | /** upper bound that will match strings of exact size */ |
| 1027 | UCOL_BOUND_UPPER = 1, |
| 1028 | /** upper bound that will match all the strings that have the same initial substring as the given string */ |
| 1029 | UCOL_BOUND_UPPER_LONG = 2, |
| 1030 | UCOL_BOUND_VALUE_COUNT |
| 1031 | } UColBoundMode; |
| 1032 | |
| 1033 | /** |
| 1034 | * Produce a bound for a given sortkey and a number of levels. |
| 1035 | * Return value is always the number of bytes needed, regardless of |
| 1036 | * whether the result buffer was big enough or even valid.<br> |
| 1037 | * Resulting bounds can be used to produce a range of strings that are |
| 1038 | * between upper and lower bounds. For example, if bounds are produced |
| 1039 | * for a sortkey of string "smith", strings between upper and lower |
| 1040 | * bounds with one level would include "Smith", "SMITH", "sMiTh".<br> |
| 1041 | * There are two upper bounds that can be produced. If UCOL_BOUND_UPPER |
| 1042 | * is produced, strings matched would be as above. However, if bound |
| 1043 | * produced using UCOL_BOUND_UPPER_LONG is used, the above example will |
| 1044 | * also match "Smithsonian" and similar.<br> |
| 1045 | * For more on usage, see example in cintltst/capitst.c in procedure |
| 1046 | * TestBounds. |
| 1047 | * Sort keys may be compared using <TT>strcmp</TT>. |
| 1048 | * @param source The source sortkey. |
| 1049 | * @param sourceLength The length of source, or -1 if null-terminated. |
| 1050 | * (If an unmodified sortkey is passed, it is always null |
| 1051 | * terminated). |
| 1052 | * @param boundType Type of bound required. It can be UCOL_BOUND_LOWER, which |
| 1053 | * produces a lower inclusive bound, UCOL_BOUND_UPPER, that |
| 1054 | * produces upper bound that matches strings of the same length |
| 1055 | * or UCOL_BOUND_UPPER_LONG that matches strings that have the |
| 1056 | * same starting substring as the source string. |
| 1057 | * @param noOfLevels Number of levels required in the resulting bound (for most |
| 1058 | * uses, the recommended value is 1). See users guide for |
| 1059 | * explanation on number of levels a sortkey can have. |
| 1060 | * @param result A pointer to a buffer to receive the resulting sortkey. |
| 1061 | * @param resultLength The maximum size of result. |
| 1062 | * @param status Used for returning error code if something went wrong. If the |
| 1063 | * number of levels requested is higher than the number of levels |
| 1064 | * in the source key, a warning (U_SORT_KEY_TOO_SHORT_WARNING) is |
| 1065 | * issued. |
| 1066 | * @return The size needed to fully store the bound. |
| 1067 | * @see ucol_keyHashCode |
| 1068 | * @stable ICU 2.1 |
| 1069 | */ |
| 1070 | U_STABLE int32_t U_EXPORT2 |
| 1071 | ucol_getBound(const uint8_t *source, |
| 1072 | int32_t sourceLength, |
| 1073 | UColBoundMode boundType, |
| 1074 | uint32_t noOfLevels, |
| 1075 | uint8_t *result, |
| 1076 | int32_t resultLength, |
| 1077 | UErrorCode *status); |
| 1078 | |
| 1079 | /** |
| 1080 | * Gets the version information for a Collator. Version is currently |
| 1081 | * an opaque 32-bit number which depends, among other things, on major |
| 1082 | * versions of the collator tailoring and UCA. |
| 1083 | * @param coll The UCollator to query. |
| 1084 | * @param info the version # information, the result will be filled in |
| 1085 | * @stable ICU 2.0 |
| 1086 | */ |
| 1087 | U_STABLE void U_EXPORT2 |
| 1088 | ucol_getVersion(const UCollator* coll, UVersionInfo info); |
| 1089 | |
| 1090 | /** |
| 1091 | * Gets the UCA version information for a Collator. Version is the |
| 1092 | * UCA version number (3.1.1, 4.0). |
| 1093 | * @param coll The UCollator to query. |
| 1094 | * @param info the version # information, the result will be filled in |
| 1095 | * @stable ICU 2.8 |
| 1096 | */ |
| 1097 | U_STABLE void U_EXPORT2 |
| 1098 | ucol_getUCAVersion(const UCollator* coll, UVersionInfo info); |
| 1099 | |
| 1100 | /** |
| 1101 | * Merges two sort keys. The levels are merged with their corresponding counterparts |
| 1102 | * (primaries with primaries, secondaries with secondaries etc.). Between the values |
| 1103 | * from the same level a separator is inserted. |
| 1104 | * |
| 1105 | * This is useful, for example, for combining sort keys from first and last names |
| 1106 | * to sort such pairs. |
| 1107 | * It is possible to merge multiple sort keys by consecutively merging |
| 1108 | * another one with the intermediate result. |
| 1109 | * |
| 1110 | * The length of the merge result is the sum of the lengths of the input sort keys. |
| 1111 | * |
| 1112 | * Example (uncompressed): |
| 1113 | * <pre>191B1D 01 050505 01 910505 00 |
| 1114 | * 1F2123 01 050505 01 910505 00</pre> |
| 1115 | * will be merged as |
| 1116 | * <pre>191B1D 02 1F2123 01 050505 02 050505 01 910505 02 910505 00</pre> |
| 1117 | * |
| 1118 | * If the destination buffer is not big enough, then its contents are undefined. |
| 1119 | * If any of source lengths are zero or any of the source pointers are NULL/undefined, |
| 1120 | * the result is of size zero. |
| 1121 | * |
| 1122 | * @param src1 the first sort key |
| 1123 | * @param src1Length the length of the first sort key, including the zero byte at the end; |
| 1124 | * can be -1 if the function is to find the length |
| 1125 | * @param src2 the second sort key |
| 1126 | * @param src2Length the length of the second sort key, including the zero byte at the end; |
| 1127 | * can be -1 if the function is to find the length |
| 1128 | * @param dest the buffer where the merged sort key is written, |
| 1129 | * can be NULL if destCapacity==0 |
| 1130 | * @param destCapacity the number of bytes in the dest buffer |
| 1131 | * @return the length of the merged sort key, src1Length+src2Length; |
| 1132 | * can be larger than destCapacity, or 0 if an error occurs (only for illegal arguments), |
| 1133 | * in which cases the contents of dest is undefined |
| 1134 | * @stable ICU 2.0 |
| 1135 | */ |
| 1136 | U_STABLE int32_t U_EXPORT2 |
| 1137 | ucol_mergeSortkeys(const uint8_t *src1, int32_t src1Length, |
| 1138 | const uint8_t *src2, int32_t src2Length, |
| 1139 | uint8_t *dest, int32_t destCapacity); |
| 1140 | |
| 1141 | /** |
| 1142 | * Universal attribute setter |
| 1143 | * @param coll collator which attributes are to be changed |
| 1144 | * @param attr attribute type |
| 1145 | * @param value attribute value |
| 1146 | * @param status to indicate whether the operation went on smoothly or there were errors |
| 1147 | * @see UColAttribute |
| 1148 | * @see UColAttributeValue |
| 1149 | * @see ucol_getAttribute |
| 1150 | * @stable ICU 2.0 |
| 1151 | */ |
| 1152 | U_STABLE void U_EXPORT2 |
| 1153 | ucol_setAttribute(UCollator *coll, UColAttribute attr, UColAttributeValue value, UErrorCode *status); |
| 1154 | |
| 1155 | /** |
| 1156 | * Universal attribute getter |
| 1157 | * @param coll collator which attributes are to be changed |
| 1158 | * @param attr attribute type |
| 1159 | * @return attribute value |
| 1160 | * @param status to indicate whether the operation went on smoothly or there were errors |
| 1161 | * @see UColAttribute |
| 1162 | * @see UColAttributeValue |
| 1163 | * @see ucol_setAttribute |
| 1164 | * @stable ICU 2.0 |
| 1165 | */ |
| 1166 | U_STABLE UColAttributeValue U_EXPORT2 |
| 1167 | ucol_getAttribute(const UCollator *coll, UColAttribute attr, UErrorCode *status); |
| 1168 | |
| 1169 | #ifndef U_HIDE_DRAFT_API |
| 1170 | |
| 1171 | /** |
| 1172 | * Sets the variable top to the top of the specified reordering group. |
| 1173 | * The variable top determines the highest-sorting character |
| 1174 | * which is affected by UCOL_ALTERNATE_HANDLING. |
| 1175 | * If that attribute is set to UCOL_NON_IGNORABLE, then the variable top has no effect. |
| 1176 | * @param coll the collator |
| 1177 | * @param group one of UCOL_REORDER_CODE_SPACE, UCOL_REORDER_CODE_PUNCTUATION, |
| 1178 | * UCOL_REORDER_CODE_SYMBOL, UCOL_REORDER_CODE_CURRENCY; |
| 1179 | * or UCOL_REORDER_CODE_DEFAULT to restore the default max variable group |
| 1180 | * @param pErrorCode Standard ICU error code. Its input value must |
| 1181 | * pass the U_SUCCESS() test, or else the function returns |
| 1182 | * immediately. Check for U_FAILURE() on output or use with |
| 1183 | * function chaining. (See User Guide for details.) |
| 1184 | * @see ucol_getMaxVariable |
| 1185 | * @draft ICU 53 |
| 1186 | */ |
| 1187 | U_DRAFT void U_EXPORT2 |
| 1188 | ucol_setMaxVariable(UCollator *coll, UColReorderCode group, UErrorCode *pErrorCode); |
| 1189 | |
| 1190 | /** |
| 1191 | * Returns the maximum reordering group whose characters are affected by UCOL_ALTERNATE_HANDLING. |
| 1192 | * @param coll the collator |
| 1193 | * @return the maximum variable reordering group. |
| 1194 | * @see ucol_setMaxVariable |
| 1195 | * @draft ICU 53 |
| 1196 | */ |
| 1197 | U_DRAFT UColReorderCode U_EXPORT2 |
| 1198 | ucol_getMaxVariable(const UCollator *coll); |
| 1199 | |
| 1200 | #endif /* U_HIDE_DRAFT_API */ |
| 1201 | |
| 1202 | /** |
| 1203 | * Sets the variable top to the primary weight of the specified string. |
| 1204 | * |
| 1205 | * Beginning with ICU 53, the variable top is pinned to |
| 1206 | * the top of one of the supported reordering groups, |
| 1207 | * and it must not be beyond the last of those groups. |
| 1208 | * See ucol_setMaxVariable(). |
| 1209 | * @param coll the collator |
| 1210 | * @param varTop one or more (if contraction) UChars to which the variable top should be set |
| 1211 | * @param len length of variable top string. If -1 it is considered to be zero terminated. |
| 1212 | * @param status error code. If error code is set, the return value is undefined. |
| 1213 | * Errors set by this function are:<br> |
| 1214 | * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such contraction<br> |
| 1215 | * U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond |
| 1216 | * the last reordering group supported by ucol_setMaxVariable() |
| 1217 | * @return variable top primary weight |
| 1218 | * @see ucol_getVariableTop |
| 1219 | * @see ucol_restoreVariableTop |
| 1220 | * @deprecated ICU 53 Call ucol_setMaxVariable() instead. |
| 1221 | */ |
| 1222 | U_DEPRECATED uint32_t U_EXPORT2 |
| 1223 | ucol_setVariableTop(UCollator *coll, |
| 1224 | const UChar *varTop, int32_t len, |
| 1225 | UErrorCode *status); |
| 1226 | |
| 1227 | /** |
| 1228 | * Gets the variable top value of a Collator. |
| 1229 | * @param coll collator which variable top needs to be retrieved |
| 1230 | * @param status error code (not changed by function). If error code is set, |
| 1231 | * the return value is undefined. |
| 1232 | * @return the variable top primary weight |
| 1233 | * @see ucol_getMaxVariable |
| 1234 | * @see ucol_setVariableTop |
| 1235 | * @see ucol_restoreVariableTop |
| 1236 | * @stable ICU 2.0 |
| 1237 | */ |
| 1238 | U_STABLE uint32_t U_EXPORT2 ucol_getVariableTop(const UCollator *coll, UErrorCode *status); |
| 1239 | |
| 1240 | /** |
| 1241 | * Sets the variable top to the specified primary weight. |
| 1242 | * |
| 1243 | * Beginning with ICU 53, the variable top is pinned to |
| 1244 | * the top of one of the supported reordering groups, |
| 1245 | * and it must not be beyond the last of those groups. |
| 1246 | * See ucol_setMaxVariable(). |
| 1247 | * @param varTop primary weight, as returned by ucol_setVariableTop or ucol_getVariableTop |
| 1248 | * @param status error code |
| 1249 | * @see ucol_getVariableTop |
| 1250 | * @see ucol_setVariableTop |
| 1251 | * @deprecated ICU 53 Call ucol_setMaxVariable() instead. |
| 1252 | */ |
| 1253 | U_DEPRECATED void U_EXPORT2 |
| 1254 | ucol_restoreVariableTop(UCollator *coll, const uint32_t varTop, UErrorCode *status); |
| 1255 | |
| 1256 | /** |
| 1257 | * Thread safe cloning operation. The result is a clone of a given collator. |
| 1258 | * @param coll collator to be cloned |
| 1259 | * @param stackBuffer <em>Deprecated functionality as of ICU 52, use NULL.</em><br> |
| 1260 | * user allocated space for the new clone. |
| 1261 | * If NULL new memory will be allocated. |
| 1262 | * If buffer is not large enough, new memory will be allocated. |
| 1263 | * Clients can use the U_COL_SAFECLONE_BUFFERSIZE. |
| 1264 | * @param pBufferSize <em>Deprecated functionality as of ICU 52, use NULL or 1.</em><br> |
| 1265 | * pointer to size of allocated space. |
| 1266 | * If *pBufferSize == 0, a sufficient size for use in cloning will |
| 1267 | * be returned ('pre-flighting') |
| 1268 | * If *pBufferSize is not enough for a stack-based safe clone, |
| 1269 | * new memory will be allocated. |
| 1270 | * @param status to indicate whether the operation went on smoothly or there were errors |
| 1271 | * An informational status value, U_SAFECLONE_ALLOCATED_ERROR, is used if any |
| 1272 | * allocations were necessary. |
| 1273 | * @return pointer to the new clone |
| 1274 | * @see ucol_open |
| 1275 | * @see ucol_openRules |
| 1276 | * @see ucol_close |
| 1277 | * @stable ICU 2.0 |
| 1278 | */ |
| 1279 | U_STABLE UCollator* U_EXPORT2 |
| 1280 | ucol_safeClone(const UCollator *coll, |
| 1281 | void *stackBuffer, |
| 1282 | int32_t *pBufferSize, |
| 1283 | UErrorCode *status); |
| 1284 | |
| 1285 | #ifndef U_HIDE_DEPRECATED_API |
| 1286 | |
| 1287 | /** default memory size for the new clone. |
| 1288 | * @deprecated ICU 52. Do not rely on ucol_safeClone() cloning into any provided buffer. |
| 1289 | */ |
| 1290 | #define U_COL_SAFECLONE_BUFFERSIZE 1 |
| 1291 | |
| 1292 | #endif /* U_HIDE_DEPRECATED_API */ |
| 1293 | |
| 1294 | /** |
| 1295 | * Returns current rules. Delta defines whether full rules are returned or just the tailoring. |
| 1296 | * Returns number of UChars needed to store rules. If buffer is NULL or bufferLen is not enough |
| 1297 | * to store rules, will store up to available space. |
| 1298 | * |
| 1299 | * ucol_getRules() should normally be used instead. |
| 1300 | * See http://userguide.icu-project.org/collation/customization#TOC-Building-on-Existing-Locales |
| 1301 | * @param coll collator to get the rules from |
| 1302 | * @param delta one of UCOL_TAILORING_ONLY, UCOL_FULL_RULES. |
| 1303 | * @param buffer buffer to store the result in. If NULL, you'll get no rules. |
| 1304 | * @param bufferLen length of buffer to store rules in. If less than needed you'll get only the part that fits in. |
| 1305 | * @return current rules |
| 1306 | * @stable ICU 2.0 |
| 1307 | * @see UCOL_FULL_RULES |
| 1308 | */ |
| 1309 | U_STABLE int32_t U_EXPORT2 |
| 1310 | ucol_getRulesEx(const UCollator *coll, UColRuleOption delta, UChar *buffer, int32_t bufferLen); |
| 1311 | |
| 1312 | #ifndef U_HIDE_DEPRECATED_API |
| 1313 | /** |
| 1314 | * gets the locale name of the collator. If the collator |
| 1315 | * is instantiated from the rules, then this function returns |
| 1316 | * NULL. |
| 1317 | * @param coll The UCollator for which the locale is needed |
| 1318 | * @param type You can choose between requested, valid and actual |
| 1319 | * locale. For description see the definition of |
| 1320 | * ULocDataLocaleType in uloc.h |
| 1321 | * @param status error code of the operation |
| 1322 | * @return real locale name from which the collation data comes. |
| 1323 | * If the collator was instantiated from rules, returns |
| 1324 | * NULL. |
| 1325 | * @deprecated ICU 2.8 Use ucol_getLocaleByType instead |
| 1326 | */ |
| 1327 | U_DEPRECATED const char * U_EXPORT2 |
| 1328 | ucol_getLocale(const UCollator *coll, ULocDataLocaleType type, UErrorCode *status); |
| 1329 | #endif /* U_HIDE_DEPRECATED_API */ |
| 1330 | |
| 1331 | /** |
| 1332 | * gets the locale name of the collator. If the collator |
| 1333 | * is instantiated from the rules, then this function returns |
| 1334 | * NULL. |
| 1335 | * @param coll The UCollator for which the locale is needed |
| 1336 | * @param type You can choose between requested, valid and actual |
| 1337 | * locale. For description see the definition of |
| 1338 | * ULocDataLocaleType in uloc.h |
| 1339 | * @param status error code of the operation |
| 1340 | * @return real locale name from which the collation data comes. |
| 1341 | * If the collator was instantiated from rules, returns |
| 1342 | * NULL. |
| 1343 | * @stable ICU 2.8 |
| 1344 | */ |
| 1345 | U_STABLE const char * U_EXPORT2 |
| 1346 | ucol_getLocaleByType(const UCollator *coll, ULocDataLocaleType type, UErrorCode *status); |
| 1347 | |
| 1348 | /** |
| 1349 | * Get a Unicode set that contains all the characters and sequences tailored in |
| 1350 | * this collator. The result must be disposed of by using uset_close. |
| 1351 | * @param coll The UCollator for which we want to get tailored chars |
| 1352 | * @param status error code of the operation |
| 1353 | * @return a pointer to newly created USet. Must be be disposed by using uset_close |
| 1354 | * @see ucol_openRules |
| 1355 | * @see uset_close |
| 1356 | * @stable ICU 2.4 |
| 1357 | */ |
| 1358 | U_STABLE USet * U_EXPORT2 |
| 1359 | ucol_getTailoredSet(const UCollator *coll, UErrorCode *status); |
| 1360 | |
| 1361 | #ifndef U_HIDE_INTERNAL_API |
| 1362 | /** Calculates the set of unsafe code points, given a collator. |
| 1363 | * A character is unsafe if you could append any character and cause the ordering to alter significantly. |
| 1364 | * Collation sorts in normalized order, so anything that rearranges in normalization can cause this. |
| 1365 | * Thus if you have a character like a_umlaut, and you add a lower_dot to it, |
| 1366 | * then it normalizes to a_lower_dot + umlaut, and sorts differently. |
| 1367 | * @param coll Collator |
| 1368 | * @param unsafe a fill-in set to receive the unsafe points |
| 1369 | * @param status for catching errors |
| 1370 | * @return number of elements in the set |
| 1371 | * @internal ICU 3.0 |
| 1372 | */ |
| 1373 | U_INTERNAL int32_t U_EXPORT2 |
| 1374 | ucol_getUnsafeSet( const UCollator *coll, |
| 1375 | USet *unsafe, |
| 1376 | UErrorCode *status); |
| 1377 | |
| 1378 | /** Touches all resources needed for instantiating a collator from a short string definition, |
| 1379 | * thus filling up the cache. |
| 1380 | * @param definition A short string containing a locale and a set of attributes. |
| 1381 | * Attributes not explicitly mentioned are left at the default |
| 1382 | * state for a locale. |
| 1383 | * @param parseError if not NULL, structure that will get filled with error's pre |
| 1384 | * and post context in case of error. |
| 1385 | * @param forceDefaults if FALSE, the settings that are the same as the collator |
| 1386 | * default settings will not be applied (for example, setting |
| 1387 | * French secondary on a French collator would not be executed). |
| 1388 | * If TRUE, all the settings will be applied regardless of the |
| 1389 | * collator default value. If the definition |
| 1390 | * strings are to be cached, should be set to FALSE. |
| 1391 | * @param status Error code. Apart from regular error conditions connected to |
| 1392 | * instantiating collators (like out of memory or similar), this |
| 1393 | * API will return an error if an invalid attribute or attribute/value |
| 1394 | * combination is specified. |
| 1395 | * @see ucol_openFromShortString |
| 1396 | * @internal ICU 3.2.1 |
| 1397 | */ |
| 1398 | U_INTERNAL void U_EXPORT2 |
| 1399 | ucol_prepareShortStringOpen( const char *definition, |
| 1400 | UBool forceDefaults, |
| 1401 | UParseError *parseError, |
| 1402 | UErrorCode *status); |
| 1403 | #endif /* U_HIDE_INTERNAL_API */ |
| 1404 | |
| 1405 | /** Creates a binary image of a collator. This binary image can be stored and |
| 1406 | * later used to instantiate a collator using ucol_openBinary. |
| 1407 | * This API supports preflighting. |
| 1408 | * @param coll Collator |
| 1409 | * @param buffer a fill-in buffer to receive the binary image |
| 1410 | * @param capacity capacity of the destination buffer |
| 1411 | * @param status for catching errors |
| 1412 | * @return size of the image |
| 1413 | * @see ucol_openBinary |
| 1414 | * @stable ICU 3.2 |
| 1415 | */ |
| 1416 | U_STABLE int32_t U_EXPORT2 |
| 1417 | ucol_cloneBinary(const UCollator *coll, |
| 1418 | uint8_t *buffer, int32_t capacity, |
| 1419 | UErrorCode *status); |
| 1420 | |
| 1421 | /** Opens a collator from a collator binary image created using |
| 1422 | * ucol_cloneBinary. Binary image used in instantiation of the |
| 1423 | * collator remains owned by the user and should stay around for |
| 1424 | * the lifetime of the collator. The API also takes a base collator |
| 1425 | * which usually should be the root collator. |
| 1426 | * @param bin binary image owned by the user and required through the |
| 1427 | * lifetime of the collator |
| 1428 | * @param length size of the image. If negative, the API will try to |
| 1429 | * figure out the length of the image |
| 1430 | * @param base fallback collator, usually the root collator. Base is required to be |
| 1431 | * present through the lifetime of the collator. Currently |
| 1432 | * it cannot be NULL. |
| 1433 | * @param status for catching errors |
| 1434 | * @return newly created collator |
| 1435 | * @see ucol_cloneBinary |
| 1436 | * @stable ICU 3.2 |
| 1437 | */ |
| 1438 | U_STABLE UCollator* U_EXPORT2 |
| 1439 | ucol_openBinary(const uint8_t *bin, int32_t length, |
| 1440 | const UCollator *base, |
| 1441 | UErrorCode *status); |
| 1442 | |
| 1443 | |
| 1444 | #endif /* #if !UCONFIG_NO_COLLATION */ |
| 1445 | |
| 1446 | #endif |
| 1447 |
Generated while processing qt4/src/corelib/tools/qlocale_icu.cpp
Generated on 2014-Aug-03 from project include
Powered by 
Code Browser 1.7