OLD | NEW |
1 /* | 1 /* |
2 ******************************************************************************* | 2 ******************************************************************************* |
3 * Copyright (c) 1996-2013, International Business Machines Corporation and other
s. | 3 * Copyright (c) 1996-2014, International Business Machines Corporation and other
s. |
4 * All Rights Reserved. | 4 * All Rights Reserved. |
5 ******************************************************************************* | 5 ******************************************************************************* |
6 */ | 6 */ |
7 | 7 |
8 #ifndef UCOL_H | 8 #ifndef UCOL_H |
9 #define UCOL_H | 9 #define UCOL_H |
10 | 10 |
11 #include "unicode/utypes.h" | 11 #include "unicode/utypes.h" |
12 | 12 |
13 #if !UCONFIG_NO_COLLATION | 13 #if !UCONFIG_NO_COLLATION |
14 | 14 |
15 #include "unicode/unorm.h" | 15 #include "unicode/unorm.h" |
16 #include "unicode/localpointer.h" | 16 #include "unicode/localpointer.h" |
17 #include "unicode/parseerr.h" | 17 #include "unicode/parseerr.h" |
18 #include "unicode/uloc.h" | 18 #include "unicode/uloc.h" |
19 #include "unicode/uset.h" | 19 #include "unicode/uset.h" |
20 #include "unicode/uscript.h" | 20 #include "unicode/uscript.h" |
21 | 21 |
22 /** | 22 /** |
23 * \file | 23 * \file |
24 * \brief C API: Collator | 24 * \brief C API: Collator |
25 * | 25 * |
26 * <h2> Collator C API </h2> | 26 * <h2> Collator C API </h2> |
27 * | 27 * |
28 * The C API for Collator performs locale-sensitive | 28 * The C API for Collator performs locale-sensitive |
29 * string comparison. You use this service to build | 29 * string comparison. You use this service to build |
30 * searching and sorting routines for natural language text. | 30 * searching and sorting routines for natural language text. |
31 * <em>Important: </em>The ICU collation service has been reimplemented | |
32 * in order to achieve better performance and UCA compliance. | |
33 * For details, see the | |
34 * <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/collati
on/ICU_collation_design.htm"> | |
35 * collation design document</a>. | |
36 * <p> | 31 * <p> |
37 * For more information about the collation service see | 32 * For more information about the collation service see |
38 * <a href="http://icu-project.org/userguide/Collate_Intro.html">the users guide
</a>. | 33 * <a href="http://userguide.icu-project.org/collation">the User Guide</a>. |
39 * <p> | 34 * <p> |
40 * Collation service provides correct sorting orders for most locales supported
in ICU. | 35 * Collation service provides correct sorting orders for most locales supported
in ICU. |
41 * If specific data for a locale is not available, the orders eventually falls b
ack | 36 * If specific data for a locale is not available, the orders eventually falls b
ack |
42 * to the <a href="http://www.unicode.org/unicode/reports/tr10/">UCA sort order<
/a>. | 37 * to the <a href="http://www.unicode.org/reports/tr35/tr35-collation.html#Root_
Collation">CLDR root sort order</a>. |
43 * <p> | 38 * <p> |
44 * Sort ordering may be customized by providing your own set of rules. For more
on | 39 * Sort ordering may be customized by providing your own set of rules. For more
on |
45 * this subject see the | 40 * this subject see the <a href="http://userguide.icu-project.org/collation/cust
omization"> |
46 * <a href="http://icu-project.org/userguide/Collate_Customization.html"> | 41 * Collation Customization</a> section of the User Guide. |
47 * Collation customization</a> section of the users guide. | |
48 * <p> | 42 * <p> |
49 * @see UCollationResult | 43 * @see UCollationResult |
50 * @see UNormalizationMode | 44 * @see UNormalizationMode |
51 * @see UCollationStrength | 45 * @see UCollationStrength |
52 * @see UCollationElements | 46 * @see UCollationElements |
53 */ | 47 */ |
54 | 48 |
55 /** A collator. | 49 /** A collator. |
56 * For usage in C programs. | 50 * For usage in C programs. |
57 */ | 51 */ |
(...skipping 226 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
284 * incremental NFD normalization is performed. | 278 * incremental NFD normalization is performed. |
285 * @stable ICU 2.0 | 279 * @stable ICU 2.0 |
286 */ | 280 */ |
287 UCOL_NORMALIZATION_MODE, | 281 UCOL_NORMALIZATION_MODE, |
288 /** An alias for UCOL_NORMALIZATION_MODE attribute. | 282 /** An alias for UCOL_NORMALIZATION_MODE attribute. |
289 * @stable ICU 2.0 | 283 * @stable ICU 2.0 |
290 */ | 284 */ |
291 UCOL_DECOMPOSITION_MODE = UCOL_NORMALIZATION_MODE, | 285 UCOL_DECOMPOSITION_MODE = UCOL_NORMALIZATION_MODE, |
292 /** The strength attribute. Can be either UCOL_PRIMARY, UCOL_SECONDARY, | 286 /** The strength attribute. Can be either UCOL_PRIMARY, UCOL_SECONDARY, |
293 * UCOL_TERTIARY, UCOL_QUATERNARY or UCOL_IDENTICAL. The usual strength | 287 * UCOL_TERTIARY, UCOL_QUATERNARY or UCOL_IDENTICAL. The usual strength |
294 * for most locales (except Japanese) is tertiary. Quaternary strength | 288 * for most locales (except Japanese) is tertiary. |
| 289 * |
| 290 * Quaternary strength |
295 * is useful when combined with shifted setting for alternate handling | 291 * is useful when combined with shifted setting for alternate handling |
296 * attribute and for JIS x 4061 collation, when it is used to distinguish | 292 * attribute and for JIS X 4061 collation, when it is used to distinguish |
297 * between Katakana and Hiragana (this is achieved by setting the | 293 * between Katakana and Hiragana. |
298 * UCOL_HIRAGANA_QUATERNARY mode to on. Otherwise, quaternary level | 294 * Otherwise, quaternary level |
299 * is affected only by the number of non ignorable code points in | 295 * is affected only by the number of non-ignorable code points in |
300 * the string. Identical strength is rarely useful, as it amounts | 296 * the string. |
| 297 * |
| 298 * Identical strength is rarely useful, as it amounts |
301 * to codepoints of the NFD form of the string. | 299 * to codepoints of the NFD form of the string. |
302 * @stable ICU 2.0 | 300 * @stable ICU 2.0 |
303 */ | 301 */ |
304 UCOL_STRENGTH, | 302 UCOL_STRENGTH, |
305 #ifndef U_HIDE_DEPRECATED_API | 303 #ifndef U_HIDE_DEPRECATED_API |
306 /** When turned on, this attribute positions Hiragana before all | 304 /** When turned on, this attribute positions Hiragana before all |
307 * non-ignorables on quaternary level This is a sneaky way to produce JIS | 305 * non-ignorables on quaternary level This is a sneaky way to produce JIS |
308 * sort order. | 306 * sort order. |
309 * | 307 * |
310 * This attribute is an implementation detail of the CLDR Japanese tailorin
g. | 308 * This attribute was an implementation detail of the CLDR Japanese tailori
ng. |
311 * The implementation might change to use a different mechanism | 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 |
312 * to achieve the same Japanese sort order. | 311 * to achieve the same Japanese sort order. |
313 * Since ICU 50, this attribute is not settable any more via API functions. | 312 * |
314 * @deprecated ICU 50 Implementation detail, cannot be set via API, might b
e removed from implementation. | 313 * @deprecated ICU 50 Implementation detail, cannot be set via API, was rem
oved from implementation. |
315 */ | 314 */ |
316 UCOL_HIRAGANA_QUATERNARY_MODE = UCOL_STRENGTH + 1, | 315 UCOL_HIRAGANA_QUATERNARY_MODE = UCOL_STRENGTH + 1, |
317 #endif /* U_HIDE_DEPRECATED_API */ | 316 #endif /* U_HIDE_DEPRECATED_API */ |
318 /** When turned on, this attribute generates a collation key | 317 /** |
319 * for the numeric value of substrings of digits. | 318 * When turned on, this attribute makes |
| 319 * substrings of digits sort according to their numeric values. |
| 320 * |
320 * This is a way to get '100' to sort AFTER '2'. Note that the longest | 321 * This is a way to get '100' to sort AFTER '2'. Note that the longest |
321 * digit substring that can be treated as a single collation element is | 322 * digit substring that can be treated as a single unit is |
322 * 254 digits (not counting leading zeros). If a digit substring is | 323 * 254 digits (not counting leading zeros). If a digit substring is |
323 * longer than that, the digits beyond the limit will be treated as a | 324 * longer than that, the digits beyond the limit will be treated as a |
324 * separate digit substring associated with a separate collation element. | 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 * |
325 * @stable ICU 2.8 | 333 * @stable ICU 2.8 |
326 */ | 334 */ |
327 UCOL_NUMERIC_COLLATION = UCOL_STRENGTH + 2, | 335 UCOL_NUMERIC_COLLATION = UCOL_STRENGTH + 2, |
328 /** | 336 /** |
329 * The number of UColAttribute constants. | 337 * The number of UColAttribute constants. |
330 * @stable ICU 2.0 | 338 * @stable ICU 2.0 |
331 */ | 339 */ |
332 UCOL_ATTRIBUTE_COUNT | 340 UCOL_ATTRIBUTE_COUNT |
333 } UColAttribute; | 341 } UColAttribute; |
334 | 342 |
(...skipping 12 matching lines...) Expand all Loading... |
347 * The "UCA rules" are an <i>approximation</i> of the root collator's sort ord
er. | 355 * The "UCA rules" are an <i>approximation</i> of the root collator's sort ord
er. |
348 * They are almost never used or useful at runtime and can be removed from the
data. | 356 * They are almost never used or useful at runtime and can be removed from the
data. |
349 * See http://userguide.icu-project.org/collation/customization#TOC-Building-o
n-Existing-Locales | 357 * See http://userguide.icu-project.org/collation/customization#TOC-Building-o
n-Existing-Locales |
350 * @stable ICU 2.0 | 358 * @stable ICU 2.0 |
351 */ | 359 */ |
352 UCOL_FULL_RULES | 360 UCOL_FULL_RULES |
353 } UColRuleOption ; | 361 } UColRuleOption ; |
354 | 362 |
355 /** | 363 /** |
356 * Open a UCollator for comparing strings. | 364 * Open a UCollator for comparing strings. |
| 365 * |
| 366 * For some languages, multiple collation types are available; |
| 367 * for example, "de@collation=phonebook". |
| 368 * Starting with ICU 54, collation attributes can be specified via locale keywor
ds as well, |
| 369 * in the old locale extension syntax ("el@colCaseFirst=upper") |
| 370 * or in language tag syntax ("el-u-kf-upper"). |
| 371 * See <a href="http://userguide.icu-project.org/collation/api">User Guide: Coll
ation API</a>. |
| 372 * |
357 * The UCollator pointer is used in all the calls to the Collation | 373 * The UCollator pointer is used in all the calls to the Collation |
358 * service. After finished, collator must be disposed of by calling | 374 * service. After finished, collator must be disposed of by calling |
359 * {@link #ucol_close }. | 375 * {@link #ucol_close }. |
360 * @param loc The locale containing the required collation rules. | 376 * @param loc The locale containing the required collation rules. |
361 * Special values for locales can be passed in - | 377 * Special values for locales can be passed in - |
362 * if NULL is passed for the locale, the default locale | 378 * if NULL is passed for the locale, the default locale |
363 * collation rules will be used. If empty string ("") or | 379 * collation rules will be used. If empty string ("") or |
364 * "root" are passed, UCA rules will be used. | 380 * "root" are passed, the root collator will be returned. |
365 * @param status A pointer to an UErrorCode to receive any errors | 381 * @param status A pointer to a UErrorCode to receive any errors |
366 * @return A pointer to a UCollator, or 0 if an error occurred. | 382 * @return A pointer to a UCollator, or 0 if an error occurred. |
367 * @see ucol_openRules | 383 * @see ucol_openRules |
368 * @see ucol_safeClone | 384 * @see ucol_safeClone |
369 * @see ucol_close | 385 * @see ucol_close |
370 * @stable ICU 2.0 | 386 * @stable ICU 2.0 |
371 */ | 387 */ |
372 U_STABLE UCollator* U_EXPORT2 | 388 U_STABLE UCollator* U_EXPORT2 |
373 ucol_open(const char *loc, UErrorCode *status); | 389 ucol_open(const char *loc, UErrorCode *status); |
374 | 390 |
375 /** | 391 /** |
376 * Produce an UCollator instance according to the rules supplied. | 392 * Produce a UCollator instance according to the rules supplied. |
377 * The rules are used to change the default ordering, defined in the | 393 * The rules are used to change the default ordering, defined in the |
378 * UCA in a process called tailoring. The resulting UCollator pointer | 394 * UCA in a process called tailoring. The resulting UCollator pointer |
379 * can be used in the same way as the one obtained by {@link #ucol_strcoll }. | 395 * can be used in the same way as the one obtained by {@link #ucol_strcoll }. |
380 * @param rules A string describing the collation rules. For the syntax | 396 * @param rules A string describing the collation rules. For the syntax |
381 * of the rules please see users guide. | 397 * of the rules please see users guide. |
382 * @param rulesLength The length of rules, or -1 if null-terminated. | 398 * @param rulesLength The length of rules, or -1 if null-terminated. |
383 * @param normalizationMode The normalization mode: One of | 399 * @param normalizationMode The normalization mode: One of |
384 * UCOL_OFF (expect the text to not need normalization), | 400 * UCOL_OFF (expect the text to not need normalization), |
385 * UCOL_ON (normalize), or | 401 * UCOL_ON (normalize), or |
386 * UCOL_DEFAULT (set the mode according to the rules) | 402 * UCOL_DEFAULT (set the mode according to the rules) |
387 * @param strength The default collation strength; one of UCOL_PRIMARY, UCOL_SEC
ONDARY, | 403 * @param strength The default collation strength; one of UCOL_PRIMARY, UCOL_SEC
ONDARY, |
388 * UCOL_TERTIARY, UCOL_IDENTICAL,UCOL_DEFAULT_STRENGTH - can be also set in the
rules. | 404 * UCOL_TERTIARY, UCOL_IDENTICAL,UCOL_DEFAULT_STRENGTH - can be also set in the
rules. |
389 * @param parseError A pointer to UParseError to recieve information about erro
rs | 405 * @param parseError A pointer to UParseError to recieve information about erro
rs |
390 * occurred during parsing. This argument can currently be se
t | 406 * occurred during parsing. This argument can currently be se
t |
391 * to NULL, but at users own risk. Please provide a real stru
cture. | 407 * to NULL, but at users own risk. Please provide a real stru
cture. |
392 * @param status A pointer to an UErrorCode to receive any errors | 408 * @param status A pointer to a UErrorCode to receive any errors |
393 * @return A pointer to a UCollator. It is not guaranteed that NULL be returned
in case | 409 * @return A pointer to a UCollator. It is not guaranteed that NULL be returned
in case |
394 * of error - please use status argument to check for errors. | 410 * of error - please use status argument to check for errors. |
395 * @see ucol_open | 411 * @see ucol_open |
396 * @see ucol_safeClone | 412 * @see ucol_safeClone |
397 * @see ucol_close | 413 * @see ucol_close |
398 * @stable ICU 2.0 | 414 * @stable ICU 2.0 |
399 */ | 415 */ |
400 U_STABLE UCollator* U_EXPORT2 | 416 U_STABLE UCollator* U_EXPORT2 |
401 ucol_openRules( const UChar *rules, | 417 ucol_openRules( const UChar *rules, |
402 int32_t rulesLength, | 418 int32_t rulesLength, |
403 UColAttributeValue normalizationMode, | 419 UColAttributeValue normalizationMode, |
404 UCollationStrength strength, | 420 UCollationStrength strength, |
405 UParseError *parseError, | 421 UParseError *parseError, |
406 UErrorCode *status); | 422 UErrorCode *status); |
407 | 423 |
| 424 #ifndef U_HIDE_DEPRECATED_API |
408 /** | 425 /** |
409 * Open a collator defined by a short form string. | 426 * Open a collator defined by a short form string. |
410 * The structure and the syntax of the string is defined in the "Naming collator
s" | 427 * The structure and the syntax of the string is defined in the "Naming collator
s" |
411 * section of the users guide: | 428 * section of the users guide: |
412 * http://icu-project.org/userguide/Collate_Concepts.html#Naming_Collators | 429 * http://userguide.icu-project.org/collation/concepts#TOC-Collator-naming-schem
e |
413 * Attributes are overriden by the subsequent attributes. So, for "S2_S3", final | 430 * Attributes are overriden by the subsequent attributes. So, for "S2_S3", final |
414 * strength will be 3. 3066bis locale overrides individual locale parts. | 431 * strength will be 3. 3066bis locale overrides individual locale parts. |
415 * The call to this function is equivalent to a call to ucol_open, followed by a
| 432 * The call to this function is equivalent to a call to ucol_open, followed by a
|
416 * series of calls to ucol_setAttribute and ucol_setVariableTop. | 433 * series of calls to ucol_setAttribute and ucol_setVariableTop. |
417 * @param definition A short string containing a locale and a set of attributes.
| 434 * @param definition A short string containing a locale and a set of attributes.
|
418 * Attributes not explicitly mentioned are left at the default | 435 * Attributes not explicitly mentioned are left at the default |
419 * state for a locale. | 436 * state for a locale. |
420 * @param parseError if not NULL, structure that will get filled with error's pr
e | 437 * @param parseError if not NULL, structure that will get filled with error's pr
e |
421 * and post context in case of error. | 438 * and post context in case of error. |
422 * @param forceDefaults if FALSE, the settings that are the same as the collator
| 439 * @param forceDefaults if FALSE, the settings that are the same as the collator
|
423 * default settings will not be applied (for example, setting | 440 * default settings will not be applied (for example, setting |
424 * French secondary on a French collator would not be executed
). | 441 * French secondary on a French collator would not be executed
). |
425 * If TRUE, all the settings will be applied regardless of the
| 442 * If TRUE, all the settings will be applied regardless of the
|
426 * collator default value. If the definition | 443 * collator default value. If the definition |
427 * strings are to be cached, should be set to FALSE. | 444 * strings are to be cached, should be set to FALSE. |
428 * @param status Error code. Apart from regular error conditions connected t
o | 445 * @param status Error code. Apart from regular error conditions connected t
o |
429 * instantiating collators (like out of memory or similar), th
is | 446 * instantiating collators (like out of memory or similar), th
is |
430 * API will return an error if an invalid attribute or attribu
te/value | 447 * API will return an error if an invalid attribute or attribu
te/value |
431 * combination is specified. | 448 * combination is specified. |
432 * @return A pointer to a UCollator or 0 if an error occured (includin
g an | 449 * @return A pointer to a UCollator or 0 if an error occured (includin
g an |
433 * invalid attribute). | 450 * invalid attribute). |
434 * @see ucol_open | 451 * @see ucol_open |
435 * @see ucol_setAttribute | 452 * @see ucol_setAttribute |
436 * @see ucol_setVariableTop | 453 * @see ucol_setVariableTop |
437 * @see ucol_getShortDefinitionString | 454 * @see ucol_getShortDefinitionString |
438 * @see ucol_normalizeShortDefinitionString | 455 * @see ucol_normalizeShortDefinitionString |
439 * @stable ICU 3.0 | 456 * @deprecated ICU 54 Use ucol_open() with language tag collation keywords inste
ad. |
440 * | |
441 */ | 457 */ |
442 U_STABLE UCollator* U_EXPORT2 | 458 U_DEPRECATED UCollator* U_EXPORT2 |
443 ucol_openFromShortString( const char *definition, | 459 ucol_openFromShortString( const char *definition, |
444 UBool forceDefaults, | 460 UBool forceDefaults, |
445 UParseError *parseError, | 461 UParseError *parseError, |
446 UErrorCode *status); | 462 UErrorCode *status); |
| 463 #endif /* U_HIDE_DEPRECATED_API */ |
447 | 464 |
448 #ifndef U_HIDE_DEPRECATED_API | 465 #ifndef U_HIDE_DEPRECATED_API |
449 /** | 466 /** |
450 * Get a set containing the contractions defined by the collator. The set includ
es | 467 * Get a set containing the contractions defined by the collator. The set includ
es |
451 * both the UCA contractions and the contractions defined by the collator. This
set | 468 * both the root collator's contractions and the contractions defined by the col
lator. This set |
452 * will contain only strings. If a tailoring explicitly suppresses contractions
from | 469 * will contain only strings. If a tailoring explicitly suppresses contractions
from |
453 * the UCA (like Russian), removed contractions will not be in the resulting set
. | 470 * the root collator (like Russian), removed contractions will not be in the res
ulting set. |
454 * @param coll collator | 471 * @param coll collator |
455 * @param conts the set to hold the result. It gets emptied before | 472 * @param conts the set to hold the result. It gets emptied before |
456 * contractions are added. | 473 * contractions are added. |
457 * @param status to hold the error code | 474 * @param status to hold the error code |
458 * @return the size of the contraction set | 475 * @return the size of the contraction set |
459 * | 476 * |
460 * @deprecated ICU 3.4, use ucol_getContractionsAndExpansions instead | 477 * @deprecated ICU 3.4, use ucol_getContractionsAndExpansions instead |
461 */ | 478 */ |
462 U_DEPRECATED int32_t U_EXPORT2 | 479 U_DEPRECATED int32_t U_EXPORT2 |
463 ucol_getContractions( const UCollator *coll, | 480 ucol_getContractions( const UCollator *coll, |
464 USet *conts, | 481 USet *conts, |
465 UErrorCode *status); | 482 UErrorCode *status); |
466 #endif /* U_HIDE_DEPRECATED_API */ | 483 #endif /* U_HIDE_DEPRECATED_API */ |
467 | 484 |
468 /** | 485 /** |
469 * Get a set containing the expansions defined by the collator. The set includes | 486 * Get a set containing the expansions defined by the collator. The set includes |
470 * both the UCA expansions and the expansions defined by the tailoring | 487 * both the root collator's expansions and the expansions defined by the tailori
ng |
471 * @param coll collator | 488 * @param coll collator |
472 * @param contractions if not NULL, the set to hold the contractions | 489 * @param contractions if not NULL, the set to hold the contractions |
473 * @param expansions if not NULL, the set to hold the expansions | 490 * @param expansions if not NULL, the set to hold the expansions |
474 * @param addPrefixes add the prefix contextual elements to contractions | 491 * @param addPrefixes add the prefix contextual elements to contractions |
475 * @param status to hold the error code | 492 * @param status to hold the error code |
476 * | 493 * |
477 * @stable ICU 3.4 | 494 * @stable ICU 3.4 |
478 */ | 495 */ |
479 U_STABLE void U_EXPORT2 | 496 U_STABLE void U_EXPORT2 |
480 ucol_getContractionsAndExpansions( const UCollator *coll, | 497 ucol_getContractionsAndExpansions( const UCollator *coll, |
(...skipping 57 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
538 /** | 555 /** |
539 * Compare two strings in UTF-8. | 556 * Compare two strings in UTF-8. |
540 * The strings will be compared using the options already specified. | 557 * The strings will be compared using the options already specified. |
541 * Note: When input string contains malformed a UTF-8 byte sequence, | 558 * Note: When input string contains malformed a UTF-8 byte sequence, |
542 * this function treats these bytes as REPLACEMENT CHARACTER (U+FFFD). | 559 * this function treats these bytes as REPLACEMENT CHARACTER (U+FFFD). |
543 * @param coll The UCollator containing the comparison rules. | 560 * @param coll The UCollator containing the comparison rules. |
544 * @param source The source UTF-8 string. | 561 * @param source The source UTF-8 string. |
545 * @param sourceLength The length of source, or -1 if null-terminated. | 562 * @param sourceLength The length of source, or -1 if null-terminated. |
546 * @param target The target UTF-8 string. | 563 * @param target The target UTF-8 string. |
547 * @param targetLength The length of target, or -1 if null-terminated. | 564 * @param targetLength The length of target, or -1 if null-terminated. |
548 * @param status A pointer to an UErrorCode to receive any errors | 565 * @param status A pointer to a UErrorCode to receive any errors |
549 * @return The result of comparing the strings; one of UCOL_EQUAL, | 566 * @return The result of comparing the strings; one of UCOL_EQUAL, |
550 * UCOL_GREATER, UCOL_LESS | 567 * UCOL_GREATER, UCOL_LESS |
551 * @see ucol_greater | 568 * @see ucol_greater |
552 * @see ucol_greaterOrEqual | 569 * @see ucol_greaterOrEqual |
553 * @see ucol_equal | 570 * @see ucol_equal |
554 * @stable ICU 50 | 571 * @stable ICU 50 |
555 */ | 572 */ |
556 U_STABLE UCollationResult U_EXPORT2 | 573 U_STABLE UCollationResult U_EXPORT2 |
557 ucol_strcollUTF8( | 574 ucol_strcollUTF8( |
558 const UCollator *coll, | 575 const UCollator *coll, |
(...skipping 61 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
620 const UChar *target, int32_t targetLength); | 637 const UChar *target, int32_t targetLength); |
621 | 638 |
622 /** | 639 /** |
623 * Compare two UTF-8 encoded trings. | 640 * Compare two UTF-8 encoded trings. |
624 * The strings will be compared using the options already specified. | 641 * The strings will be compared using the options already specified. |
625 * @param coll The UCollator containing the comparison rules. | 642 * @param coll The UCollator containing the comparison rules. |
626 * @param sIter The source string iterator. | 643 * @param sIter The source string iterator. |
627 * @param tIter The target string iterator. | 644 * @param tIter The target string iterator. |
628 * @return The result of comparing the strings; one of UCOL_EQUAL, | 645 * @return The result of comparing the strings; one of UCOL_EQUAL, |
629 * UCOL_GREATER, UCOL_LESS | 646 * UCOL_GREATER, UCOL_LESS |
630 * @param status A pointer to an UErrorCode to receive any errors | 647 * @param status A pointer to a UErrorCode to receive any errors |
631 * @see ucol_strcoll | 648 * @see ucol_strcoll |
632 * @stable ICU 2.6 | 649 * @stable ICU 2.6 |
633 */ | 650 */ |
634 U_STABLE UCollationResult U_EXPORT2 | 651 U_STABLE UCollationResult U_EXPORT2 |
635 ucol_strcollIter( const UCollator *coll, | 652 ucol_strcollIter( const UCollator *coll, |
636 UCharIterator *sIter, | 653 UCharIterator *sIter, |
637 UCharIterator *tIter, | 654 UCharIterator *tIter, |
638 UErrorCode *status); | 655 UErrorCode *status); |
639 | 656 |
640 /** | 657 /** |
(...skipping 54 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
695 * are space, punctuation, symbol, currency, and digit. These special groups are
represented with | 712 * are space, punctuation, symbol, currency, and digit. These special groups are
represented with |
696 * UColReorderCode entries. Script groups can be intermingled with | 713 * UColReorderCode entries. Script groups can be intermingled with |
697 * these special non-script blocks if those special blocks are explicitly specif
ied in the reordering. | 714 * these special non-script blocks if those special blocks are explicitly specif
ied in the reordering. |
698 * <p>The special code OTHERS stands for any script that is not explicitly | 715 * <p>The special code OTHERS stands for any script that is not explicitly |
699 * mentioned in the list of reordering codes given. Anything that is after OTHER
S | 716 * mentioned in the list of reordering codes given. Anything that is after OTHER
S |
700 * will go at the very end of the reordering in the order given. | 717 * will go at the very end of the reordering in the order given. |
701 * <p>The special reorder code DEFAULT will reset the reordering for this collat
or | 718 * <p>The special reorder code DEFAULT will reset the reordering for this collat
or |
702 * to the default for this collator. The default reordering may be the DUCET/CLD
R order or may be a reordering that | 719 * to the default for this collator. The default reordering may be the DUCET/CLD
R order or may be a reordering that |
703 * was specified when this collator was created from resource data or from rules
. The | 720 * was specified when this collator was created from resource data or from rules
. The |
704 * DEFAULT code <b>must</b> be the sole code supplied when it used. If not | 721 * DEFAULT code <b>must</b> be the sole code supplied when it used. If not |
705 * that will result in an U_ILLEGAL_ARGUMENT_ERROR being set. | 722 * that will result in a U_ILLEGAL_ARGUMENT_ERROR being set. |
706 * <p>The special reorder code NONE will remove any reordering for this collator
. | 723 * <p>The special reorder code NONE will remove any reordering for this collator
. |
707 * The result of setting no reordering will be to have the DUCET/CLDR ordering u
sed. The | 724 * The result of setting no reordering will be to have the DUCET/CLDR ordering u
sed. The |
708 * NONE code <b>must</b> be the sole code supplied when it used. | 725 * NONE code <b>must</b> be the sole code supplied when it used. |
709 * @param coll The UCollator to set. | 726 * @param coll The UCollator to set. |
710 * @param reorderCodes An array of script codes in the new order. This can be NU
LL if the | 727 * @param reorderCodes An array of script codes in the new order. This can be NU
LL if the |
711 * length is also set to 0. An empty array will clear any reordering codes on th
e collator. | 728 * length is also set to 0. An empty array will clear any reordering codes on th
e collator. |
712 * @param reorderCodesLength The length of reorderCodes. | 729 * @param reorderCodesLength The length of reorderCodes. |
713 * @param pErrorCode Must be a valid pointer to an error code value, which must
not indicate a | 730 * @param pErrorCode Must be a valid pointer to an error code value, which must
not indicate a |
714 * failure before the function call. | 731 * failure before the function call. |
715 * @see ucol_getReorderCodes | 732 * @see ucol_getReorderCodes |
(...skipping 30 matching lines...) Expand all Loading... |
746 int32_t destCapacity, | 763 int32_t destCapacity, |
747 UErrorCode *pErrorCode); | 764 UErrorCode *pErrorCode); |
748 | 765 |
749 /** | 766 /** |
750 * Get the display name for a UCollator. | 767 * Get the display name for a UCollator. |
751 * The display name is suitable for presentation to a user. | 768 * The display name is suitable for presentation to a user. |
752 * @param objLoc The locale of the collator in question. | 769 * @param objLoc The locale of the collator in question. |
753 * @param dispLoc The locale for display. | 770 * @param dispLoc The locale for display. |
754 * @param result A pointer to a buffer to receive the attribute. | 771 * @param result A pointer to a buffer to receive the attribute. |
755 * @param resultLength The maximum size of result. | 772 * @param resultLength The maximum size of result. |
756 * @param status A pointer to an UErrorCode to receive any errors | 773 * @param status A pointer to a UErrorCode to receive any errors |
757 * @return The total buffer size needed; if greater than resultLength, | 774 * @return The total buffer size needed; if greater than resultLength, |
758 * the output was truncated. | 775 * the output was truncated. |
759 * @stable ICU 2.0 | 776 * @stable ICU 2.0 |
760 */ | 777 */ |
761 U_STABLE int32_t U_EXPORT2 | 778 U_STABLE int32_t U_EXPORT2 |
762 ucol_getDisplayName( const char *objLoc, | 779 ucol_getDisplayName( const char *objLoc, |
763 const char *dispLoc, | 780 const char *dispLoc, |
764 UChar *result, | 781 UChar *result, |
765 int32_t resultLength, | 782 int32_t resultLength, |
766 UErrorCode *status); | 783 UErrorCode *status); |
(...skipping 76 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
843 * @return a string enumeration over keyword values for the given key and the lo
cale. | 860 * @return a string enumeration over keyword values for the given key and the lo
cale. |
844 * @stable ICU 4.2 | 861 * @stable ICU 4.2 |
845 */ | 862 */ |
846 U_STABLE UEnumeration* U_EXPORT2 | 863 U_STABLE UEnumeration* U_EXPORT2 |
847 ucol_getKeywordValuesForLocale(const char* key, | 864 ucol_getKeywordValuesForLocale(const char* key, |
848 const char* locale, | 865 const char* locale, |
849 UBool commonlyUsed, | 866 UBool commonlyUsed, |
850 UErrorCode* status); | 867 UErrorCode* status); |
851 | 868 |
852 /** | 869 /** |
853 * Return the functionally equivalent locale for the given | 870 * Return the functionally equivalent locale for the specified |
854 * requested locale, with respect to given keyword, for the | 871 * input locale, with respect to given keyword, for the |
855 * collation service. If two locales return the same result, then | 872 * collation service. If two different input locale + keyword |
856 * collators instantiated for these locales will behave | 873 * combinations produce the same result locale, then collators |
857 * equivalently. The converse is not always true; two collators | 874 * instantiated for these two different input locales will behave |
| 875 * equivalently. The converse is not always true; two collators |
858 * may in fact be equivalent, but return different results, due to | 876 * may in fact be equivalent, but return different results, due to |
859 * internal details. The return result has no other meaning than | 877 * internal details. The return result has no other meaning than |
860 * that stated above, and implies nothing as to the relationship | 878 * that stated above, and implies nothing as to the relationship |
861 * between the two locales. This is intended for use by | 879 * between the two locales. This is intended for use by |
862 * applications who wish to cache collators, or otherwise reuse | 880 * applications who wish to cache collators, or otherwise reuse |
863 * collators when possible. The functional equivalent may change | 881 * collators when possible. The functional equivalent may change |
864 * over time. For more information, please see the <a | 882 * over time. For more information, please see the <a |
865 * href="http://icu-project.org/userguide/locale.html#services"> | 883 * href="http://userguide.icu-project.org/locale#TOC-Locales-and-Services"> |
866 * Locales and Services</a> section of the ICU User Guide. | 884 * Locales and Services</a> section of the ICU User Guide. |
867 * @param result fillin for the functionally equivalent locale | 885 * @param result fillin for the functionally equivalent result locale |
868 * @param resultCapacity capacity of the fillin buffer | 886 * @param resultCapacity capacity of the fillin buffer |
869 * @param keyword a particular keyword as enumerated by | 887 * @param keyword a particular keyword as enumerated by |
870 * ucol_getKeywords. | 888 * ucol_getKeywords. |
871 * @param locale the requested locale | 889 * @param locale the specified input locale |
872 * @param isAvailable if non-NULL, pointer to a fillin parameter that | 890 * @param isAvailable if non-NULL, pointer to a fillin parameter that |
873 * indicates whether the requested locale was 'available' to the | 891 * on return indicates whether the specified input locale was 'available' |
874 * collation service. A locale is defined as 'available' if it | 892 * to the collation service. A locale is defined as 'available' if it |
875 * physically exists within the collation locale data. | 893 * physically exists within the collation locale data. |
876 * @param status pointer to input-output error code | 894 * @param status pointer to input-output error code |
877 * @return the actual buffer size needed for the locale. If greater | 895 * @return the actual buffer size needed for the locale. If greater |
878 * than resultCapacity, the returned full name will be truncated and | 896 * than resultCapacity, the returned full name will be truncated and |
879 * an error code will be returned. | 897 * an error code will be returned. |
880 * @stable ICU 3.0 | 898 * @stable ICU 3.0 |
881 */ | 899 */ |
882 U_STABLE int32_t U_EXPORT2 | 900 U_STABLE int32_t U_EXPORT2 |
883 ucol_getFunctionalEquivalent(char* result, int32_t resultCapacity, | 901 ucol_getFunctionalEquivalent(char* result, int32_t resultCapacity, |
884 const char* keyword, const char* locale, | 902 const char* keyword, const char* locale, |
885 UBool* isAvailable, UErrorCode* status); | 903 UBool* isAvailable, UErrorCode* status); |
886 | 904 |
887 /** | 905 /** |
888 * Get the collation tailoring rules from a UCollator. | 906 * Get the collation tailoring rules from a UCollator. |
889 * The rules will follow the rule syntax. | 907 * The rules will follow the rule syntax. |
890 * @param coll The UCollator to query. | 908 * @param coll The UCollator to query. |
891 * @param length | 909 * @param length |
892 * @return The collation tailoring rules. | 910 * @return The collation tailoring rules. |
893 * @stable ICU 2.0 | 911 * @stable ICU 2.0 |
894 */ | 912 */ |
895 U_STABLE const UChar* U_EXPORT2 | 913 U_STABLE const UChar* U_EXPORT2 |
896 ucol_getRules( const UCollator *coll, | 914 ucol_getRules( const UCollator *coll, |
897 int32_t *length); | 915 int32_t *length); |
898 | 916 |
| 917 #ifndef U_HIDE_DEPRECATED_API |
899 /** Get the short definition string for a collator. This API harvests the collat
or's | 918 /** Get the short definition string for a collator. This API harvests the collat
or's |
900 * locale and the attribute set and produces a string that can be used for open
ing | 919 * locale and the attribute set and produces a string that can be used for open
ing |
901 * a collator with the same properties using the ucol_openFromShortString API. | 920 * a collator with the same attributes using the ucol_openFromShortString API. |
902 * This string will be normalized. | 921 * This string will be normalized. |
903 * The structure and the syntax of the string is defined in the "Naming collato
rs" | 922 * The structure and the syntax of the string is defined in the "Naming collato
rs" |
904 * section of the users guide: | 923 * section of the users guide: |
905 * http://icu-project.org/userguide/Collate_Concepts.html#Naming_Collators | 924 * http://userguide.icu-project.org/collation/concepts#TOC-Collator-naming-sche
me |
906 * This API supports preflighting. | 925 * This API supports preflighting. |
907 * @param coll a collator | 926 * @param coll a collator |
908 * @param locale a locale that will appear as a collators locale in the resulti
ng | 927 * @param locale a locale that will appear as a collators locale in the resulti
ng |
909 * short string definition. If NULL, the locale will be harvested
| 928 * short string definition. If NULL, the locale will be harvested
|
910 * from the collator. | 929 * from the collator. |
911 * @param buffer space to hold the resulting string | 930 * @param buffer space to hold the resulting string |
912 * @param capacity capacity of the buffer | 931 * @param capacity capacity of the buffer |
913 * @param status for returning errors. All the preflighting errors are featured | 932 * @param status for returning errors. All the preflighting errors are featured |
914 * @return length of the resulting string | 933 * @return length of the resulting string |
915 * @see ucol_openFromShortString | 934 * @see ucol_openFromShortString |
916 * @see ucol_normalizeShortDefinitionString | 935 * @see ucol_normalizeShortDefinitionString |
917 * @stable ICU 3.0 | 936 * @deprecated ICU 54 |
918 */ | 937 */ |
919 U_STABLE int32_t U_EXPORT2 | 938 U_DEPRECATED int32_t U_EXPORT2 |
920 ucol_getShortDefinitionString(const UCollator *coll, | 939 ucol_getShortDefinitionString(const UCollator *coll, |
921 const char *locale, | 940 const char *locale, |
922 char *buffer, | 941 char *buffer, |
923 int32_t capacity, | 942 int32_t capacity, |
924 UErrorCode *status); | 943 UErrorCode *status); |
925 | 944 |
926 /** Verifies and normalizes short definition string. | 945 /** Verifies and normalizes short definition string. |
927 * Normalized short definition string has all the option sorted by the argument
name, | 946 * Normalized short definition string has all the option sorted by the argument
name, |
928 * so that equivalent definition strings are the same. | 947 * so that equivalent definition strings are the same. |
929 * This API supports preflighting. | 948 * This API supports preflighting. |
930 * @param source definition string | 949 * @param source definition string |
931 * @param destination space to hold the resulting string | 950 * @param destination space to hold the resulting string |
932 * @param capacity capacity of the buffer | 951 * @param capacity capacity of the buffer |
933 * @param parseError if not NULL, structure that will get filled with error's p
re | 952 * @param parseError if not NULL, structure that will get filled with error's p
re |
934 * and post context in case of error. | 953 * and post context in case of error. |
935 * @param status Error code. This API will return an error if an invalid at
tribute | 954 * @param status Error code. This API will return an error if an invalid at
tribute |
936 * or attribute/value combination is specified. All the prefl
ighting | 955 * or attribute/value combination is specified. All the prefl
ighting |
937 * errors are also featured | 956 * errors are also featured |
938 * @return length of the resulting normalized string. | 957 * @return length of the resulting normalized string. |
939 * | 958 * |
940 * @see ucol_openFromShortString | 959 * @see ucol_openFromShortString |
941 * @see ucol_getShortDefinitionString | 960 * @see ucol_getShortDefinitionString |
942 * | 961 * |
943 * @stable ICU 3.0 | 962 * @deprecated ICU 54 |
944 */ | 963 */ |
945 | 964 |
946 U_STABLE int32_t U_EXPORT2 | 965 U_DEPRECATED int32_t U_EXPORT2 |
947 ucol_normalizeShortDefinitionString(const char *source, | 966 ucol_normalizeShortDefinitionString(const char *source, |
948 char *destination, | 967 char *destination, |
949 int32_t capacity, | 968 int32_t capacity, |
950 UParseError *parseError, | 969 UParseError *parseError, |
951 UErrorCode *status); | 970 UErrorCode *status); |
| 971 #endif /* U_HIDE_DEPRECATED_API */ |
952 | 972 |
953 | 973 |
954 /** | 974 /** |
955 * Get a sort key for a string from a UCollator. | 975 * Get a sort key for a string from a UCollator. |
956 * Sort keys may be compared using <TT>strcmp</TT>. | 976 * Sort keys may be compared using <TT>strcmp</TT>. |
957 * | 977 * |
| 978 * Note that sort keys are often less efficient than simply doing comparison. |
| 979 * For more details, see the ICU User Guide. |
| 980 * |
958 * Like ICU functions that write to an output buffer, the buffer contents | 981 * Like ICU functions that write to an output buffer, the buffer contents |
959 * is undefined if the buffer capacity (resultLength parameter) is too small. | 982 * is undefined if the buffer capacity (resultLength parameter) is too small. |
960 * Unlike ICU functions that write a string to an output buffer, | 983 * Unlike ICU functions that write a string to an output buffer, |
961 * the terminating zero byte is counted in the sort key length. | 984 * the terminating zero byte is counted in the sort key length. |
962 * @param coll The UCollator containing the collation rules. | 985 * @param coll The UCollator containing the collation rules. |
963 * @param source The string to transform. | 986 * @param source The string to transform. |
964 * @param sourceLength The length of source, or -1 if null-terminated. | 987 * @param sourceLength The length of source, or -1 if null-terminated. |
965 * @param result A pointer to a buffer to receive the attribute. | 988 * @param result A pointer to a buffer to receive the attribute. |
966 * @param resultLength The maximum size of result. | 989 * @param resultLength The maximum size of result. |
967 * @return The size needed to fully store the sort key. | 990 * @return The size needed to fully store the sort key. |
(...skipping 121 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1089 U_STABLE void U_EXPORT2 | 1112 U_STABLE void U_EXPORT2 |
1090 ucol_getUCAVersion(const UCollator* coll, UVersionInfo info); | 1113 ucol_getUCAVersion(const UCollator* coll, UVersionInfo info); |
1091 | 1114 |
1092 /** | 1115 /** |
1093 * Merges two sort keys. The levels are merged with their corresponding counterp
arts | 1116 * Merges two sort keys. The levels are merged with their corresponding counterp
arts |
1094 * (primaries with primaries, secondaries with secondaries etc.). Between the va
lues | 1117 * (primaries with primaries, secondaries with secondaries etc.). Between the va
lues |
1095 * from the same level a separator is inserted. | 1118 * from the same level a separator is inserted. |
1096 * | 1119 * |
1097 * This is useful, for example, for combining sort keys from first and last name
s | 1120 * This is useful, for example, for combining sort keys from first and last name
s |
1098 * to sort such pairs. | 1121 * to sort such pairs. |
| 1122 * See http://www.unicode.org/reports/tr10/#Merging_Sort_Keys |
| 1123 * |
| 1124 * The recommended way to achieve "merged" sorting is by |
| 1125 * concatenating strings with U+FFFE between them. |
| 1126 * The concatenation has the same sort order as the merged sort keys, |
| 1127 * but merge(getSortKey(str1), getSortKey(str2)) may differ from getSortKey(str1
+ '\uFFFE' + str2). |
| 1128 * Using strings with U+FFFE may yield shorter sort keys. |
| 1129 * |
| 1130 * For details about Sort Key Features see |
| 1131 * http://userguide.icu-project.org/collation/api#TOC-Sort-Key-Features |
| 1132 * |
1099 * It is possible to merge multiple sort keys by consecutively merging | 1133 * It is possible to merge multiple sort keys by consecutively merging |
1100 * another one with the intermediate result. | 1134 * another one with the intermediate result. |
1101 * | 1135 * |
1102 * The length of the merge result is the sum of the lengths of the input sort ke
ys. | 1136 * The length of the merge result is the sum of the lengths of the input sort ke
ys. |
1103 * | 1137 * |
1104 * Example (uncompressed): | 1138 * Example (uncompressed): |
1105 * <pre>191B1D 01 050505 01 910505 00 | 1139 * <pre>191B1D 01 050505 01 910505 00 |
1106 * 1F2123 01 050505 01 910505 00</pre> | 1140 * 1F2123 01 050505 01 910505 00</pre> |
1107 * will be merged as | 1141 * will be merged as |
1108 * <pre>191B1D 02 1F2123 01 050505 02 050505 01 910505 02 910505 00</pre> | 1142 * <pre>191B1D 02 1F2123 01 050505 02 050505 01 910505 02 910505 00</pre> |
(...skipping 42 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1151 * @return attribute value | 1185 * @return attribute value |
1152 * @param status to indicate whether the operation went on smoothly or there wer
e errors | 1186 * @param status to indicate whether the operation went on smoothly or there wer
e errors |
1153 * @see UColAttribute | 1187 * @see UColAttribute |
1154 * @see UColAttributeValue | 1188 * @see UColAttributeValue |
1155 * @see ucol_setAttribute | 1189 * @see ucol_setAttribute |
1156 * @stable ICU 2.0 | 1190 * @stable ICU 2.0 |
1157 */ | 1191 */ |
1158 U_STABLE UColAttributeValue U_EXPORT2 | 1192 U_STABLE UColAttributeValue U_EXPORT2 |
1159 ucol_getAttribute(const UCollator *coll, UColAttribute attr, UErrorCode *status)
; | 1193 ucol_getAttribute(const UCollator *coll, UColAttribute attr, UErrorCode *status)
; |
1160 | 1194 |
1161 /** Variable top | 1195 #ifndef U_HIDE_DRAFT_API |
1162 * is a two byte primary value which causes all the codepoints with primary valu
es that | 1196 |
1163 * are less or equal than the variable top to be shifted when alternate handling
is set | 1197 /** |
1164 * to UCOL_SHIFTED. | 1198 * Sets the variable top to the top of the specified reordering group. |
1165 * Sets the variable top to a collation element value of a string supplied. | 1199 * The variable top determines the highest-sorting character |
1166 * @param coll collator which variable top needs to be changed | 1200 * which is affected by UCOL_ALTERNATE_HANDLING. |
| 1201 * If that attribute is set to UCOL_NON_IGNORABLE, then the variable top has no
effect. |
| 1202 * @param coll the collator |
| 1203 * @param group one of UCOL_REORDER_CODE_SPACE, UCOL_REORDER_CODE_PUNCTUATION, |
| 1204 * UCOL_REORDER_CODE_SYMBOL, UCOL_REORDER_CODE_CURRENCY; |
| 1205 * or UCOL_REORDER_CODE_DEFAULT to restore the default max variable
group |
| 1206 * @param pErrorCode Standard ICU error code. Its input value must |
| 1207 * pass the U_SUCCESS() test, or else the function returns |
| 1208 * immediately. Check for U_FAILURE() on output or use with |
| 1209 * function chaining. (See User Guide for details.) |
| 1210 * @see ucol_getMaxVariable |
| 1211 * @draft ICU 53 |
| 1212 */ |
| 1213 U_DRAFT void U_EXPORT2 |
| 1214 ucol_setMaxVariable(UCollator *coll, UColReorderCode group, UErrorCode *pErrorCo
de); |
| 1215 |
| 1216 /** |
| 1217 * Returns the maximum reordering group whose characters are affected by UCOL_AL
TERNATE_HANDLING. |
| 1218 * @param coll the collator |
| 1219 * @return the maximum variable reordering group. |
| 1220 * @see ucol_setMaxVariable |
| 1221 * @draft ICU 53 |
| 1222 */ |
| 1223 U_DRAFT UColReorderCode U_EXPORT2 |
| 1224 ucol_getMaxVariable(const UCollator *coll); |
| 1225 |
| 1226 #endif /* U_HIDE_DRAFT_API */ |
| 1227 |
| 1228 #ifndef U_HIDE_DEPRECATED_API |
| 1229 /** |
| 1230 * Sets the variable top to the primary weight of the specified string. |
| 1231 * |
| 1232 * Beginning with ICU 53, the variable top is pinned to |
| 1233 * the top of one of the supported reordering groups, |
| 1234 * and it must not be beyond the last of those groups. |
| 1235 * See ucol_setMaxVariable(). |
| 1236 * @param coll the collator |
1167 * @param varTop one or more (if contraction) UChars to which the variable top s
hould be set | 1237 * @param varTop one or more (if contraction) UChars to which the variable top s
hould be set |
1168 * @param len length of variable top string. If -1 it is considered to be zero t
erminated. | 1238 * @param len length of variable top string. If -1 it is considered to be zero t
erminated. |
1169 * @param status error code. If error code is set, the return value is undefined
. | 1239 * @param status error code. If error code is set, the return value is undefined
. |
1170 * Errors set by this function are: <br> | 1240 * Errors set by this function are:<br> |
1171 * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no
such | 1241 * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no
such contraction<br> |
1172 * a contraction<br> | 1242 * U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond |
1173 * U_PRIMARY_TOO_LONG_ERROR if the primary for the variable top has more than
two bytes | 1243 * the last reordering group supported by ucol_setMaxVariable() |
1174 * @return a 32 bit value containing the value of the variable top in upper 16 b
its. | 1244 * @return variable top primary weight |
1175 * Lower 16 bits are undefined | |
1176 * @see ucol_getVariableTop | 1245 * @see ucol_getVariableTop |
1177 * @see ucol_restoreVariableTop | 1246 * @see ucol_restoreVariableTop |
1178 * @stable ICU 2.0 | 1247 * @deprecated ICU 53 Call ucol_setMaxVariable() instead. |
1179 */ | 1248 */ |
1180 U_STABLE uint32_t U_EXPORT2 | 1249 U_DEPRECATED uint32_t U_EXPORT2 |
1181 ucol_setVariableTop(UCollator *coll, | 1250 ucol_setVariableTop(UCollator *coll, |
1182 const UChar *varTop, int32_t len, | 1251 const UChar *varTop, int32_t len, |
1183 UErrorCode *status); | 1252 UErrorCode *status); |
| 1253 #endif /* U_HIDE_DEPRECATED_API */ |
1184 | 1254 |
1185 /** | 1255 /** |
1186 * Gets the variable top value of a Collator. | 1256 * Gets the variable top value of a Collator. |
1187 * Lower 16 bits are undefined and should be ignored. | |
1188 * @param coll collator which variable top needs to be retrieved | 1257 * @param coll collator which variable top needs to be retrieved |
1189 * @param status error code (not changed by function). If error code is set, | 1258 * @param status error code (not changed by function). If error code is set, |
1190 * the return value is undefined. | 1259 * the return value is undefined. |
1191 * @return the variable top value of a Collator. | 1260 * @return the variable top primary weight |
| 1261 * @see ucol_getMaxVariable |
1192 * @see ucol_setVariableTop | 1262 * @see ucol_setVariableTop |
1193 * @see ucol_restoreVariableTop | 1263 * @see ucol_restoreVariableTop |
1194 * @stable ICU 2.0 | 1264 * @stable ICU 2.0 |
1195 */ | 1265 */ |
1196 U_STABLE uint32_t U_EXPORT2 ucol_getVariableTop(const UCollator *coll, UErrorCod
e *status); | 1266 U_STABLE uint32_t U_EXPORT2 ucol_getVariableTop(const UCollator *coll, UErrorCod
e *status); |
1197 | 1267 |
1198 /** | 1268 /** |
1199 * Sets the variable top to a collation element value supplied. Variable top is | 1269 * Sets the variable top to the specified primary weight. |
1200 * set to the upper 16 bits. | 1270 * |
1201 * Lower 16 bits are ignored. | 1271 * Beginning with ICU 53, the variable top is pinned to |
1202 * @param coll collator which variable top needs to be changed | 1272 * the top of one of the supported reordering groups, |
1203 * @param varTop CE value, as returned by ucol_setVariableTop or ucol)getVariabl
eTop | 1273 * and it must not be beyond the last of those groups. |
1204 * @param status error code (not changed by function) | 1274 * See ucol_setMaxVariable(). |
| 1275 * @param varTop primary weight, as returned by ucol_setVariableTop or ucol_getV
ariableTop |
| 1276 * @param status error code |
1205 * @see ucol_getVariableTop | 1277 * @see ucol_getVariableTop |
1206 * @see ucol_setVariableTop | 1278 * @see ucol_setVariableTop |
1207 * @stable ICU 2.0 | 1279 * @deprecated ICU 53 Call ucol_setMaxVariable() instead. |
1208 */ | 1280 */ |
1209 U_STABLE void U_EXPORT2 | 1281 U_DEPRECATED void U_EXPORT2 |
1210 ucol_restoreVariableTop(UCollator *coll, const uint32_t varTop, UErrorCode *stat
us); | 1282 ucol_restoreVariableTop(UCollator *coll, const uint32_t varTop, UErrorCode *stat
us); |
1211 | 1283 |
1212 /** | 1284 /** |
1213 * Thread safe cloning operation. The result is a clone of a given collator. | 1285 * Thread safe cloning operation. The result is a clone of a given collator. |
1214 * @param coll collator to be cloned | 1286 * @param coll collator to be cloned |
1215 * @param stackBuffer <em>Deprecated functionality as of ICU 52, use NULL.</em><
br> | 1287 * @param stackBuffer <em>Deprecated functionality as of ICU 52, use NULL.</em><
br> |
1216 * user allocated space for the new clone. | 1288 * user allocated space for the new clone. |
1217 * If NULL new memory will be allocated. | 1289 * If NULL new memory will be allocated. |
1218 * If buffer is not large enough, new memory will be allocated. | 1290 * If buffer is not large enough, new memory will be allocated. |
1219 * Clients can use the U_COL_SAFECLONE_BUFFERSIZE. | 1291 * Clients can use the U_COL_SAFECLONE_BUFFERSIZE. |
(...skipping 75 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1295 * @param status error code of the operation | 1367 * @param status error code of the operation |
1296 * @return real locale name from which the collation data comes. | 1368 * @return real locale name from which the collation data comes. |
1297 * If the collator was instantiated from rules, returns | 1369 * If the collator was instantiated from rules, returns |
1298 * NULL. | 1370 * NULL. |
1299 * @stable ICU 2.8 | 1371 * @stable ICU 2.8 |
1300 */ | 1372 */ |
1301 U_STABLE const char * U_EXPORT2 | 1373 U_STABLE const char * U_EXPORT2 |
1302 ucol_getLocaleByType(const UCollator *coll, ULocDataLocaleType type, UErrorCode
*status); | 1374 ucol_getLocaleByType(const UCollator *coll, ULocDataLocaleType type, UErrorCode
*status); |
1303 | 1375 |
1304 /** | 1376 /** |
1305 * Get an Unicode set that contains all the characters and sequences tailored in
| 1377 * Get a Unicode set that contains all the characters and sequences tailored in |
1306 * this collator. The result must be disposed of by using uset_close. | 1378 * this collator. The result must be disposed of by using uset_close. |
1307 * @param coll The UCollator for which we want to get tailored chars | 1379 * @param coll The UCollator for which we want to get tailored chars |
1308 * @param status error code of the operation | 1380 * @param status error code of the operation |
1309 * @return a pointer to newly created USet. Must be be disposed by using uset_cl
ose | 1381 * @return a pointer to newly created USet. Must be be disposed by using uset_cl
ose |
1310 * @see ucol_openRules | 1382 * @see ucol_openRules |
1311 * @see uset_close | 1383 * @see uset_close |
1312 * @stable ICU 2.4 | 1384 * @stable ICU 2.4 |
1313 */ | 1385 */ |
1314 U_STABLE USet * U_EXPORT2 | 1386 U_STABLE USet * U_EXPORT2 |
1315 ucol_getTailoredSet(const UCollator *coll, UErrorCode *status); | 1387 ucol_getTailoredSet(const UCollator *coll, UErrorCode *status); |
1316 | 1388 |
1317 #ifndef U_HIDE_INTERNAL_API | 1389 #ifndef U_HIDE_INTERNAL_API |
1318 /** | |
1319 * Universal attribute getter that returns UCOL_DEFAULT if the value is default | |
1320 * @param coll collator which attributes are to be changed | |
1321 * @param attr attribute type | |
1322 * @return attribute value or UCOL_DEFAULT if the value is default | |
1323 * @param status to indicate whether the operation went on smoothly or there wer
e errors | |
1324 * @see UColAttribute | |
1325 * @see UColAttributeValue | |
1326 * @see ucol_setAttribute | |
1327 * @internal ICU 3.0 | |
1328 */ | |
1329 U_INTERNAL UColAttributeValue U_EXPORT2 | |
1330 ucol_getAttributeOrDefault(const UCollator *coll, UColAttribute attr, UErrorCode
*status); | |
1331 | |
1332 /** Check whether two collators are equal. Collators are considered equal if the
y | |
1333 * will sort strings the same. This means that both the current attributes and
the | |
1334 * rules must be equivalent. Currently used for RuleBasedCollator::operator==. | |
1335 * @param source first collator | |
1336 * @param target second collator | |
1337 * @return TRUE or FALSE | |
1338 * @internal ICU 3.0 | |
1339 */ | |
1340 U_INTERNAL UBool U_EXPORT2 | |
1341 ucol_equals(const UCollator *source, const UCollator *target); | |
1342 | |
1343 /** Calculates the set of unsafe code points, given a collator. | 1390 /** Calculates the set of unsafe code points, given a collator. |
1344 * A character is unsafe if you could append any character and cause the order
ing to alter significantly. | 1391 * A character is unsafe if you could append any character and cause the order
ing to alter significantly. |
1345 * Collation sorts in normalized order, so anything that rearranges in normali
zation can cause this. | 1392 * Collation sorts in normalized order, so anything that rearranges in normali
zation can cause this. |
1346 * Thus if you have a character like a_umlaut, and you add a lower_dot to it, | 1393 * Thus if you have a character like a_umlaut, and you add a lower_dot to it, |
1347 * then it normalizes to a_lower_dot + umlaut, and sorts differently. | 1394 * then it normalizes to a_lower_dot + umlaut, and sorts differently. |
1348 * @param coll Collator | 1395 * @param coll Collator |
1349 * @param unsafe a fill-in set to receive the unsafe points | 1396 * @param unsafe a fill-in set to receive the unsafe points |
1350 * @param status for catching errors | 1397 * @param status for catching errors |
1351 * @return number of elements in the set | 1398 * @return number of elements in the set |
1352 * @internal ICU 3.0 | 1399 * @internal ICU 3.0 |
1353 */ | 1400 */ |
1354 U_INTERNAL int32_t U_EXPORT2 | 1401 U_INTERNAL int32_t U_EXPORT2 |
1355 ucol_getUnsafeSet( const UCollator *coll, | 1402 ucol_getUnsafeSet( const UCollator *coll, |
1356 USet *unsafe, | 1403 USet *unsafe, |
1357 UErrorCode *status); | 1404 UErrorCode *status); |
1358 | 1405 |
1359 /** Reset UCA's static pointers. You don't want to use this, unless your static
memory can go away. | |
1360 * @internal ICU 3.2.1 | |
1361 */ | |
1362 U_INTERNAL void U_EXPORT2 | |
1363 ucol_forgetUCA(void); | |
1364 | |
1365 /** Touches all resources needed for instantiating a collator from a short strin
g definition, | 1406 /** Touches all resources needed for instantiating a collator from a short strin
g definition, |
1366 * thus filling up the cache. | 1407 * thus filling up the cache. |
1367 * @param definition A short string containing a locale and a set of attributes.
| 1408 * @param definition A short string containing a locale and a set of attributes.
|
1368 * Attributes not explicitly mentioned are left at the default | 1409 * Attributes not explicitly mentioned are left at the default |
1369 * state for a locale. | 1410 * state for a locale. |
1370 * @param parseError if not NULL, structure that will get filled with error's pr
e | 1411 * @param parseError if not NULL, structure that will get filled with error's pr
e |
1371 * and post context in case of error. | 1412 * and post context in case of error. |
1372 * @param forceDefaults if FALSE, the settings that are the same as the collator
| 1413 * @param forceDefaults if FALSE, the settings that are the same as the collator
|
1373 * default settings will not be applied (for example, setting | 1414 * default settings will not be applied (for example, setting |
1374 * French secondary on a French collator would not be executed
). | 1415 * French secondary on a French collator would not be executed
). |
(...skipping 27 matching lines...) Expand all Loading... |
1402 */ | 1443 */ |
1403 U_STABLE int32_t U_EXPORT2 | 1444 U_STABLE int32_t U_EXPORT2 |
1404 ucol_cloneBinary(const UCollator *coll, | 1445 ucol_cloneBinary(const UCollator *coll, |
1405 uint8_t *buffer, int32_t capacity, | 1446 uint8_t *buffer, int32_t capacity, |
1406 UErrorCode *status); | 1447 UErrorCode *status); |
1407 | 1448 |
1408 /** Opens a collator from a collator binary image created using | 1449 /** Opens a collator from a collator binary image created using |
1409 * ucol_cloneBinary. Binary image used in instantiation of the | 1450 * ucol_cloneBinary. Binary image used in instantiation of the |
1410 * collator remains owned by the user and should stay around for | 1451 * collator remains owned by the user and should stay around for |
1411 * the lifetime of the collator. The API also takes a base collator | 1452 * the lifetime of the collator. The API also takes a base collator |
1412 * which usualy should be UCA. | 1453 * which must be the root collator. |
1413 * @param bin binary image owned by the user and required through the | 1454 * @param bin binary image owned by the user and required through the |
1414 * lifetime of the collator | 1455 * lifetime of the collator |
1415 * @param length size of the image. If negative, the API will try to | 1456 * @param length size of the image. If negative, the API will try to |
1416 * figure out the length of the image | 1457 * figure out the length of the image |
1417 * @param base fallback collator, usually UCA. Base is required to be | 1458 * @param base Base collator, for lookup of untailored characters. |
1418 * present through the lifetime of the collator. Currently | 1459 * Must be the root collator, must not be NULL. |
1419 * it cannot be NULL. | 1460 * The base is required to be present through the lifetime of the c
ollator. |
1420 * @param status for catching errors | 1461 * @param status for catching errors |
1421 * @return newly created collator | 1462 * @return newly created collator |
1422 * @see ucol_cloneBinary | 1463 * @see ucol_cloneBinary |
1423 * @stable ICU 3.2 | 1464 * @stable ICU 3.2 |
1424 */ | 1465 */ |
1425 U_STABLE UCollator* U_EXPORT2 | 1466 U_STABLE UCollator* U_EXPORT2 |
1426 ucol_openBinary(const uint8_t *bin, int32_t length, | 1467 ucol_openBinary(const uint8_t *bin, int32_t length, |
1427 const UCollator *base, | 1468 const UCollator *base, |
1428 UErrorCode *status); | 1469 UErrorCode *status); |
1429 | 1470 |
1430 | 1471 |
1431 #endif /* #if !UCONFIG_NO_COLLATION */ | 1472 #endif /* #if !UCONFIG_NO_COLLATION */ |
1432 | 1473 |
1433 #endif | 1474 #endif |
OLD | NEW |