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