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