1 /* 2 ****************************************************************************** 3 * Copyright (C) 1996-2007, International Business Machines * 4 * Corporation and others. All Rights Reserved. * 5 ****************************************************************************** 6 */ 7 8 /** 9 * File coll.h 10 * 11 * Created by: Helena Shih 12 * 13 * Modification History: 14 * 15 * Date Name Description 16 * 02/5/97 aliu Modified createDefault to load collation data from 17 * binary files when possible. Added related methods 18 * createCollationFromFile, chopLocale, createPathName. 19 * 02/11/97 aliu Added members addToCache, findInCache, and fgCache. 20 * 02/12/97 aliu Modified to create objects from RuleBasedCollator cache. 21 * Moved cache out of Collation class. 22 * 02/13/97 aliu Moved several methods out of this class and into 23 * RuleBasedCollator, with modifications. Modified 24 * createDefault() to call new RuleBasedCollator(Locale&) 25 * constructor. General clean up and documentation. 26 * 02/20/97 helena Added clone, operator==, operator!=, operator=, copy 27 * constructor and getDynamicClassID. 28 * 03/25/97 helena Updated with platform independent data types. 29 * 05/06/97 helena Added memory allocation error detection. 30 * 06/20/97 helena Java class name change. 31 * 09/03/97 helena Added createCollationKeyValues(). 32 * 02/10/98 damiba Added compare() with length as parameter. 33 * 04/23/99 stephen Removed EDecompositionMode, merged with 34 * Normalizer::EMode. 35 * 11/02/99 helena Collator performance enhancements. Eliminates the 36 * UnicodeString construction and special case for NO_OP. 37 * 11/23/99 srl More performance enhancements. Inlining of 38 * critical accessors. 39 * 05/15/00 helena Added version information API. 40 * 01/29/01 synwee Modified into a C++ wrapper which calls C apis 41 * (ucoll.h). 42 */ 43 44 #ifndef COLL_H 45 #define COLL_H 46 47 #include "unicode/utypes.h" 48 49 /** 50 * \file 51 * \brief C++ API: Collation Service. 52 */ 53 54 #if !UCONFIG_NO_COLLATION 55 56 #include "unicode/uobject.h" 57 #include "unicode/ucol.h" 58 #include "unicode/normlzr.h" 59 #include "unicode/locid.h" 60 #include "unicode/uniset.h" 61 #include "unicode/umisc.h" 62 63 U_NAMESPACE_BEGIN 64 65 class StringEnumeration; 66 67 #if !UCONFIG_NO_SERVICE 68 /** 69 * @stable ICU 2.6 70 */ 71 class CollatorFactory; 72 #endif 73 74 /** 75 * @stable ICU 2.0 76 */ 77 class CollationKey; 78 79 /** 80 * The <code>Collator</code> class performs locale-sensitive string 81 * comparison.<br> 82 * You use this class to build searching and sorting routines for natural 83 * language text.<br> 84 * <em>Important: </em>The ICU collation service has been reimplemented 85 * in order to achieve better performance and UCA compliance. 86 * For details, see the 87 * <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/collation/ICU_collation_design.htm"> 88 * collation design document</a>. 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> property 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 dependant. 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::US, 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 * <p> 141 * For comparing strings exactly once, the <code>compare</code> method 142 * provides the best performance. When sorting a list of strings however, it 143 * is generally necessary to compare each string multiple times. In this case, 144 * sort keys provide better performance. The <code>getSortKey</code> methods 145 * convert a string to a series of bytes that can be compared bitwise against 146 * other sort keys using <code>strcmp()</code>. Sort keys are written as 147 * zero-terminated byte strings. They consist of several substrings, one for 148 * each collation strength level, that are delimited by 0x01 bytes. 149 * If the string code points are appended for UCOL_IDENTICAL, then they are 150 * processed for correct code point order comparison and may contain 0x01 151 * bytes but not zero bytes. 152 * </p> 153 * <p> 154 * An older set of APIs returns a <code>CollationKey</code> object that wraps 155 * the sort key bytes instead of returning the bytes themselves. 156 * Its use is deprecated, but it is still available for compatibility with 157 * Java. 158 * </p> 159 * <p> 160 * <strong>Note:</strong> <code>Collator</code>s with different Locale, 161 * and CollationStrength settings will return different sort 162 * orders for the same set of strings. Locales have specific collation rules, 163 * and the way in which secondary and tertiary differences are taken into 164 * account, for example, will result in a different sorting order for same 165 * strings. 166 * </p> 167 * @see RuleBasedCollator 168 * @see CollationKey 169 * @see CollationElementIterator 170 * @see Locale 171 * @see Normalizer 172 * @version 2.0 11/15/01 173 */ 174 175 class U_I18N_API Collator : public UObject { 176 public: 177 178 // Collator public enums ----------------------------------------------- 179 180 /** 181 * Base letter represents a primary difference. Set comparison level to 182 * PRIMARY to ignore secondary and tertiary differences.<br> 183 * Use this to set the strength of a Collator object.<br> 184 * Example of primary difference, "abc" < "abd" 185 * 186 * Diacritical differences on the same base letter represent a secondary 187 * difference. Set comparison level to SECONDARY to ignore tertiary 188 * differences. Use this to set the strength of a Collator object.<br> 189 * Example of secondary difference, "ä" >> "a". 190 * 191 * Uppercase and lowercase versions of the same character represents a 192 * tertiary difference. Set comparison level to TERTIARY to include all 193 * comparison differences. Use this to set the strength of a Collator 194 * object.<br> 195 * Example of tertiary difference, "abc" <<< "ABC". 196 * 197 * Two characters are considered "identical" when they have the same unicode 198 * spellings.<br> 199 * For example, "ä" == "ä". 200 * 201 * UCollationStrength is also used to determine the strength of sort keys 202 * generated from Collator objects. 203 * @stable ICU 2.0 204 */ 205 enum ECollationStrength 206 { 207 PRIMARY = 0, 208 SECONDARY = 1, 209 TERTIARY = 2, 210 QUATERNARY = 3, 211 IDENTICAL = 15 212 }; 213 214 /** 215 * LESS is returned if source string is compared to be less than target 216 * string in the compare() method. 217 * EQUAL is returned if source string is compared to be equal to target 218 * string in the compare() method. 219 * GREATER is returned if source string is compared to be greater than 220 * target string in the compare() method. 221 * @see Collator#compare 222 * @deprecated ICU 2.6. Use C enum UCollationResult defined in ucol.h 223 */ 224 enum EComparisonResult 225 { 226 LESS = -1, 227 EQUAL = 0, 228 GREATER = 1 229 }; 230 231 // Collator public destructor ----------------------------------------- 232 233 /** 234 * Destructor 235 * @stable ICU 2.0 236 */ 237 virtual ~Collator(); 238 239 // Collator public methods -------------------------------------------- 240 241 /** 242 * Returns true if "other" is the same as "this" 243 * @param other Collator object to be compared 244 * @return true if other is the same as this. 245 * @stable ICU 2.0 246 */ 247 virtual UBool operator==(const Collator& other) const; 248 249 /** 250 * Returns true if "other" is not the same as "this". 251 * @param other Collator object to be compared 252 * @return true if other is not the same as this. 253 * @stable ICU 2.0 254 */ 255 virtual UBool operator!=(const Collator& other) const; 256 257 /** 258 * Makes a shallow copy of the current object. 259 * @return a copy of this object 260 * @stable ICU 2.0 261 */ 262 virtual Collator* clone(void) const = 0; 263 264 /** 265 * Creates the Collator object for the current default locale. 266 * The default locale is determined by Locale::getDefault. 267 * The UErrorCode& err parameter is used to return status information to the user. 268 * To check whether the construction succeeded or not, you should check the 269 * value of U_SUCCESS(err). If you wish more detailed information, you can 270 * check for informational error results which still indicate success. 271 * U_USING_FALLBACK_ERROR indicates that a fall back locale was used. For 272 * example, 'de_CH' was requested, but nothing was found there, so 'de' was 273 * used. U_USING_DEFAULT_ERROR indicates that the default locale data was 274 * used; neither the requested locale nor any of its fall back locales 275 * could be found. 276 * The caller owns the returned object and is responsible for deleting it. 277 * 278 * @param err the error code status. 279 * @return the collation object of the default locale.(for example, en_US) 280 * @see Locale#getDefault 281 * @stable ICU 2.0 282 */ 283 static Collator* U_EXPORT2 createInstance(UErrorCode& err); 284 285 /** 286 * Gets the table-based collation object for the desired locale. The 287 * resource of the desired locale will be loaded by ResourceLoader. 288 * Locale::ENGLISH is the base collation table and all other languages are 289 * built on top of it with additional language-specific modifications. 290 * The UErrorCode& err parameter is used to return status information to the user. 291 * To check whether the construction succeeded or not, you should check 292 * the value of U_SUCCESS(err). If you wish more detailed information, you 293 * can check for informational error results which still indicate success. 294 * U_USING_FALLBACK_ERROR indicates that a fall back locale was used. For 295 * example, 'de_CH' was requested, but nothing was found there, so 'de' was 296 * used. U_USING_DEFAULT_ERROR indicates that the default locale data was 297 * used; neither the requested locale nor any of its fall back locales 298 * could be found. 299 * The caller owns the returned object and is responsible for deleting it. 300 * @param loc The locale ID for which to open a collator. 301 * @param err the error code status. 302 * @return the created table-based collation object based on the desired 303 * locale. 304 * @see Locale 305 * @see ResourceLoader 306 * @stable ICU 2.2 307 */ 308 static Collator* U_EXPORT2 createInstance(const Locale& loc, UErrorCode& err); 309 310 #ifdef U_USE_COLLATION_OBSOLETE_2_6 311 /** 312 * Create a Collator with a specific version. 313 * This is the same as createInstance(loc, err) except that getVersion() of 314 * the returned object is guaranteed to be the same as the version 315 * parameter. 316 * This is designed to be used to open the same collator for a given 317 * locale even when ICU is updated. 318 * The same locale and version guarantees the same sort keys and 319 * comparison results. 320 * <p> 321 * Note: this API will be removed in a future release. Use 322 * <tt>createInstance(const Locale&, UErrorCode&) instead.</tt></p> 323 * 324 * @param loc The locale ID for which to open a collator. 325 * @param version The requested collator version. 326 * @param err A reference to a UErrorCode, 327 * must not indicate a failure before calling this function. 328 * @return A pointer to a Collator, or 0 if an error occurred 329 * or a collator with the requested version is not available. 330 * 331 * @see getVersion 332 * @obsolete ICU 2.6 333 */ 334 static Collator *createInstance(const Locale &loc, UVersionInfo version, UErrorCode &err); 335 #endif 336 337 /** 338 * The comparison function compares the character data stored in two 339 * different strings. Returns information about whether a string is less 340 * than, greater than or equal to another string. 341 * @param source the source string to be compared with. 342 * @param target the string that is to be compared with the source string. 343 * @return Returns a byte value. GREATER if source is greater 344 * than target; EQUAL if source is equal to target; LESS if source is less 345 * than target 346 * @deprecated ICU 2.6 use the overload with UErrorCode & 347 */ 348 virtual EComparisonResult compare(const UnicodeString& source, 349 const UnicodeString& target) const; 350 351 /** 352 * The comparison function compares the character data stored in two 353 * different strings. Returns information about whether a string is less 354 * than, greater than or equal to another string. 355 * @param source the source string to be compared with. 356 * @param target the string that is to be compared with the source string. 357 * @param status possible error code 358 * @return Returns an enum value. UCOL_GREATER if source is greater 359 * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less 360 * than target 361 * @stable ICU 2.6 362 */ 363 virtual UCollationResult compare(const UnicodeString& source, 364 const UnicodeString& target, 365 UErrorCode &status) const = 0; 366 367 /** 368 * Does the same thing as compare but limits the comparison to a specified 369 * length 370 * @param source the source string to be compared with. 371 * @param target the string that is to be compared with the source string. 372 * @param length the length the comparison is limited to 373 * @return Returns a byte value. GREATER if source (up to the specified 374 * length) is greater than target; EQUAL if source (up to specified 375 * length) is equal to target; LESS if source (up to the specified 376 * length) is less than target. 377 * @deprecated ICU 2.6 use the overload with UErrorCode & 378 */ 379 virtual EComparisonResult compare(const UnicodeString& source, 380 const UnicodeString& target, 381 int32_t length) const; 382 383 /** 384 * Does the same thing as compare but limits the comparison to a specified 385 * length 386 * @param source the source string to be compared with. 387 * @param target the string that is to be compared with the source string. 388 * @param length the length the comparison is limited to 389 * @param status possible error code 390 * @return Returns an enum value. UCOL_GREATER if source (up to the specified 391 * length) is greater than target; UCOL_EQUAL if source (up to specified 392 * length) is equal to target; UCOL_LESS if source (up to the specified 393 * length) is less than target. 394 * @stable ICU 2.6 395 */ 396 virtual UCollationResult compare(const UnicodeString& source, 397 const UnicodeString& target, 398 int32_t length, 399 UErrorCode &status) const = 0; 400 401 /** 402 * The comparison function compares the character data stored in two 403 * different string arrays. Returns information about whether a string array 404 * is less than, greater than or equal to another string array. 405 * @param source the source string array to be compared with. 406 * @param sourceLength the length of the source string array. If this value 407 * is equal to -1, the string array is null-terminated. 408 * @param target the string that is to be compared with the source string. 409 * @param targetLength the length of the target string array. If this value 410 * is equal to -1, the string array is null-terminated. 411 * @return Returns a byte value. GREATER if source is greater than target; 412 * EQUAL if source is equal to target; LESS if source is less than 413 * target 414 * @deprecated ICU 2.6 use the overload with UErrorCode & 415 */ 416 virtual EComparisonResult compare(const UChar* source, int32_t sourceLength, 417 const UChar* target, int32_t targetLength) 418 const; 419 420 /** 421 * The comparison function compares the character data stored in two 422 * different string arrays. Returns information about whether a string array 423 * is less than, greater than or equal to another string array. 424 * @param source the source string array to be compared with. 425 * @param sourceLength the length of the source string array. If this value 426 * is equal to -1, the string array is null-terminated. 427 * @param target the string that is to be compared with the source string. 428 * @param targetLength the length of the target string array. If this value 429 * is equal to -1, the string array is null-terminated. 430 * @param status possible error code 431 * @return Returns an enum value. UCOL_GREATER if source is greater 432 * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less 433 * than target 434 * @stable ICU 2.6 435 */ 436 virtual UCollationResult compare(const UChar* source, int32_t sourceLength, 437 const UChar* target, int32_t targetLength, 438 UErrorCode &status) const = 0; 439 440 /** 441 * Transforms the string into a series of characters that can be compared 442 * with CollationKey::compareTo. It is not possible to restore the original 443 * string from the chars in the sort key. The generated sort key handles 444 * only a limited number of ignorable characters. 445 * <p>Use CollationKey::equals or CollationKey::compare to compare the 446 * generated sort keys. 447 * If the source string is null, a null collation key will be returned. 448 * @param source the source string to be transformed into a sort key. 449 * @param key the collation key to be filled in 450 * @param status the error code status. 451 * @return the collation key of the string based on the collation rules. 452 * @see CollationKey#compare 453 * @deprecated ICU 2.8 Use getSortKey(...) instead 454 */ 455 virtual CollationKey& getCollationKey(const UnicodeString& source, 456 CollationKey& key, 457 UErrorCode& status) const = 0; 458 459 /** 460 * Transforms the string into a series of characters that can be compared 461 * with CollationKey::compareTo. It is not possible to restore the original 462 * string from the chars in the sort key. The generated sort key handles 463 * only a limited number of ignorable characters. 464 * <p>Use CollationKey::equals or CollationKey::compare to compare the 465 * generated sort keys. 466 * <p>If the source string is null, a null collation key will be returned. 467 * @param source the source string to be transformed into a sort key. 468 * @param sourceLength length of the collation key 469 * @param key the collation key to be filled in 470 * @param status the error code status. 471 * @return the collation key of the string based on the collation rules. 472 * @see CollationKey#compare 473 * @deprecated ICU 2.8 Use getSortKey(...) instead 474 */ 475 virtual CollationKey& getCollationKey(const UChar*source, 476 int32_t sourceLength, 477 CollationKey& key, 478 UErrorCode& status) const = 0; 479 /** 480 * Generates the hash code for the collation object 481 * @stable ICU 2.0 482 */ 483 virtual int32_t hashCode(void) const = 0; 484 485 /** 486 * Gets the locale of the Collator 487 * 488 * @param type can be either requested, valid or actual locale. For more 489 * information see the definition of ULocDataLocaleType in 490 * uloc.h 491 * @param status the error code status. 492 * @return locale where the collation data lives. If the collator 493 * was instantiated from rules, locale is empty. 494 * @deprecated ICU 2.8 This API is under consideration for revision 495 * in ICU 3.0. 496 */ 497 virtual const Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const = 0; 498 499 /** 500 * Convenience method for comparing two strings based on the collation rules. 501 * @param source the source string to be compared with. 502 * @param target the target string to be compared with. 503 * @return true if the first string is greater than the second one, 504 * according to the collation rules. false, otherwise. 505 * @see Collator#compare 506 * @stable ICU 2.0 507 */ 508 UBool greater(const UnicodeString& source, const UnicodeString& target) 509 const; 510 511 /** 512 * Convenience method for comparing two strings based on the collation rules. 513 * @param source the source string to be compared with. 514 * @param target the target string to be compared with. 515 * @return true if the first string is greater than or equal to the second 516 * one, according to the collation rules. false, otherwise. 517 * @see Collator#compare 518 * @stable ICU 2.0 519 */ 520 UBool greaterOrEqual(const UnicodeString& source, 521 const UnicodeString& target) const; 522 523 /** 524 * Convenience method for comparing two strings based on the collation rules. 525 * @param source the source string to be compared with. 526 * @param target the target string to be compared with. 527 * @return true if the strings are equal according to the collation rules. 528 * false, otherwise. 529 * @see Collator#compare 530 * @stable ICU 2.0 531 */ 532 UBool equals(const UnicodeString& source, const UnicodeString& target) const; 533 534 /** 535 * Determines the minimum strength that will be use in comparison or 536 * transformation. 537 * <p>E.g. with strength == SECONDARY, the tertiary difference is ignored 538 * <p>E.g. with strength == PRIMARY, the secondary and tertiary difference 539 * are ignored. 540 * @return the current comparison level. 541 * @see Collator#setStrength 542 * @deprecated ICU 2.6 Use getAttribute(UCOL_STRENGTH...) instead 543 */ 544 virtual ECollationStrength getStrength(void) const = 0; 545 546 /** 547 * Sets the minimum strength to be used in comparison or transformation. 548 * <p>Example of use: 549 * <pre> 550 * \code 551 * UErrorCode status = U_ZERO_ERROR; 552 * Collator*myCollation = Collator::createInstance(Locale::US, status); 553 * if (U_FAILURE(status)) return; 554 * myCollation->setStrength(Collator::PRIMARY); 555 * // result will be "abc" == "ABC" 556 * // tertiary differences will be ignored 557 * Collator::ComparisonResult result = myCollation->compare("abc", "ABC"); 558 * \endcode 559 * </pre> 560 * @see Collator#getStrength 561 * @param newStrength the new comparison level. 562 * @deprecated ICU 2.6 Use setAttribute(UCOL_STRENGTH...) instead 563 */ 564 virtual void setStrength(ECollationStrength newStrength) = 0; 565 566 /** 567 * Get name of the object for the desired Locale, in the desired langauge 568 * @param objectLocale must be from getAvailableLocales 569 * @param displayLocale specifies the desired locale for output 570 * @param name the fill-in parameter of the return value 571 * @return display-able name of the object for the object locale in the 572 * desired language 573 * @stable ICU 2.0 574 */ 575 static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale, 576 const Locale& displayLocale, 577 UnicodeString& name); 578 579 /** 580 * Get name of the object for the desired Locale, in the langauge of the 581 * default locale. 582 * @param objectLocale must be from getAvailableLocales 583 * @param name the fill-in parameter of the return value 584 * @return name of the object for the desired locale in the default language 585 * @stable ICU 2.0 586 */ 587 static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale, 588 UnicodeString& name); 589 590 /** 591 * Get the set of Locales for which Collations are installed. 592 * 593 * <p>Note this does not include locales supported by registered collators. 594 * If collators might have been registered, use the overload of getAvailableLocales 595 * that returns a StringEnumeration.</p> 596 * 597 * @param count the output parameter of number of elements in the locale list 598 * @return the list of available locales for which collations are installed 599 * @stable ICU 2.0 600 */ 601 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count); 602 603 /** 604 * Return a StringEnumeration over the locales available at the time of the call, 605 * including registered locales. If a severe error occurs (such as out of memory 606 * condition) this will return null. If there is no locale data, an empty enumeration 607 * will be returned. 608 * @return a StringEnumeration over the locales available at the time of the call 609 * @stable ICU 2.6 610 */ 611 static StringEnumeration* U_EXPORT2 getAvailableLocales(void); 612 613 /** 614 * Create a string enumerator of all possible keywords that are relevant to 615 * collation. At this point, the only recognized keyword for this 616 * service is "collation". 617 * @param status input-output error code 618 * @return a string enumeration over locale strings. The caller is 619 * responsible for closing the result. 620 * @stable ICU 3.0 621 */ 622 static StringEnumeration* U_EXPORT2 getKeywords(UErrorCode& status); 623 624 /** 625 * Given a keyword, create a string enumeration of all values 626 * for that keyword that are currently in use. 627 * @param keyword a particular keyword as enumerated by 628 * ucol_getKeywords. If any other keyword is passed in, status is set 629 * to U_ILLEGAL_ARGUMENT_ERROR. 630 * @param status input-output error code 631 * @return a string enumeration over collation keyword values, or NULL 632 * upon error. The caller is responsible for deleting the result. 633 * @stable ICU 3.0 634 */ 635 static StringEnumeration* U_EXPORT2 getKeywordValues(const char *keyword, UErrorCode& status); 636 637 /** 638 * Return the functionally equivalent locale for the given 639 * requested locale, with respect to given keyword, for the 640 * collation service. If two locales return the same result, then 641 * collators instantiated for these locales will behave 642 * equivalently. The converse is not always true; two collators 643 * may in fact be equivalent, but return different results, due to 644 * internal details. The return result has no other meaning than 645 * that stated above, and implies nothing as to the relationship 646 * between the two locales. This is intended for use by 647 * applications who wish to cache collators, or otherwise reuse 648 * collators when possible. The functional equivalent may change 649 * over time. For more information, please see the <a 650 * href="http://icu-project.org/userguide/locale.html#services"> 651 * Locales and Services</a> section of the ICU User Guide. 652 * @param keyword a particular keyword as enumerated by 653 * ucol_getKeywords. 654 * @param locale the requested locale 655 * @param isAvailable reference to a fillin parameter that 656 * indicates whether the requested locale was 'available' to the 657 * collation service. A locale is defined as 'available' if it 658 * physically exists within the collation locale data. 659 * @param status reference to input-output error code 660 * @return the functionally equivalent collation locale, or the root 661 * locale upon error. 662 * @stable ICU 3.0 663 */ 664 static Locale U_EXPORT2 getFunctionalEquivalent(const char* keyword, const Locale& locale, 665 UBool& isAvailable, UErrorCode& status); 666 667 #if !UCONFIG_NO_SERVICE 668 /** 669 * Register a new Collator. The collator will be adopted. 670 * @param toAdopt the Collator instance to be adopted 671 * @param locale the locale with which the collator will be associated 672 * @param status the in/out status code, no special meanings are assigned 673 * @return a registry key that can be used to unregister this collator 674 * @stable ICU 2.6 675 */ 676 static URegistryKey U_EXPORT2 registerInstance(Collator* toAdopt, const Locale& locale, UErrorCode& status); 677 678 /** 679 * Register a new CollatorFactory. The factory will be adopted. 680 * @param toAdopt the CollatorFactory instance to be adopted 681 * @param status the in/out status code, no special meanings are assigned 682 * @return a registry key that can be used to unregister this collator 683 * @stable ICU 2.6 684 */ 685 static URegistryKey U_EXPORT2 registerFactory(CollatorFactory* toAdopt, UErrorCode& status); 686 687 /** 688 * Unregister a previously-registered Collator or CollatorFactory 689 * using the key returned from the register call. Key becomes 690 * invalid after a successful call and should not be used again. 691 * The object corresponding to the key will be deleted. 692 * @param key the registry key returned by a previous call to registerInstance 693 * @param status the in/out status code, no special meanings are assigned 694 * @return TRUE if the collator for the key was successfully unregistered 695 * @stable ICU 2.6 696 */ 697 static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status); 698 #endif /* UCONFIG_NO_SERVICE */ 699 700 /** 701 * Gets the version information for a Collator. 702 * @param info the version # information, the result will be filled in 703 * @stable ICU 2.0 704 */ 705 virtual void getVersion(UVersionInfo info) const = 0; 706 707 /** 708 * Returns a unique class ID POLYMORPHICALLY. Pure virtual method. 709 * This method is to implement a simple version of RTTI, since not all C++ 710 * compilers support genuine RTTI. Polymorphic operator==() and clone() 711 * methods call this method. 712 * @return The class ID for this object. All objects of a given class have 713 * the same class ID. Objects of other classes have different class 714 * IDs. 715 * @stable ICU 2.0 716 */ 717 virtual UClassID getDynamicClassID(void) const = 0; 718 719 /** 720 * Universal attribute setter 721 * @param attr attribute type 722 * @param value attribute value 723 * @param status to indicate whether the operation went on smoothly or 724 * there were errors 725 * @stable ICU 2.2 726 */ 727 virtual void setAttribute(UColAttribute attr, UColAttributeValue value, 728 UErrorCode &status) = 0; 729 730 /** 731 * Universal attribute getter 732 * @param attr attribute type 733 * @param status to indicate whether the operation went on smoothly or 734 * there were errors 735 * @return attribute value 736 * @stable ICU 2.2 737 */ 738 virtual UColAttributeValue getAttribute(UColAttribute attr, 739 UErrorCode &status) = 0; 740 741 /** 742 * Sets the variable top to a collation element value of a string supplied. 743 * @param varTop one or more (if contraction) UChars to which the variable top should be set 744 * @param len length of variable top string. If -1 it is considered to be zero terminated. 745 * @param status error code. If error code is set, the return value is undefined. Errors set by this function are: <br> 746 * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such a contraction<br> 747 * U_PRIMARY_TOO_LONG_ERROR if the primary for the variable top has more than two bytes 748 * @return a 32 bit value containing the value of the variable top in upper 16 bits. Lower 16 bits are undefined 749 * @stable ICU 2.0 750 */ 751 virtual uint32_t setVariableTop(const UChar *varTop, int32_t len, UErrorCode &status) = 0; 752 753 /** 754 * Sets the variable top to a collation element value of a string supplied. 755 * @param varTop an UnicodeString size 1 or more (if contraction) of UChars to which the variable top should be set 756 * @param status error code. If error code is set, the return value is undefined. Errors set by this function are: <br> 757 * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such a contraction<br> 758 * U_PRIMARY_TOO_LONG_ERROR if the primary for the variable top has more than two bytes 759 * @return a 32 bit value containing the value of the variable top in upper 16 bits. Lower 16 bits are undefined 760 * @stable ICU 2.0 761 */ 762 virtual uint32_t setVariableTop(const UnicodeString varTop, UErrorCode &status) = 0; 763 764 /** 765 * Sets the variable top to a collation element value supplied. Variable top is set to the upper 16 bits. 766 * Lower 16 bits are ignored. 767 * @param varTop CE value, as returned by setVariableTop or ucol)getVariableTop 768 * @param status error code (not changed by function) 769 * @stable ICU 2.0 770 */ 771 virtual void setVariableTop(const uint32_t varTop, UErrorCode &status) = 0; 772 773 /** 774 * Gets the variable top value of a Collator. 775 * Lower 16 bits are undefined and should be ignored. 776 * @param status error code (not changed by function). If error code is set, the return value is undefined. 777 * @stable ICU 2.0 778 */ 779 virtual uint32_t getVariableTop(UErrorCode &status) const = 0; 780 781 /** 782 * Get an UnicodeSet that contains all the characters and sequences 783 * tailored in this collator. 784 * @param status error code of the operation 785 * @return a pointer to a UnicodeSet object containing all the 786 * code points and sequences that may sort differently than 787 * in the UCA. The object must be disposed of by using delete 788 * @stable ICU 2.4 789 */ 790 virtual UnicodeSet *getTailoredSet(UErrorCode &status) const; 791 792 793 /** 794 * Thread safe cloning operation 795 * @return pointer to the new clone, user should remove it. 796 * @stable ICU 2.2 797 */ 798 virtual Collator* safeClone(void) = 0; 799 800 /** 801 * Get the sort key as an array of bytes from an UnicodeString. 802 * Sort key byte arrays are zero-terminated and can be compared using 803 * strcmp(). 804 * @param source string to be processed. 805 * @param result buffer to store result in. If NULL, number of bytes needed 806 * will be returned. 807 * @param resultLength length of the result buffer. If if not enough the 808 * buffer will be filled to capacity. 809 * @return Number of bytes needed for storing the sort key 810 * @stable ICU 2.2 811 */ 812 virtual int32_t getSortKey(const UnicodeString& source, 813 uint8_t* result, 814 int32_t resultLength) const = 0; 815 816 /** 817 * Get the sort key as an array of bytes from an UChar buffer. 818 * Sort key byte arrays are zero-terminated and can be compared using 819 * strcmp(). 820 * @param source string to be processed. 821 * @param sourceLength length of string to be processed. 822 * If -1, the string is 0 terminated and length will be decided by the 823 * function. 824 * @param result buffer to store result in. If NULL, number of bytes needed 825 * will be returned. 826 * @param resultLength length of the result buffer. If if not enough the 827 * buffer will be filled to capacity. 828 * @return Number of bytes needed for storing the sort key 829 * @stable ICU 2.2 830 */ 831 virtual int32_t getSortKey(const UChar*source, int32_t sourceLength, 832 uint8_t*result, int32_t resultLength) const = 0; 833 834 /** 835 * Produce a bound for a given sortkey and a number of levels. 836 * Return value is always the number of bytes needed, regardless of 837 * whether the result buffer was big enough or even valid.<br> 838 * Resulting bounds can be used to produce a range of strings that are 839 * between upper and lower bounds. For example, if bounds are produced 840 * for a sortkey of string "smith", strings between upper and lower 841 * bounds with one level would include "Smith", "SMITH", "sMiTh".<br> 842 * There are two upper bounds that can be produced. If UCOL_BOUND_UPPER 843 * is produced, strings matched would be as above. However, if bound 844 * produced using UCOL_BOUND_UPPER_LONG is used, the above example will 845 * also match "Smithsonian" and similar.<br> 846 * For more on usage, see example in cintltst/capitst.c in procedure 847 * TestBounds. 848 * Sort keys may be compared using <TT>strcmp</TT>. 849 * @param source The source sortkey. 850 * @param sourceLength The length of source, or -1 if null-terminated. 851 * (If an unmodified sortkey is passed, it is always null 852 * terminated). 853 * @param boundType Type of bound required. It can be UCOL_BOUND_LOWER, which 854 * produces a lower inclusive bound, UCOL_BOUND_UPPER, that 855 * produces upper bound that matches strings of the same length 856 * or UCOL_BOUND_UPPER_LONG that matches strings that have the 857 * same starting substring as the source string. 858 * @param noOfLevels Number of levels required in the resulting bound (for most 859 * uses, the recommended value is 1). See users guide for 860 * explanation on number of levels a sortkey can have. 861 * @param result A pointer to a buffer to receive the resulting sortkey. 862 * @param resultLength The maximum size of result. 863 * @param status Used for returning error code if something went wrong. If the 864 * number of levels requested is higher than the number of levels 865 * in the source key, a warning (U_SORT_KEY_TOO_SHORT_WARNING) is 866 * issued. 867 * @return The size needed to fully store the bound. 868 * @see ucol_keyHashCode 869 * @stable ICU 2.1 870 */ 871 static int32_t U_EXPORT2 getBound(const uint8_t *source, 872 int32_t sourceLength, 873 UColBoundMode boundType, 874 uint32_t noOfLevels, 875 uint8_t *result, 876 int32_t resultLength, 877 UErrorCode &status); 878 879 880 protected: 881 882 // Collator protected constructors ------------------------------------- 883 884 /** 885 * Default constructor. 886 * Constructor is different from the old default Collator constructor. 887 * The task for determing the default collation strength and normalization 888 * mode is left to the child class. 889 * @stable ICU 2.0 890 */ 891 Collator(); 892 893 /** 894 * Constructor. 895 * Empty constructor, does not handle the arguments. 896 * This constructor is done for backward compatibility with 1.7 and 1.8. 897 * The task for handling the argument collation strength and normalization 898 * mode is left to the child class. 899 * @param collationStrength collation strength 900 * @param decompositionMode 901 * @deprecated ICU 2.4. Subclasses should use the default constructor 902 * instead and handle the strength and normalization mode themselves. 903 */ 904 Collator(UCollationStrength collationStrength, 905 UNormalizationMode decompositionMode); 906 907 /** 908 * Copy constructor. 909 * @param other Collator object to be copied from 910 * @stable ICU 2.0 911 */ 912 Collator(const Collator& other); 913 914 // Collator protected methods ----------------------------------------- 915 916 917 /** 918 * Used internally by registraton to define the requested and valid locales. 919 * @param requestedLocale the requsted locale 920 * @param validLocale the valid locale 921 * @internal 922 */ 923 virtual void setLocales(const Locale& requestedLocale, const Locale& validLocale); 924 925 public: 926 #if !UCONFIG_NO_SERVICE 927 /** 928 * used only by ucol_open, not for public use 929 * @internal 930 */ 931 static UCollator* createUCollator(const char* loc, UErrorCode* status); 932 #endif 933 private: 934 /** 935 * Assignment operator. Private for now. 936 * @internal 937 */ 938 Collator& operator=(const Collator& other); 939 940 friend class CFactory; 941 friend class SimpleCFactory; 942 friend class ICUCollatorFactory; 943 friend class ICUCollatorService; 944 static Collator* makeInstance(const Locale& desiredLocale, 945 UErrorCode& status); 946 947 // Collator private data members --------------------------------------- 948 949 /* 950 synwee : removed as attributes to be handled by child class 951 UCollationStrength strength; 952 Normalizer::EMode decmp; 953 */ 954 /* This is useless information */ 955 /* static const UVersionInfo fVersion;*/ 956 }; 957 958 #if !UCONFIG_NO_SERVICE 959 /** 960 * A factory, used with registerFactory, the creates multiple collators and provides 961 * display names for them. A factory supports some number of locales-- these are the 962 * locales for which it can create collators. The factory can be visible, in which 963 * case the supported locales will be enumerated by getAvailableLocales, or invisible, 964 * in which they are not. Invisible locales are still supported, they are just not 965 * listed by getAvailableLocales. 966 * <p> 967 * If standard locale display names are sufficient, Collator instances can 968 * be registered using registerInstance instead.</p> 969 * <p> 970 * Note: if the collators are to be used from C APIs, they must be instances 971 * of RuleBasedCollator.</p> 972 * 973 * @stable ICU 2.6 974 */ 975 class U_I18N_API CollatorFactory : public UObject { 976 public: 977 978 /** 979 * Destructor 980 * @stable ICU 3.0 981 */ 982 virtual ~CollatorFactory(); 983 984 /** 985 * Return true if this factory is visible. Default is true. 986 * If not visible, the locales supported by this factory will not 987 * be listed by getAvailableLocales. 988 * @return true if the factory is visible. 989 * @stable ICU 2.6 990 */ 991 virtual UBool visible(void) const; 992 993 /** 994 * Return a collator for the provided locale. If the locale 995 * is not supported, return NULL. 996 * @param loc the locale identifying the collator to be created. 997 * @return a new collator if the locale is supported, otherwise NULL. 998 * @stable ICU 2.6 999 */ 1000 virtual Collator* createCollator(const Locale& loc) = 0; 1001 1002 /** 1003 * Return the name of the collator for the objectLocale, localized for the displayLocale. 1004 * If objectLocale is not supported, or the factory is not visible, set the result string 1005 * to bogus. 1006 * @param objectLocale the locale identifying the collator 1007 * @param displayLocale the locale for which the display name of the collator should be localized 1008 * @param result an output parameter for the display name, set to bogus if not supported. 1009 * @return the display name 1010 * @stable ICU 2.6 1011 */ 1012 virtual UnicodeString& getDisplayName(const Locale& objectLocale, 1013 const Locale& displayLocale, 1014 UnicodeString& result); 1015 1016 /** 1017 * Return an array of all the locale names directly supported by this factory. 1018 * The number of names is returned in count. This array is owned by the factory. 1019 * Its contents must never change. 1020 * @param count output parameter for the number of locales supported by the factory 1021 * @param status the in/out error code 1022 * @return a pointer to an array of count UnicodeStrings. 1023 * @stable ICU 2.6 1024 */ 1025 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) = 0; 1026 }; 1027 #endif /* UCONFIG_NO_SERVICE */ 1028 1029 // Collator inline methods ----------------------------------------------- 1030 1031 U_NAMESPACE_END 1032 1033 #endif /* #if !UCONFIG_NO_COLLATION */ 1034 1035 #endif 1036