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