Where Online Learning is simpler!
The C and C++ Include Header Files
/usr/include/unicode/coll.h
$ cat -n /usr/include/unicode/coll.h 1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ****************************************************************************** 5 * Copyright (C) 1996-2016, International Business Machines 6 * Corporation and others. All Rights Reserved. 7 ****************************************************************************** 8 */ 9 10 /** 11 * \file 12 * \brief C++ API: Collation Service. 13 */ 14 15 /** 16 * File coll.h 17 * 18 * Created by: Helena Shih 19 * 20 * Modification History: 21 * 22 * Date Name Description 23 * 02/5/97 aliu Modified createDefault to load collation data from 24 * binary files when possible. Added related methods 25 * createCollationFromFile, chopLocale, createPathName. 26 * 02/11/97 aliu Added members addToCache, findInCache, and fgCache. 27 * 02/12/97 aliu Modified to create objects from RuleBasedCollator cache. 28 * Moved cache out of Collation class. 29 * 02/13/97 aliu Moved several methods out of this class and into 30 * RuleBasedCollator, with modifications. Modified 31 * createDefault() to call new RuleBasedCollator(Locale&) 32 * constructor. General clean up and documentation. 33 * 02/20/97 helena Added clone, operator==, operator!=, operator=, copy 34 * constructor and getDynamicClassID. 35 * 03/25/97 helena Updated with platform independent data types. 36 * 05/06/97 helena Added memory allocation error detection. 37 * 06/20/97 helena Java class name change. 38 * 09/03/97 helena Added createCollationKeyValues(). 39 * 02/10/98 damiba Added compare() with length as parameter. 40 * 04/23/99 stephen Removed EDecompositionMode, merged with 41 * Normalizer::EMode. 42 * 11/02/99 helena Collator performance enhancements. Eliminates the 43 * UnicodeString construction and special case for NO_OP. 44 * 11/23/99 srl More performance enhancements. Inlining of 45 * critical accessors. 46 * 05/15/00 helena Added version information API. 47 * 01/29/01 synwee Modified into a C++ wrapper which calls C apis 48 * (ucol.h). 49 * 2012-2014 markus Rewritten in C++ again. 50 */ 51 52 #ifndef COLL_H 53 #define COLL_H 54 55 #include "unicode/utypes.h" 56 57 #if U_SHOW_CPLUSPLUS_API 58 59 #if !UCONFIG_NO_COLLATION 60 61 #include "unicode/uobject.h" 62 #include "unicode/ucol.h" 63 #include "unicode/unorm.h" 64 #include "unicode/locid.h" 65 #include "unicode/uniset.h" 66 #include "unicode/umisc.h" 67 #include "unicode/uiter.h" 68 #include "unicode/stringpiece.h" 69 70 U_NAMESPACE_BEGIN 71 72 class StringEnumeration; 73 74 #if !UCONFIG_NO_SERVICE 75 /** 76 * @stable ICU 2.6 77 */ 78 class CollatorFactory; 79 #endif 80 81 /** 82 * @stable ICU 2.0 83 */ 84 class CollationKey; 85 86 /** 87 * The <code>Collator</code> class performs locale-sensitive string 88 * comparison.<br> 89 * You use this class to build searching and sorting routines for natural 90 * language text. 91 * <p> 92 * <code>Collator</code> is an abstract base class. Subclasses implement 93 * specific collation strategies. One subclass, 94 * <code>RuleBasedCollator</code>, is currently provided and is applicable 95 * to a wide set of languages. Other subclasses may be created to handle more 96 * specialized needs. 97 * <p> 98 * Like other locale-sensitive classes, you can use the static factory method, 99 * <code>createInstance</code>, to obtain the appropriate 100 * <code>Collator</code> object for a given locale. You will only need to 101 * look at the subclasses of <code>Collator</code> if you need to 102 * understand the details of a particular collation strategy or if you need to 103 * modify that strategy. 104 * <p> 105 * The following example shows how to compare two strings using the 106 * <code>Collator</code> for the default locale. 107 * \htmlonly<blockquote>\endhtmlonly 108 * <pre> 109 * \code 110 * // Compare two strings in the default locale 111 * UErrorCode success = U_ZERO_ERROR; 112 * Collator* myCollator = Collator::createInstance(success); 113 * if (myCollator->compare("abc", "ABC") < 0) 114 * cout << "abc is less than ABC" << endl; 115 * else 116 * cout << "abc is greater than or equal to ABC" << endl; 117 * \endcode 118 * </pre> 119 * \htmlonly</blockquote>\endhtmlonly 120 * <p> 121 * You can set a <code>Collator</code>'s <em>strength</em> attribute to 122 * determine the level of difference considered significant in comparisons. 123 * Five strengths are provided: <code>PRIMARY</code>, <code>SECONDARY</code>, 124 * <code>TERTIARY</code>, <code>QUATERNARY</code> and <code>IDENTICAL</code>. 125 * The exact assignment of strengths to language features is locale dependent. 126 * For example, in Czech, "e" and "f" are considered primary differences, 127 * while "e" and "\u00EA" are secondary differences, "e" and "E" are tertiary 128 * differences and "e" and "e" are identical. The following shows how both case 129 * and accents could be ignored for US English. 130 * \htmlonly<blockquote>\endhtmlonly 131 * <pre> 132 * \code 133 * //Get the Collator for US English and set its strength to PRIMARY 134 * UErrorCode success = U_ZERO_ERROR; 135 * Collator* usCollator = Collator::createInstance(Locale::getUS(), success); 136 * usCollator->setStrength(Collator::PRIMARY); 137 * if (usCollator->compare("abc", "ABC") == 0) 138 * cout << "'abc' and 'ABC' strings are equivalent with strength PRIMARY" << endl; 139 * \endcode 140 * </pre> 141 * \htmlonly</blockquote>\endhtmlonly 142 * 143 * The <code>getSortKey</code> methods 144 * convert a string to a series of bytes that can be compared bitwise against 145 * other sort keys using <code>strcmp()</code>. Sort keys are written as 146 * zero-terminated byte strings. 147 * 148 * Another set of APIs returns a <code>CollationKey</code> object that wraps 149 * the sort key bytes instead of returning the bytes themselves. 150 * </p> 151 * <p> 152 * <strong>Note:</strong> <code>Collator</code>s with different Locale, 153 * and CollationStrength settings will return different sort 154 * orders for the same set of strings. Locales have specific collation rules, 155 * and the way in which secondary and tertiary differences are taken into 156 * account, for example, will result in a different sorting order for same 157 * strings. 158 * </p> 159 * @see RuleBasedCollator 160 * @see CollationKey 161 * @see CollationElementIterator 162 * @see Locale 163 * @see Normalizer2 164 * @version 2.0 11/15/01 165 */ 166 167 class U_I18N_API Collator : public UObject { 168 public: 169 170 // Collator public enums ----------------------------------------------- 171 172 /** 173 * Base letter represents a primary difference. Set comparison level to 174 * PRIMARY to ignore secondary and tertiary differences.<br> 175 * Use this to set the strength of a Collator object.<br> 176 * Example of primary difference, "abc" < "abd" 177 * 178 * Diacritical differences on the same base letter represent a secondary 179 * difference. Set comparison level to SECONDARY to ignore tertiary 180 * differences. Use this to set the strength of a Collator object.<br> 181 * Example of secondary difference, "ä" >> "a". 182 * 183 * Uppercase and lowercase versions of the same character represents a 184 * tertiary difference. Set comparison level to TERTIARY to include all 185 * comparison differences. Use this to set the strength of a Collator 186 * object.<br> 187 * Example of tertiary difference, "abc" <<< "ABC". 188 * 189 * Two characters are considered "identical" when they have the same unicode 190 * spellings.<br> 191 * For example, "ä" == "ä". 192 * 193 * UCollationStrength is also used to determine the strength of sort keys 194 * generated from Collator objects. 195 * @stable ICU 2.0 196 */ 197 enum ECollationStrength 198 { 199 PRIMARY = UCOL_PRIMARY, // 0 200 SECONDARY = UCOL_SECONDARY, // 1 201 TERTIARY = UCOL_TERTIARY, // 2 202 QUATERNARY = UCOL_QUATERNARY, // 3 203 IDENTICAL = UCOL_IDENTICAL // 15 204 }; 205 206 207 // Cannot use #ifndef U_HIDE_DEPRECATED_API for the following, it is 208 // used by virtual methods that cannot have that conditional. 209 #ifndef U_FORCE_HIDE_DEPRECATED_API 210 /** 211 * LESS is returned if source string is compared to be less than target 212 * string in the compare() method. 213 * EQUAL is returned if source string is compared to be equal to target 214 * string in the compare() method. 215 * GREATER is returned if source string is compared to be greater than 216 * target string in the compare() method. 217 * @see Collator#compare 218 * @deprecated ICU 2.6. Use C enum UCollationResult defined in ucol.h 219 */ 220 enum EComparisonResult 221 { 222 LESS = UCOL_LESS, // -1 223 EQUAL = UCOL_EQUAL, // 0 224 GREATER = UCOL_GREATER // 1 225 }; 226 #endif // U_FORCE_HIDE_DEPRECATED_API 227 228 // Collator public destructor ----------------------------------------- 229 230 /** 231 * Destructor 232 * @stable ICU 2.0 233 */ 234 virtual ~Collator(); 235 236 // Collator public methods -------------------------------------------- 237 238 /** 239 * Returns true if "other" is the same as "this". 240 * 241 * The base class implementation returns true if "other" has the same type/class as "this": 242 * `typeid(*this) == typeid(other)`. 243 * 244 * Subclass implementations should do something like the following: 245 * 246 * if (this == &other) { return true; } 247 * if (!Collator::operator==(other)) { return false; } // not the same class 248 * 249 * const MyCollator &o = (const MyCollator&)other; 250 * (compare this vs. o's subclass fields) 251 * 252 * @param other Collator object to be compared 253 * @return true if other is the same as this. 254 * @stable ICU 2.0 255 */ 256 virtual bool operator==(const Collator& other) const; 257 258 /** 259 * Returns true if "other" is not the same as "this". 260 * Calls ! operator==(const Collator&) const which works for all subclasses. 261 * @param other Collator object to be compared 262 * @return true if other is not the same as this. 263 * @stable ICU 2.0 264 */ 265 virtual bool operator!=(const Collator& other) const; 266 267 /** 268 * Makes a copy of this object. 269 * @return a copy of this object, owned by the caller 270 * @stable ICU 2.0 271 */ 272 virtual Collator* clone() const = 0; 273 274 /** 275 * Creates the Collator object for the current default locale. 276 * The default locale is determined by Locale::getDefault. 277 * The UErrorCode& err parameter is used to return status information to the user. 278 * To check whether the construction succeeded or not, you should check the 279 * value of U_SUCCESS(err). If you wish more detailed information, you can 280 * check for informational error results which still indicate success. 281 * U_USING_FALLBACK_ERROR indicates that a fall back locale was used. For 282 * example, 'de_CH' was requested, but nothing was found there, so 'de' was 283 * used. U_USING_DEFAULT_ERROR indicates that the default locale data was 284 * used; neither the requested locale nor any of its fall back locales 285 * could be found. 286 * The caller owns the returned object and is responsible for deleting it. 287 * 288 * @param err the error code status. 289 * @return the collation object of the default locale.(for example, en_US) 290 * @see Locale#getDefault 291 * @stable ICU 2.0 292 */ 293 static Collator* U_EXPORT2 createInstance(UErrorCode& err); 294 295 /** 296 * Gets the collation object for the desired locale. The 297 * resource of the desired locale will be loaded. 298 * 299 * Locale::getRoot() is the base collation table and all other languages are 300 * built on top of it with additional language-specific modifications. 301 * 302 * For some languages, multiple collation types are available; 303 * for example, "de@collation=phonebook". 304 * Starting with ICU 54, collation attributes can be specified via locale keywords as well, 305 * in the old locale extension syntax ("el@colCaseFirst=upper") 306 * or in language tag syntax ("el-u-kf-upper"). 307 * See <a href="https://unicode-org.github.io/icu/userguide/collation/api">User Guide: Collation API</a>. 308 * 309 * The UErrorCode& err parameter is used to return status information to the user. 310 * To check whether the construction succeeded or not, you should check 311 * the value of U_SUCCESS(err). If you wish more detailed information, you 312 * can check for informational error results which still indicate success. 313 * U_USING_FALLBACK_ERROR indicates that a fall back locale was used. For 314 * example, 'de_CH' was requested, but nothing was found there, so 'de' was 315 * used. U_USING_DEFAULT_ERROR indicates that the default locale data was 316 * used; neither the requested locale nor any of its fall back locales 317 * could be found. 318 * 319 * The caller owns the returned object and is responsible for deleting it. 320 * @param loc The locale ID for which to open a collator. 321 * @param err the error code status. 322 * @return the created table-based collation object based on the desired 323 * locale. 324 * @see Locale 325 * @see ResourceLoader 326 * @stable ICU 2.2 327 */ 328 static Collator* U_EXPORT2 createInstance(const Locale& loc, UErrorCode& err); 329 330 #ifndef U_FORCE_HIDE_DEPRECATED_API 331 /** 332 * The comparison function compares the character data stored in two 333 * different strings. Returns information about whether a string is less 334 * than, greater than or equal to another string. 335 * @param source the source string to be compared with. 336 * @param target the string that is to be compared with the source string. 337 * @return Returns a byte value. GREATER if source is greater 338 * than target; EQUAL if source is equal to target; LESS if source is less 339 * than target 340 * @deprecated ICU 2.6 use the overload with UErrorCode & 341 */ 342 virtual EComparisonResult compare(const UnicodeString& source, 343 const UnicodeString& target) const; 344 #endif // U_FORCE_HIDE_DEPRECATED_API 345 346 /** 347 * The comparison function compares the character data stored in two 348 * different strings. Returns information about whether a string is less 349 * than, greater than or equal to another string. 350 * @param source the source string to be compared with. 351 * @param target the string that is to be compared with the source string. 352 * @param status possible error code 353 * @return Returns an enum value. UCOL_GREATER if source is greater 354 * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less 355 * than target 356 * @stable ICU 2.6 357 */ 358 virtual UCollationResult compare(const UnicodeString& source, 359 const UnicodeString& target, 360 UErrorCode &status) const = 0; 361 362 #ifndef U_FORCE_HIDE_DEPRECATED_API 363 /** 364 * Does the same thing as compare but limits the comparison to a specified 365 * length 366 * @param source the source string to be compared with. 367 * @param target the string that is to be compared with the source string. 368 * @param length the length the comparison is limited to 369 * @return Returns a byte value. GREATER if source (up to the specified 370 * length) is greater than target; EQUAL if source (up to specified 371 * length) is equal to target; LESS if source (up to the specified 372 * length) is less than target. 373 * @deprecated ICU 2.6 use the overload with UErrorCode & 374 */ 375 virtual EComparisonResult compare(const UnicodeString& source, 376 const UnicodeString& target, 377 int32_t length) const; 378 #endif // U_FORCE_HIDE_DEPRECATED_API 379 380 /** 381 * Does the same thing as compare but limits the comparison to a specified 382 * length 383 * @param source the source string to be compared with. 384 * @param target the string that is to be compared with the source string. 385 * @param length the length the comparison is limited to 386 * @param status possible error code 387 * @return Returns an enum value. UCOL_GREATER if source (up to the specified 388 * length) is greater than target; UCOL_EQUAL if source (up to specified 389 * length) is equal to target; UCOL_LESS if source (up to the specified 390 * length) is less than target. 391 * @stable ICU 2.6 392 */ 393 virtual UCollationResult compare(const UnicodeString& source, 394 const UnicodeString& target, 395 int32_t length, 396 UErrorCode &status) const = 0; 397 398 #ifndef U_FORCE_HIDE_DEPRECATED_API 399 /** 400 * The comparison function compares the character data stored in two 401 * different string arrays. Returns information about whether a string array 402 * is less than, greater than or equal to another string array. 403 * <p>Example of use: 404 * <pre> 405 * . char16_t ABC[] = {0x41, 0x42, 0x43, 0}; // = "ABC" 406 * . char16_t abc[] = {0x61, 0x62, 0x63, 0}; // = "abc" 407 * . UErrorCode status = U_ZERO_ERROR; 408 * . Collator *myCollation = 409 * . Collator::createInstance(Locale::getUS(), status); 410 * . if (U_FAILURE(status)) return; 411 * . myCollation->setStrength(Collator::PRIMARY); 412 * . // result would be Collator::EQUAL ("abc" == "ABC") 413 * . // (no primary difference between "abc" and "ABC") 414 * . Collator::EComparisonResult result = 415 * . myCollation->compare(abc, 3, ABC, 3); 416 * . myCollation->setStrength(Collator::TERTIARY); 417 * . // result would be Collator::LESS ("abc" <<< "ABC") 418 * . // (with tertiary difference between "abc" and "ABC") 419 * . result = myCollation->compare(abc, 3, ABC, 3); 420 * </pre> 421 * @param source the source string array to be compared with. 422 * @param sourceLength the length of the source string array. If this value 423 * is equal to -1, the string array is null-terminated. 424 * @param target the string that is to be compared with the source string. 425 * @param targetLength the length of the target string array. If this value 426 * is equal to -1, the string array is null-terminated. 427 * @return Returns a byte value. GREATER if source is greater than target; 428 * EQUAL if source is equal to target; LESS if source is less than 429 * target 430 * @deprecated ICU 2.6 use the overload with UErrorCode & 431 */ 432 virtual EComparisonResult compare(const char16_t* source, int32_t sourceLength, 433 const char16_t* target, int32_t targetLength) 434 const; 435 #endif // U_FORCE_HIDE_DEPRECATED_API 436 437 /** 438 * The comparison function compares the character data stored in two 439 * different string arrays. Returns information about whether a string array 440 * is less than, greater than or equal to another string array. 441 * @param source the source string array to be compared with. 442 * @param sourceLength the length of the source string array. If this value 443 * is equal to -1, the string array is null-terminated. 444 * @param target the string that is to be compared with the source string. 445 * @param targetLength the length of the target string array. If this value 446 * is equal to -1, the string array is null-terminated. 447 * @param status possible error code 448 * @return Returns an enum value. UCOL_GREATER if source is greater 449 * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less 450 * than target 451 * @stable ICU 2.6 452 */ 453 virtual UCollationResult compare(const char16_t* source, int32_t sourceLength, 454 const char16_t* target, int32_t targetLength, 455 UErrorCode &status) const = 0; 456 457 /** 458 * Compares two strings using the Collator. 459 * Returns whether the first one compares less than/equal to/greater than 460 * the second one. 461 * This version takes UCharIterator input. 462 * @param sIter the first ("source") string iterator 463 * @param tIter the second ("target") string iterator 464 * @param status ICU status 465 * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER 466 * @stable ICU 4.2 467 */ 468 virtual UCollationResult compare(UCharIterator &sIter, 469 UCharIterator &tIter, 470 UErrorCode &status) const; 471 472 /** 473 * Compares two UTF-8 strings using the Collator. 474 * Returns whether the first one compares less than/equal to/greater than 475 * the second one. 476 * This version takes UTF-8 input. 477 * Note that a StringPiece can be implicitly constructed 478 * from a std::string or a NUL-terminated const char * string. 479 * @param source the first UTF-8 string 480 * @param target the second UTF-8 string 481 * @param status ICU status 482 * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER 483 * @stable ICU 4.2 484 */ 485 virtual UCollationResult compareUTF8(const StringPiece &source, 486 const StringPiece &target, 487 UErrorCode &status) const; 488 489 /** 490 * Transforms the string into a series of characters that can be compared 491 * with CollationKey::compareTo. It is not possible to restore the original 492 * string from the chars in the sort key. 493 * <p>Use CollationKey::equals or CollationKey::compare to compare the 494 * generated sort keys. 495 * If the source string is null, a null collation key will be returned. 496 * 497 * Note that sort keys are often less efficient than simply doing comparison. 498 * For more details, see the ICU User Guide. 499 * 500 * @param source the source string to be transformed into a sort key. 501 * @param key the collation key to be filled in 502 * @param status the error code status. 503 * @return the collation key of the string based on the collation rules. 504 * @see CollationKey#compare 505 * @stable ICU 2.0 506 */ 507 virtual CollationKey& getCollationKey(const UnicodeString& source, 508 CollationKey& key, 509 UErrorCode& status) const = 0; 510 511 /** 512 * Transforms the string into a series of characters that can be compared 513 * with CollationKey::compareTo. It is not possible to restore the original 514 * string from the chars in the sort key. 515 * <p>Use CollationKey::equals or CollationKey::compare to compare the 516 * generated sort keys. 517 * <p>If the source string is null, a null collation key will be returned. 518 * 519 * Note that sort keys are often less efficient than simply doing comparison. 520 * For more details, see the ICU User Guide. 521 * 522 * @param source the source string to be transformed into a sort key. 523 * @param sourceLength length of the collation key 524 * @param key the collation key to be filled in 525 * @param status the error code status. 526 * @return the collation key of the string based on the collation rules. 527 * @see CollationKey#compare 528 * @stable ICU 2.0 529 */ 530 virtual CollationKey& getCollationKey(const char16_t*source, 531 int32_t sourceLength, 532 CollationKey& key, 533 UErrorCode& status) const = 0; 534 /** 535 * Generates the hash code for the collation object 536 * @stable ICU 2.0 537 */ 538 virtual int32_t hashCode(void) const = 0; 539 540 #ifndef U_FORCE_HIDE_DEPRECATED_API 541 /** 542 * Gets the locale of the Collator 543 * 544 * @param type can be either requested, valid or actual locale. For more 545 * information see the definition of ULocDataLocaleType in 546 * uloc.h 547 * @param status the error code status. 548 * @return locale where the collation data lives. If the collator 549 * was instantiated from rules, locale is empty. 550 * @deprecated ICU 2.8 This API is under consideration for revision 551 * in ICU 3.0. 552 */ 553 virtual Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const = 0; 554 #endif // U_FORCE_HIDE_DEPRECATED_API 555 556 /** 557 * Convenience method for comparing two strings based on the collation rules. 558 * @param source the source string to be compared with. 559 * @param target the target string to be compared with. 560 * @return true if the first string is greater than the second one, 561 * according to the collation rules. false, otherwise. 562 * @see Collator#compare 563 * @stable ICU 2.0 564 */ 565 UBool greater(const UnicodeString& source, const UnicodeString& target) 566 const; 567 568 /** 569 * Convenience method for comparing two strings based on the collation rules. 570 * @param source the source string to be compared with. 571 * @param target the target string to be compared with. 572 * @return true if the first string is greater than or equal to the second 573 * one, according to the collation rules. false, otherwise. 574 * @see Collator#compare 575 * @stable ICU 2.0 576 */ 577 UBool greaterOrEqual(const UnicodeString& source, 578 const UnicodeString& target) const; 579 580 /** 581 * Convenience method for comparing two strings based on the collation rules. 582 * @param source the source string to be compared with. 583 * @param target the target string to be compared with. 584 * @return true if the strings are equal according to the collation rules. 585 * false, otherwise. 586 * @see Collator#compare 587 * @stable ICU 2.0 588 */ 589 UBool equals(const UnicodeString& source, const UnicodeString& target) const; 590 591 #ifndef U_FORCE_HIDE_DEPRECATED_API 592 /** 593 * Determines the minimum strength that will be used in comparison or 594 * transformation. 595 * <p>E.g. with strength == SECONDARY, the tertiary difference is ignored 596 * <p>E.g. with strength == PRIMARY, the secondary and tertiary difference 597 * are ignored. 598 * @return the current comparison level. 599 * @see Collator#setStrength 600 * @deprecated ICU 2.6 Use getAttribute(UCOL_STRENGTH...) instead 601 */ 602 virtual ECollationStrength getStrength(void) const; 603 604 /** 605 * Sets the minimum strength to be used in comparison or transformation. 606 * <p>Example of use: 607 * <pre> 608 * \code 609 * UErrorCode status = U_ZERO_ERROR; 610 * Collator*myCollation = Collator::createInstance(Locale::getUS(), status); 611 * if (U_FAILURE(status)) return; 612 * myCollation->setStrength(Collator::PRIMARY); 613 * // result will be "abc" == "ABC" 614 * // tertiary differences will be ignored 615 * Collator::ComparisonResult result = myCollation->compare("abc", "ABC"); 616 * \endcode 617 * </pre> 618 * @see Collator#getStrength 619 * @param newStrength the new comparison level. 620 * @deprecated ICU 2.6 Use setAttribute(UCOL_STRENGTH...) instead 621 */ 622 virtual void setStrength(ECollationStrength newStrength); 623 #endif // U_FORCE_HIDE_DEPRECATED_API 624 625 /** 626 * Retrieves the reordering codes for this collator. 627 * @param dest The array to fill with the script ordering. 628 * @param destCapacity The length of dest. If it is 0, then dest may be nullptr and the function 629 * will only return the length of the result without writing any codes (pre-flighting). 630 * @param status A reference to an error code value, which must not indicate 631 * a failure before the function call. 632 * @return The length of the script ordering array. 633 * @see ucol_setReorderCodes 634 * @see Collator#getEquivalentReorderCodes 635 * @see Collator#setReorderCodes 636 * @see UScriptCode 637 * @see UColReorderCode 638 * @stable ICU 4.8 639 */ 640 virtual int32_t getReorderCodes(int32_t *dest, 641 int32_t destCapacity, 642 UErrorCode& status) const; 643 644 /** 645 * Sets the ordering of scripts for this collator. 646 * 647 * <p>The reordering codes are a combination of script codes and reorder codes. 648 * @param reorderCodes An array of script codes in the new order. This can be nullptr if the 649 * length is also set to 0. An empty array will clear any reordering codes on the collator. 650 * @param reorderCodesLength The length of reorderCodes. 651 * @param status error code 652 * @see ucol_setReorderCodes 653 * @see Collator#getReorderCodes 654 * @see Collator#getEquivalentReorderCodes 655 * @see UScriptCode 656 * @see UColReorderCode 657 * @stable ICU 4.8 658 */ 659 virtual void setReorderCodes(const int32_t* reorderCodes, 660 int32_t reorderCodesLength, 661 UErrorCode& status) ; 662 663 /** 664 * Retrieves the reorder codes that are grouped with the given reorder code. Some reorder 665 * codes will be grouped and must reorder together. 666 * Beginning with ICU 55, scripts only reorder together if they are primary-equal, 667 * for example Hiragana and Katakana. 668 * 669 * @param reorderCode The reorder code to determine equivalence for. 670 * @param dest The array to fill with the script equivalence reordering codes. 671 * @param destCapacity The length of dest. If it is 0, then dest may be nullptr and the 672 * function will only return the length of the result without writing any codes (pre-flighting). 673 * @param status A reference to an error code value, which must not indicate 674 * a failure before the function call. 675 * @return The length of the of the reordering code equivalence array. 676 * @see ucol_setReorderCodes 677 * @see Collator#getReorderCodes 678 * @see Collator#setReorderCodes 679 * @see UScriptCode 680 * @see UColReorderCode 681 * @stable ICU 4.8 682 */ 683 static int32_t U_EXPORT2 getEquivalentReorderCodes(int32_t reorderCode, 684 int32_t* dest, 685 int32_t destCapacity, 686 UErrorCode& status); 687 688 /** 689 * Get name of the object for the desired Locale, in the desired language 690 * @param objectLocale must be from getAvailableLocales 691 * @param displayLocale specifies the desired locale for output 692 * @param name the fill-in parameter of the return value 693 * @return display-able name of the object for the object locale in the 694 * desired language 695 * @stable ICU 2.0 696 */ 697 static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale, 698 const Locale& displayLocale, 699 UnicodeString& name); 700 701 /** 702 * Get name of the object for the desired Locale, in the language of the 703 * default locale. 704 * @param objectLocale must be from getAvailableLocales 705 * @param name the fill-in parameter of the return value 706 * @return name of the object for the desired locale in the default language 707 * @stable ICU 2.0 708 */ 709 static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale, 710 UnicodeString& name); 711 712 /** 713 * Get the set of Locales for which Collations are installed. 714 * 715 * <p>Note this does not include locales supported by registered collators. 716 * If collators might have been registered, use the overload of getAvailableLocales 717 * that returns a StringEnumeration.</p> 718 * 719 * @param count the output parameter of number of elements in the locale list 720 * @return the list of available locales for which collations are installed 721 * @stable ICU 2.0 722 */ 723 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count); 724 725 /** 726 * Return a StringEnumeration over the locales available at the time of the call, 727 * including registered locales. If a severe error occurs (such as out of memory 728 * condition) this will return null. If there is no locale data, an empty enumeration 729 * will be returned. 730 * @return a StringEnumeration over the locales available at the time of the call 731 * @stable ICU 2.6 732 */ 733 static StringEnumeration* U_EXPORT2 getAvailableLocales(void); 734 735 /** 736 * Create a string enumerator of all possible keywords that are relevant to 737 * collation. At this point, the only recognized keyword for this 738 * service is "collation". 739 * @param status input-output error code 740 * @return a string enumeration over locale strings. The caller is 741 * responsible for closing the result. 742 * @stable ICU 3.0 743 */ 744 static StringEnumeration* U_EXPORT2 getKeywords(UErrorCode& status); 745 746 /** 747 * Given a keyword, create a string enumeration of all values 748 * for that keyword that are currently in use. 749 * @param keyword a particular keyword as enumerated by 750 * ucol_getKeywords. If any other keyword is passed in, status is set 751 * to U_ILLEGAL_ARGUMENT_ERROR. 752 * @param status input-output error code 753 * @return a string enumeration over collation keyword values, or nullptr 754 * upon error. The caller is responsible for deleting the result. 755 * @stable ICU 3.0 756 */ 757 static StringEnumeration* U_EXPORT2 getKeywordValues(const char *keyword, UErrorCode& status); 758 759 /** 760 * Given a key and a locale, returns an array of string values in a preferred 761 * order that would make a difference. These are all and only those values where 762 * the open (creation) of the service with the locale formed from the input locale 763 * plus input keyword and that value has different behavior than creation with the 764 * input locale alone. 765 * @param keyword one of the keys supported by this service. For now, only 766 * "collation" is supported. 767 * @param locale the locale 768 * @param commonlyUsed if set to true it will return only commonly used values 769 * with the given locale in preferred order. Otherwise, 770 * it will return all the available values for the locale. 771 * @param status ICU status 772 * @return a string enumeration over keyword values for the given key and the locale. 773 * @stable ICU 4.2 774 */ 775 static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* keyword, const Locale& locale, 776 UBool commonlyUsed, UErrorCode& status); 777 778 /** 779 * Return the functionally equivalent locale for the given 780 * requested locale, with respect to given keyword, for the 781 * collation service. If two locales return the same result, then 782 * collators instantiated for these locales will behave 783 * equivalently. The converse is not always true; two collators 784 * may in fact be equivalent, but return different results, due to 785 * internal details. The return result has no other meaning than 786 * that stated above, and implies nothing as to the relationship 787 * between the two locales. This is intended for use by 788 * applications who wish to cache collators, or otherwise reuse 789 * collators when possible. The functional equivalent may change 790 * over time. For more information, please see the <a 791 * href="https://unicode-org.github.io/icu/userguide/locale#locales-and-services"> 792 * Locales and Services</a> section of the ICU User Guide. 793 * @param keyword a particular keyword as enumerated by 794 * ucol_getKeywords. 795 * @param locale the requested locale 796 * @param isAvailable reference to a fillin parameter that 797 * indicates whether the requested locale was 'available' to the 798 * collation service. A locale is defined as 'available' if it 799 * physically exists within the collation locale data. 800 * @param status reference to input-output error code 801 * @return the functionally equivalent collation locale, or the root 802 * locale upon error. 803 * @stable ICU 3.0 804 */ 805 static Locale U_EXPORT2 getFunctionalEquivalent(const char* keyword, const Locale& locale, 806 UBool& isAvailable, UErrorCode& status); 807 808 #if !UCONFIG_NO_SERVICE 809 /** 810 * Register a new Collator. The collator will be adopted. 811 * Because ICU may choose to cache collators internally, this must be 812 * called at application startup, prior to any calls to 813 * Collator::createInstance to avoid undefined behavior. 814 * @param toAdopt the Collator instance to be adopted 815 * @param locale the locale with which the collator will be associated 816 * @param status the in/out status code, no special meanings are assigned 817 * @return a registry key that can be used to unregister this collator 818 * @stable ICU 2.6 819 */ 820 static URegistryKey U_EXPORT2 registerInstance(Collator* toAdopt, const Locale& locale, UErrorCode& status); 821 822 /** 823 * Register a new CollatorFactory. The factory will be adopted. 824 * Because ICU may choose to cache collators internally, this must be 825 * called at application startup, prior to any calls to 826 * Collator::createInstance to avoid undefined behavior. 827 * @param toAdopt the CollatorFactory instance to be adopted 828 * @param status the in/out status code, no special meanings are assigned 829 * @return a registry key that can be used to unregister this collator 830 * @stable ICU 2.6 831 */ 832 static URegistryKey U_EXPORT2 registerFactory(CollatorFactory* toAdopt, UErrorCode& status); 833 834 /** 835 * Unregister a previously-registered Collator or CollatorFactory 836 * using the key returned from the register call. Key becomes 837 * invalid after a successful call and should not be used again. 838 * The object corresponding to the key will be deleted. 839 * Because ICU may choose to cache collators internally, this should 840 * be called during application shutdown, after all calls to 841 * Collator::createInstance to avoid undefined behavior. 842 * @param key the registry key returned by a previous call to registerInstance 843 * @param status the in/out status code, no special meanings are assigned 844 * @return true if the collator for the key was successfully unregistered 845 * @stable ICU 2.6 846 */ 847 static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status); 848 #endif /* UCONFIG_NO_SERVICE */ 849 850 /** 851 * Gets the version information for a Collator. 852 * @param info the version # information, the result will be filled in 853 * @stable ICU 2.0 854 */ 855 virtual void getVersion(UVersionInfo info) const = 0; 856 857 /** 858 * Returns a unique class ID POLYMORPHICALLY. Pure virtual method. 859 * This method is to implement a simple version of RTTI, since not all C++ 860 * compilers support genuine RTTI. Polymorphic operator==() and clone() 861 * methods call this method. 862 * @return The class ID for this object. All objects of a given class have 863 * the same class ID. Objects of other classes have different class 864 * IDs. 865 * @stable ICU 2.0 866 */ 867 virtual UClassID getDynamicClassID(void) const override = 0; 868 869 /** 870 * Universal attribute setter 871 * @param attr attribute type 872 * @param value attribute value 873 * @param status to indicate whether the operation went on smoothly or 874 * there were errors 875 * @stable ICU 2.2 876 */ 877 virtual void setAttribute(UColAttribute attr, UColAttributeValue value, 878 UErrorCode &status) = 0; 879 880 /** 881 * Universal attribute getter 882 * @param attr attribute type 883 * @param status to indicate whether the operation went on smoothly or 884 * there were errors 885 * @return attribute value 886 * @stable ICU 2.2 887 */ 888 virtual UColAttributeValue getAttribute(UColAttribute attr, 889 UErrorCode &status) const = 0; 890 891 /** 892 * Sets the variable top to the top of the specified reordering group. 893 * The variable top determines the highest-sorting character 894 * which is affected by UCOL_ALTERNATE_HANDLING. 895 * If that attribute is set to UCOL_NON_IGNORABLE, then the variable top has no effect. 896 * 897 * The base class implementation sets U_UNSUPPORTED_ERROR. 898 * @param group one of UCOL_REORDER_CODE_SPACE, UCOL_REORDER_CODE_PUNCTUATION, 899 * UCOL_REORDER_CODE_SYMBOL, UCOL_REORDER_CODE_CURRENCY; 900 * or UCOL_REORDER_CODE_DEFAULT to restore the default max variable group 901 * @param errorCode Standard ICU error code. Its input value must 902 * pass the U_SUCCESS() test, or else the function returns 903 * immediately. Check for U_FAILURE() on output or use with 904 * function chaining. (See User Guide for details.) 905 * @return *this 906 * @see getMaxVariable 907 * @stable ICU 53 908 */ 909 virtual Collator &setMaxVariable(UColReorderCode group, UErrorCode &errorCode); 910 911 /** 912 * Returns the maximum reordering group whose characters are affected by UCOL_ALTERNATE_HANDLING. 913 * 914 * The base class implementation returns UCOL_REORDER_CODE_PUNCTUATION. 915 * @return the maximum variable reordering group. 916 * @see setMaxVariable 917 * @stable ICU 53 918 */ 919 virtual UColReorderCode getMaxVariable() const; 920 921 #ifndef U_FORCE_HIDE_DEPRECATED_API 922 /** 923 * Sets the variable top to the primary weight of the specified string. 924 * 925 * Beginning with ICU 53, the variable top is pinned to 926 * the top of one of the supported reordering groups, 927 * and it must not be beyond the last of those groups. 928 * See setMaxVariable(). 929 * @param varTop one or more (if contraction) char16_ts to which the variable top should be set 930 * @param len length of variable top string. If -1 it is considered to be zero terminated. 931 * @param status error code. If error code is set, the return value is undefined. Errors set by this function are: <br> 932 * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such contraction<br> 933 * U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond 934 * the last reordering group supported by setMaxVariable() 935 * @return variable top primary weight 936 * @deprecated ICU 53 Call setMaxVariable() instead. 937 */ 938 virtual uint32_t setVariableTop(const char16_t *varTop, int32_t len, UErrorCode &status) = 0; 939 940 /** 941 * Sets the variable top to the primary weight of the specified string. 942 * 943 * Beginning with ICU 53, the variable top is pinned to 944 * the top of one of the supported reordering groups, 945 * and it must not be beyond the last of those groups. 946 * See setMaxVariable(). 947 * @param varTop a UnicodeString size 1 or more (if contraction) of char16_ts to which the variable top should be set 948 * @param status error code. If error code is set, the return value is undefined. Errors set by this function are: <br> 949 * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such contraction<br> 950 * U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond 951 * the last reordering group supported by setMaxVariable() 952 * @return variable top primary weight 953 * @deprecated ICU 53 Call setMaxVariable() instead. 954 */ 955 virtual uint32_t setVariableTop(const UnicodeString &varTop, UErrorCode &status) = 0; 956 957 /** 958 * Sets the variable top to the specified primary weight. 959 * 960 * Beginning with ICU 53, the variable top is pinned to 961 * the top of one of the supported reordering groups, 962 * and it must not be beyond the last of those groups. 963 * See setMaxVariable(). 964 * @param varTop primary weight, as returned by setVariableTop or ucol_getVariableTop 965 * @param status error code 966 * @deprecated ICU 53 Call setMaxVariable() instead. 967 */ 968 virtual void setVariableTop(uint32_t varTop, UErrorCode &status) = 0; 969 #endif // U_FORCE_HIDE_DEPRECATED_API 970 971 /** 972 * Gets the variable top value of a Collator. 973 * @param status error code (not changed by function). If error code is set, the return value is undefined. 974 * @return the variable top primary weight 975 * @see getMaxVariable 976 * @stable ICU 2.0 977 */ 978 virtual uint32_t getVariableTop(UErrorCode &status) const = 0; 979 980 /** 981 * Get a UnicodeSet that contains all the characters and sequences 982 * tailored in this collator. 983 * @param status error code of the operation 984 * @return a pointer to a UnicodeSet object containing all the 985 * code points and sequences that may sort differently than 986 * in the root collator. The object must be disposed of by using delete 987 * @stable ICU 2.4 988 */ 989 virtual UnicodeSet *getTailoredSet(UErrorCode &status) const; 990 991 #ifndef U_FORCE_HIDE_DEPRECATED_API 992 /** 993 * Same as clone(). 994 * The base class implementation simply calls clone(). 995 * @return a copy of this object, owned by the caller 996 * @see clone() 997 * @deprecated ICU 50 no need to have two methods for cloning 998 */ 999 virtual Collator* safeClone() const; 1000 #endif // U_FORCE_HIDE_DEPRECATED_API 1001 1002 /** 1003 * Get the sort key as an array of bytes from a UnicodeString. 1004 * Sort key byte arrays are zero-terminated and can be compared using 1005 * strcmp(). 1006 * 1007 * Note that sort keys are often less efficient than simply doing comparison. 1008 * For more details, see the ICU User Guide. 1009 * 1010 * @param source string to be processed. 1011 * @param result buffer to store result in. If nullptr, number of bytes needed 1012 * will be returned. 1013 * @param resultLength length of the result buffer. If if not enough the 1014 * buffer will be filled to capacity. 1015 * @return Number of bytes needed for storing the sort key 1016 * @stable ICU 2.2 1017 */ 1018 virtual int32_t getSortKey(const UnicodeString& source, 1019 uint8_t* result, 1020 int32_t resultLength) const = 0; 1021 1022 /** 1023 * Get the sort key as an array of bytes from a char16_t buffer. 1024 * Sort key byte arrays are zero-terminated and can be compared using 1025 * strcmp(). 1026 * 1027 * Note that sort keys are often less efficient than simply doing comparison. 1028 * For more details, see the ICU User Guide. 1029 * 1030 * @param source string to be processed. 1031 * @param sourceLength length of string to be processed. 1032 * If -1, the string is 0 terminated and length will be decided by the 1033 * function. 1034 * @param result buffer to store result in. If nullptr, number of bytes needed 1035 * will be returned. 1036 * @param resultLength length of the result buffer. If if not enough the 1037 * buffer will be filled to capacity. 1038 * @return Number of bytes needed for storing the sort key 1039 * @stable ICU 2.2 1040 */ 1041 virtual int32_t getSortKey(const char16_t*source, int32_t sourceLength, 1042 uint8_t*result, int32_t resultLength) const = 0; 1043 1044 /** 1045 * Produce a bound for a given sortkey and a number of levels. 1046 * Return value is always the number of bytes needed, regardless of 1047 * whether the result buffer was big enough or even valid.<br> 1048 * Resulting bounds can be used to produce a range of strings that are 1049 * between upper and lower bounds. For example, if bounds are produced 1050 * for a sortkey of string "smith", strings between upper and lower 1051 * bounds with one level would include "Smith", "SMITH", "sMiTh".<br> 1052 * There are two upper bounds that can be produced. If UCOL_BOUND_UPPER 1053 * is produced, strings matched would be as above. However, if bound 1054 * produced using UCOL_BOUND_UPPER_LONG is used, the above example will 1055 * also match "Smithsonian" and similar.<br> 1056 * For more on usage, see example in cintltst/capitst.c in procedure 1057 * TestBounds. 1058 * Sort keys may be compared using <TT>strcmp</TT>. 1059 * @param source The source sortkey. 1060 * @param sourceLength The length of source, or -1 if null-terminated. 1061 * (If an unmodified sortkey is passed, it is always null 1062 * terminated). 1063 * @param boundType Type of bound required. It can be UCOL_BOUND_LOWER, which 1064 * produces a lower inclusive bound, UCOL_BOUND_UPPER, that 1065 * produces upper bound that matches strings of the same length 1066 * or UCOL_BOUND_UPPER_LONG that matches strings that have the 1067 * same starting substring as the source string. 1068 * @param noOfLevels Number of levels required in the resulting bound (for most 1069 * uses, the recommended value is 1). See users guide for 1070 * explanation on number of levels a sortkey can have. 1071 * @param result A pointer to a buffer to receive the resulting sortkey. 1072 * @param resultLength The maximum size of result. 1073 * @param status Used for returning error code if something went wrong. If the 1074 * number of levels requested is higher than the number of levels 1075 * in the source key, a warning (U_SORT_KEY_TOO_SHORT_WARNING) is 1076 * issued. 1077 * @return The size needed to fully store the bound. 1078 * @see ucol_keyHashCode 1079 * @stable ICU 2.1 1080 */ 1081 static int32_t U_EXPORT2 getBound(const uint8_t *source, 1082 int32_t sourceLength, 1083 UColBoundMode boundType, 1084 uint32_t noOfLevels, 1085 uint8_t *result, 1086 int32_t resultLength, 1087 UErrorCode &status); 1088 1089 1090 protected: 1091 1092 // Collator protected constructors ------------------------------------- 1093 1094 /** 1095 * Default constructor. 1096 * Constructor is different from the old default Collator constructor. 1097 * The task for determining the default collation strength and normalization 1098 * mode is left to the child class. 1099 * @stable ICU 2.0 1100 */ 1101 Collator(); 1102 1103 #ifndef U_HIDE_DEPRECATED_API 1104 /** 1105 * Constructor. 1106 * Empty constructor, does not handle the arguments. 1107 * This constructor is done for backward compatibility with 1.7 and 1.8. 1108 * The task for handling the argument collation strength and normalization 1109 * mode is left to the child class. 1110 * @param collationStrength collation strength 1111 * @param decompositionMode 1112 * @deprecated ICU 2.4. Subclasses should use the default constructor 1113 * instead and handle the strength and normalization mode themselves. 1114 */ 1115 Collator(UCollationStrength collationStrength, 1116 UNormalizationMode decompositionMode); 1117 #endif /* U_HIDE_DEPRECATED_API */ 1118 1119 /** 1120 * Copy constructor. 1121 * @param other Collator object to be copied from 1122 * @stable ICU 2.0 1123 */ 1124 Collator(const Collator& other); 1125 1126 public: 1127 /** 1128 * Used internally by registration to define the requested and valid locales. 1129 * @param requestedLocale the requested locale 1130 * @param validLocale the valid locale 1131 * @param actualLocale the actual locale 1132 * @internal 1133 */ 1134 virtual void setLocales(const Locale& requestedLocale, const Locale& validLocale, const Locale& actualLocale); 1135 1136 /** Get the short definition string for a collator. This internal API harvests the collator's 1137 * locale and the attribute set and produces a string that can be used for opening 1138 * a collator with the same attributes using the ucol_openFromShortString API. 1139 * This string will be normalized. 1140 * The structure and the syntax of the string is defined in the "Naming collators" 1141 * section of the users guide: 1142 * https://unicode-org.github.io/icu/userguide/collation/concepts#collator-naming-scheme 1143 * This function supports preflighting. 1144 * 1145 * This is internal, and intended to be used with delegate converters. 1146 * 1147 * @param locale a locale that will appear as a collators locale in the resulting 1148 * short string definition. If nullptr, the locale will be harvested 1149 * from the collator. 1150 * @param buffer space to hold the resulting string 1151 * @param capacity capacity of the buffer 1152 * @param status for returning errors. All the preflighting errors are featured 1153 * @return length of the resulting string 1154 * @see ucol_openFromShortString 1155 * @see ucol_normalizeShortDefinitionString 1156 * @see ucol_getShortDefinitionString 1157 * @internal 1158 */ 1159 virtual int32_t internalGetShortDefinitionString(const char *locale, 1160 char *buffer, 1161 int32_t capacity, 1162 UErrorCode &status) const; 1163 1164 /** 1165 * Implements ucol_strcollUTF8(). 1166 * @internal 1167 */ 1168 virtual UCollationResult internalCompareUTF8( 1169 const char *left, int32_t leftLength, 1170 const char *right, int32_t rightLength, 1171 UErrorCode &errorCode) const; 1172 1173 /** 1174 * Implements ucol_nextSortKeyPart(). 1175 * @internal 1176 */ 1177 virtual int32_t 1178 internalNextSortKeyPart( 1179 UCharIterator *iter, uint32_t state[2], 1180 uint8_t *dest, int32_t count, UErrorCode &errorCode) const; 1181 1182 #ifndef U_HIDE_INTERNAL_API 1183 /** @internal */ 1184 static inline Collator *fromUCollator(UCollator *uc) { 1185 return reinterpret_cast<Collator *>(uc); 1186 } 1187 /** @internal */ 1188 static inline const Collator *fromUCollator(const UCollator *uc) { 1189 return reinterpret_cast<const Collator *>(uc); 1190 } 1191 /** @internal */ 1192 inline UCollator *toUCollator() { 1193 return reinterpret_cast<UCollator *>(this); 1194 } 1195 /** @internal */ 1196 inline const UCollator *toUCollator() const { 1197 return reinterpret_cast<const UCollator *>(this); 1198 } 1199 #endif // U_HIDE_INTERNAL_API 1200 1201 private: 1202 /** 1203 * Assignment operator. Private for now. 1204 */ 1205 Collator& operator=(const Collator& other) = delete; 1206 1207 friend class CFactory; 1208 friend class SimpleCFactory; 1209 friend class ICUCollatorFactory; 1210 friend class ICUCollatorService; 1211 static Collator* makeInstance(const Locale& desiredLocale, 1212 UErrorCode& status); 1213 }; 1214 1215 #if !UCONFIG_NO_SERVICE 1216 /** 1217 * A factory, used with registerFactory, the creates multiple collators and provides 1218 * display names for them. A factory supports some number of locales-- these are the 1219 * locales for which it can create collators. The factory can be visible, in which 1220 * case the supported locales will be enumerated by getAvailableLocales, or invisible, 1221 * in which they are not. Invisible locales are still supported, they are just not 1222 * listed by getAvailableLocales. 1223 * <p> 1224 * If standard locale display names are sufficient, Collator instances can 1225 * be registered using registerInstance instead.</p> 1226 * <p> 1227 * Note: if the collators are to be used from C APIs, they must be instances 1228 * of RuleBasedCollator.</p> 1229 * 1230 * @stable ICU 2.6 1231 */ 1232 class U_I18N_API CollatorFactory : public UObject { 1233 public: 1234 1235 /** 1236 * Destructor 1237 * @stable ICU 3.0 1238 */ 1239 virtual ~CollatorFactory(); 1240 1241 /** 1242 * Return true if this factory is visible. Default is true. 1243 * If not visible, the locales supported by this factory will not 1244 * be listed by getAvailableLocales. 1245 * @return true if the factory is visible. 1246 * @stable ICU 2.6 1247 */ 1248 virtual UBool visible(void) const; 1249 1250 /** 1251 * Return a collator for the provided locale. If the locale 1252 * is not supported, return nullptr. 1253 * @param loc the locale identifying the collator to be created. 1254 * @return a new collator if the locale is supported, otherwise nullptr. 1255 * @stable ICU 2.6 1256 */ 1257 virtual Collator* createCollator(const Locale& loc) = 0; 1258 1259 /** 1260 * Return the name of the collator for the objectLocale, localized for the displayLocale. 1261 * If objectLocale is not supported, or the factory is not visible, set the result string 1262 * to bogus. 1263 * @param objectLocale the locale identifying the collator 1264 * @param displayLocale the locale for which the display name of the collator should be localized 1265 * @param result an output parameter for the display name, set to bogus if not supported. 1266 * @return the display name 1267 * @stable ICU 2.6 1268 */ 1269 virtual UnicodeString& getDisplayName(const Locale& objectLocale, 1270 const Locale& displayLocale, 1271 UnicodeString& result); 1272 1273 /** 1274 * Return an array of all the locale names directly supported by this factory. 1275 * The number of names is returned in count. This array is owned by the factory. 1276 * Its contents must never change. 1277 * @param count output parameter for the number of locales supported by the factory 1278 * @param status the in/out error code 1279 * @return a pointer to an array of count UnicodeStrings. 1280 * @stable ICU 2.6 1281 */ 1282 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) = 0; 1283 }; 1284 #endif /* UCONFIG_NO_SERVICE */ 1285 1286 // Collator inline methods ----------------------------------------------- 1287 1288 U_NAMESPACE_END 1289 1290 #endif /* #if !UCONFIG_NO_COLLATION */ 1291 1292 #endif /* U_SHOW_CPLUSPLUS_API */ 1293 1294 #endif
Contact us
|
About us
|
Term of use
|
Copyright © 2000-2025 MyWebUniversity.com ™
