1/* 2****************************************************************************** 3* Copyright (C) 1996-2014, International Business Machines Corporation and 4* others. All Rights Reserved. 5****************************************************************************** 6*/ 7 8/** 9 * \file 10 * \brief C++ API: The RuleBasedCollator class implements the Collator abstract base class. 11 */ 12 13/** 14* File tblcoll.h 15* 16* Created by: Helena Shih 17* 18* Modification History: 19* 20* Date Name Description 21* 2/5/97 aliu Added streamIn and streamOut methods. Added 22* constructor which reads RuleBasedCollator object from 23* a binary file. Added writeToFile method which streams 24* RuleBasedCollator out to a binary file. The streamIn 25* and streamOut methods use istream and ostream objects 26* in binary mode. 27* 2/12/97 aliu Modified to use TableCollationData sub-object to 28* hold invariant data. 29* 2/13/97 aliu Moved several methods into this class from Collation. 30* Added a private RuleBasedCollator(Locale&) constructor, 31* to be used by Collator::createDefault(). General 32* clean up. 33* 2/20/97 helena Added clone, operator==, operator!=, operator=, and copy 34* constructor and getDynamicClassID. 35* 3/5/97 aliu Modified constructFromFile() to add parameter 36* specifying whether or not binary loading is to be 37* attempted. This is required for dynamic rule loading. 38* 05/07/97 helena Added memory allocation error detection. 39* 6/17/97 helena Added IDENTICAL strength for compare, changed getRules to 40* use MergeCollation::getPattern. 41* 6/20/97 helena Java class name change. 42* 8/18/97 helena Added internal API documentation. 43* 09/03/97 helena Added createCollationKeyValues(). 44* 02/10/98 damiba Added compare with "length" parameter 45* 08/05/98 erm Synched with 1.2 version of RuleBasedCollator.java 46* 04/23/99 stephen Removed EDecompositionMode, merged with 47* Normalizer::EMode 48* 06/14/99 stephen Removed kResourceBundleSuffix 49* 11/02/99 helena Collator performance enhancements. Eliminates the 50* UnicodeString construction and special case for NO_OP. 51* 11/23/99 srl More performance enhancements. Updates to NormalizerIterator 52* internal state management. 53* 12/15/99 aliu Update to support Thai collation. Move NormalizerIterator 54* to implementation file. 55* 01/29/01 synwee Modified into a C++ wrapper which calls C API 56* (ucol.h) 57* 2012-2014 markus Rewritten in C++ again. 58*/ 59 60#ifndef TBLCOLL_H 61#define TBLCOLL_H 62 63#include "unicode/utypes.h" 64 65#if !UCONFIG_NO_COLLATION 66 67#include "unicode/coll.h" 68#include "unicode/locid.h" 69#include "unicode/uiter.h" 70#include "unicode/ucol.h" 71 72U_NAMESPACE_BEGIN 73 74struct CollationData; 75struct CollationSettings; 76struct CollationTailoring; 77/** 78* @stable ICU 2.0 79*/ 80class StringSearch; 81/** 82* @stable ICU 2.0 83*/ 84class CollationElementIterator; 85class CollationKey; 86class SortKeyByteSink; 87class UnicodeSet; 88class UnicodeString; 89class UVector64; 90 91/** 92 * The RuleBasedCollator class provides the implementation of 93 * Collator, using data-driven tables. The user can create a customized 94 * table-based collation. 95 * <p> 96 * For more information about the collation service see 97 * <a href="http://userguide.icu-project.org/collation">the User Guide</a>. 98 * <p> 99 * Collation service provides correct sorting orders for most locales supported in ICU. 100 * If specific data for a locale is not available, the orders eventually falls back 101 * to the <a href="http://www.unicode.org/reports/tr35/tr35-collation.html#Root_Collation">CLDR root sort order</a>. 102 * <p> 103 * Sort ordering may be customized by providing your own set of rules. For more on 104 * this subject see the <a href="http://userguide.icu-project.org/collation/customization"> 105 * Collation Customization</a> section of the User Guide. 106 * <p> 107 * Note, RuleBasedCollator is not to be subclassed. 108 * @see Collator 109 */ 110class U_I18N_API RuleBasedCollator : public Collator { 111public: 112 /** 113 * RuleBasedCollator constructor. This takes the table rules and builds a 114 * collation table out of them. Please see RuleBasedCollator class 115 * description for more details on the collation rule syntax. 116 * @param rules the collation rules to build the collation table from. 117 * @param status reporting a success or an error. 118 * @see Locale 119 * @stable ICU 2.0 120 */ 121 RuleBasedCollator(const UnicodeString& rules, UErrorCode& status); 122 123 /** 124 * RuleBasedCollator constructor. This takes the table rules and builds a 125 * collation table out of them. Please see RuleBasedCollator class 126 * description for more details on the collation rule syntax. 127 * @param rules the collation rules to build the collation table from. 128 * @param collationStrength default strength for comparison 129 * @param status reporting a success or an error. 130 * @see Locale 131 * @stable ICU 2.0 132 */ 133 RuleBasedCollator(const UnicodeString& rules, 134 ECollationStrength collationStrength, 135 UErrorCode& status); 136 137 /** 138 * RuleBasedCollator constructor. This takes the table rules and builds a 139 * collation table out of them. Please see RuleBasedCollator class 140 * description for more details on the collation rule syntax. 141 * @param rules the collation rules to build the collation table from. 142 * @param decompositionMode the normalisation mode 143 * @param status reporting a success or an error. 144 * @see Locale 145 * @stable ICU 2.0 146 */ 147 RuleBasedCollator(const UnicodeString& rules, 148 UColAttributeValue decompositionMode, 149 UErrorCode& status); 150 151 /** 152 * RuleBasedCollator constructor. This takes the table rules and builds a 153 * collation table out of them. Please see RuleBasedCollator class 154 * description for more details on the collation rule syntax. 155 * @param rules the collation rules to build the collation table from. 156 * @param collationStrength default strength for comparison 157 * @param decompositionMode the normalisation mode 158 * @param status reporting a success or an error. 159 * @see Locale 160 * @stable ICU 2.0 161 */ 162 RuleBasedCollator(const UnicodeString& rules, 163 ECollationStrength collationStrength, 164 UColAttributeValue decompositionMode, 165 UErrorCode& status); 166 167#ifndef U_HIDE_INTERNAL_API 168 /** 169 * TODO: document & propose as public API 170 * @internal 171 */ 172 RuleBasedCollator(const UnicodeString &rules, 173 UParseError &parseError, UnicodeString &reason, 174 UErrorCode &errorCode); 175#endif /* U_HIDE_INTERNAL_API */ 176 177 /** 178 * Copy constructor. 179 * @param other the RuleBasedCollator object to be copied 180 * @see Locale 181 * @stable ICU 2.0 182 */ 183 RuleBasedCollator(const RuleBasedCollator& other); 184 185 186 /** Opens a collator from a collator binary image created using 187 * cloneBinary. Binary image used in instantiation of the 188 * collator remains owned by the user and should stay around for 189 * the lifetime of the collator. The API also takes a base collator 190 * which usually should be the root collator. 191 * @param bin binary image owned by the user and required through the 192 * lifetime of the collator 193 * @param length size of the image. If negative, the API will try to 194 * figure out the length of the image 195 * @param base fallback collator, usually root. The base is required to be 196 * present through the lifetime of the collator. Currently 197 * it cannot be NULL. 198 * @param status for catching errors 199 * @return newly created collator 200 * @see cloneBinary 201 * @stable ICU 3.4 202 */ 203 RuleBasedCollator(const uint8_t *bin, int32_t length, 204 const RuleBasedCollator *base, 205 UErrorCode &status); 206 207 /** 208 * Destructor. 209 * @stable ICU 2.0 210 */ 211 virtual ~RuleBasedCollator(); 212 213 /** 214 * Assignment operator. 215 * @param other other RuleBasedCollator object to copy from. 216 * @stable ICU 2.0 217 */ 218 RuleBasedCollator& operator=(const RuleBasedCollator& other); 219 220 /** 221 * Returns true if argument is the same as this object. 222 * @param other Collator object to be compared. 223 * @return true if arguments is the same as this object. 224 * @stable ICU 2.0 225 */ 226 virtual UBool operator==(const Collator& other) const; 227 228 /** 229 * Makes a copy of this object. 230 * @return a copy of this object, owned by the caller 231 * @stable ICU 2.0 232 */ 233 virtual Collator* clone(void) const; 234 235 /** 236 * Creates a collation element iterator for the source string. The caller of 237 * this method is responsible for the memory management of the return 238 * pointer. 239 * @param source the string over which the CollationElementIterator will 240 * iterate. 241 * @return the collation element iterator of the source string using this as 242 * the based Collator. 243 * @stable ICU 2.2 244 */ 245 virtual CollationElementIterator* createCollationElementIterator( 246 const UnicodeString& source) const; 247 248 /** 249 * Creates a collation element iterator for the source. The caller of this 250 * method is responsible for the memory management of the returned pointer. 251 * @param source the CharacterIterator which produces the characters over 252 * which the CollationElementItgerator will iterate. 253 * @return the collation element iterator of the source using this as the 254 * based Collator. 255 * @stable ICU 2.2 256 */ 257 virtual CollationElementIterator* createCollationElementIterator( 258 const CharacterIterator& source) const; 259 260 // Make deprecated versions of Collator::compare() visible. 261 using Collator::compare; 262 263 /** 264 * The comparison function compares the character data stored in two 265 * different strings. Returns information about whether a string is less 266 * than, greater than or equal to another string. 267 * @param source the source string to be compared with. 268 * @param target the string that is to be compared with the source string. 269 * @param status possible error code 270 * @return Returns an enum value. UCOL_GREATER if source is greater 271 * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less 272 * than target 273 * @stable ICU 2.6 274 **/ 275 virtual UCollationResult compare(const UnicodeString& source, 276 const UnicodeString& target, 277 UErrorCode &status) const; 278 279 /** 280 * Does the same thing as compare but limits the comparison to a specified 281 * length 282 * @param source the source string to be compared with. 283 * @param target the string that is to be compared with the source string. 284 * @param length the length the comparison is limited to 285 * @param status possible error code 286 * @return Returns an enum value. UCOL_GREATER if source (up to the specified 287 * length) is greater than target; UCOL_EQUAL if source (up to specified 288 * length) is equal to target; UCOL_LESS if source (up to the specified 289 * length) is less than target. 290 * @stable ICU 2.6 291 */ 292 virtual UCollationResult compare(const UnicodeString& source, 293 const UnicodeString& target, 294 int32_t length, 295 UErrorCode &status) const; 296 297 /** 298 * The comparison function compares the character data stored in two 299 * different string arrays. Returns information about whether a string array 300 * is less than, greater than or equal to another string array. 301 * @param source the source string array to be compared with. 302 * @param sourceLength the length of the source string array. If this value 303 * is equal to -1, the string array is null-terminated. 304 * @param target the string that is to be compared with the source string. 305 * @param targetLength the length of the target string array. If this value 306 * is equal to -1, the string array is null-terminated. 307 * @param status possible error code 308 * @return Returns an enum value. UCOL_GREATER if source is greater 309 * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less 310 * than target 311 * @stable ICU 2.6 312 */ 313 virtual UCollationResult compare(const UChar* source, int32_t sourceLength, 314 const UChar* target, int32_t targetLength, 315 UErrorCode &status) const; 316 317 /** 318 * Compares two strings using the Collator. 319 * Returns whether the first one compares less than/equal to/greater than 320 * the second one. 321 * This version takes UCharIterator input. 322 * @param sIter the first ("source") string iterator 323 * @param tIter the second ("target") string iterator 324 * @param status ICU status 325 * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER 326 * @stable ICU 4.2 327 */ 328 virtual UCollationResult compare(UCharIterator &sIter, 329 UCharIterator &tIter, 330 UErrorCode &status) const; 331 332 /** 333 * Compares two UTF-8 strings using the Collator. 334 * Returns whether the first one compares less than/equal to/greater than 335 * the second one. 336 * This version takes UTF-8 input. 337 * Note that a StringPiece can be implicitly constructed 338 * from a std::string or a NUL-terminated const char * string. 339 * @param source the first UTF-8 string 340 * @param target the second UTF-8 string 341 * @param status ICU status 342 * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER 343 * @stable ICU 51 344 */ 345 virtual UCollationResult compareUTF8(const StringPiece &source, 346 const StringPiece &target, 347 UErrorCode &status) const; 348 349 /** 350 * Transforms a specified region of the string into a series of characters 351 * that can be compared with CollationKey.compare. Use a CollationKey when 352 * you need to do repeated comparisions on the same string. For a single 353 * comparison the compare method will be faster. 354 * @param source the source string. 355 * @param key the transformed key of the source string. 356 * @param status the error code status. 357 * @return the transformed key. 358 * @see CollationKey 359 * @stable ICU 2.0 360 */ 361 virtual CollationKey& getCollationKey(const UnicodeString& source, 362 CollationKey& key, 363 UErrorCode& status) const; 364 365 /** 366 * Transforms a specified region of the string into a series of characters 367 * that can be compared with CollationKey.compare. Use a CollationKey when 368 * you need to do repeated comparisions on the same string. For a single 369 * comparison the compare method will be faster. 370 * @param source the source string. 371 * @param sourceLength the length of the source string. 372 * @param key the transformed key of the source string. 373 * @param status the error code status. 374 * @return the transformed key. 375 * @see CollationKey 376 * @stable ICU 2.0 377 */ 378 virtual CollationKey& getCollationKey(const UChar *source, 379 int32_t sourceLength, 380 CollationKey& key, 381 UErrorCode& status) const; 382 383 /** 384 * Generates the hash code for the rule-based collation object. 385 * @return the hash code. 386 * @stable ICU 2.0 387 */ 388 virtual int32_t hashCode() const; 389 390 /** 391 * Gets the locale of the Collator 392 * @param type can be either requested, valid or actual locale. For more 393 * information see the definition of ULocDataLocaleType in 394 * uloc.h 395 * @param status the error code status. 396 * @return locale where the collation data lives. If the collator 397 * was instantiated from rules, locale is empty. 398 * @deprecated ICU 2.8 likely to change in ICU 3.0, based on feedback 399 */ 400 virtual Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const; 401 402 /** 403 * Gets the tailoring rules for this collator. 404 * @return the collation tailoring from which this collator was created 405 * @stable ICU 2.0 406 */ 407 const UnicodeString& getRules() const; 408 409 /** 410 * Gets the version information for a Collator. 411 * @param info the version # information, the result will be filled in 412 * @stable ICU 2.0 413 */ 414 virtual void getVersion(UVersionInfo info) const; 415 416#ifndef U_HIDE_DEPRECATED_API 417 /** 418 * Returns the maximum length of any expansion sequences that end with the 419 * specified comparison order. 420 * 421 * This is specific to the kind of collation element values and sequences 422 * returned by the CollationElementIterator. 423 * Call CollationElementIterator::getMaxExpansion() instead. 424 * 425 * @param order a collation order returned by CollationElementIterator::previous 426 * or CollationElementIterator::next. 427 * @return maximum size of the expansion sequences ending with the collation 428 * element, or 1 if the collation element does not occur at the end of 429 * any expansion sequence 430 * @see CollationElementIterator#getMaxExpansion 431 * @deprecated ICU 51 Use CollationElementIterator::getMaxExpansion() instead. 432 */ 433 int32_t getMaxExpansion(int32_t order) const; 434#endif /* U_HIDE_DEPRECATED_API */ 435 436 /** 437 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This 438 * method is to implement a simple version of RTTI, since not all C++ 439 * compilers support genuine RTTI. Polymorphic operator==() and clone() 440 * methods call this method. 441 * @return The class ID for this object. All objects of a given class have 442 * the same class ID. Objects of other classes have different class 443 * IDs. 444 * @stable ICU 2.0 445 */ 446 virtual UClassID getDynamicClassID(void) const; 447 448 /** 449 * Returns the class ID for this class. This is useful only for comparing to 450 * a return value from getDynamicClassID(). For example: 451 * <pre> 452 * Base* polymorphic_pointer = createPolymorphicObject(); 453 * if (polymorphic_pointer->getDynamicClassID() == 454 * Derived::getStaticClassID()) ... 455 * </pre> 456 * @return The class ID for all objects of this class. 457 * @stable ICU 2.0 458 */ 459 static UClassID U_EXPORT2 getStaticClassID(void); 460 461#ifndef U_HIDE_DEPRECATED_API 462 /** 463 * Do not use this method: The caller and the ICU library might use different heaps. 464 * Use cloneBinary() instead which writes to caller-provided memory. 465 * 466 * Returns a binary format of this collator. 467 * @param length Returns the length of the data, in bytes 468 * @param status the error code status. 469 * @return memory, owned by the caller, of size 'length' bytes. 470 * @deprecated ICU 52. Use cloneBinary() instead. 471 */ 472 uint8_t *cloneRuleData(int32_t &length, UErrorCode &status) const; 473#endif /* U_HIDE_DEPRECATED_API */ 474 475 /** Creates a binary image of a collator. This binary image can be stored and 476 * later used to instantiate a collator using ucol_openBinary. 477 * This API supports preflighting. 478 * @param buffer a fill-in buffer to receive the binary image 479 * @param capacity capacity of the destination buffer 480 * @param status for catching errors 481 * @return size of the image 482 * @see ucol_openBinary 483 * @stable ICU 3.4 484 */ 485 int32_t cloneBinary(uint8_t *buffer, int32_t capacity, UErrorCode &status) const; 486 487 /** 488 * Returns current rules. Delta defines whether full rules are returned or 489 * just the tailoring. 490 * 491 * getRules(void) should normally be used instead. 492 * See http://userguide.icu-project.org/collation/customization#TOC-Building-on-Existing-Locales 493 * @param delta one of UCOL_TAILORING_ONLY, UCOL_FULL_RULES. 494 * @param buffer UnicodeString to store the result rules 495 * @stable ICU 2.2 496 * @see UCOL_FULL_RULES 497 */ 498 void getRules(UColRuleOption delta, UnicodeString &buffer) const; 499 500 /** 501 * Universal attribute setter 502 * @param attr attribute type 503 * @param value attribute value 504 * @param status to indicate whether the operation went on smoothly or there were errors 505 * @stable ICU 2.2 506 */ 507 virtual void setAttribute(UColAttribute attr, UColAttributeValue value, 508 UErrorCode &status); 509 510 /** 511 * Universal attribute getter. 512 * @param attr attribute type 513 * @param status to indicate whether the operation went on smoothly or there were errors 514 * @return attribute value 515 * @stable ICU 2.2 516 */ 517 virtual UColAttributeValue getAttribute(UColAttribute attr, 518 UErrorCode &status) const; 519 520 /** 521 * Sets the variable top to the top of the specified reordering group. 522 * The variable top determines the highest-sorting character 523 * which is affected by UCOL_ALTERNATE_HANDLING. 524 * If that attribute is set to UCOL_NON_IGNORABLE, then the variable top has no effect. 525 * @param group one of UCOL_REORDER_CODE_SPACE, UCOL_REORDER_CODE_PUNCTUATION, 526 * UCOL_REORDER_CODE_SYMBOL, UCOL_REORDER_CODE_CURRENCY; 527 * or UCOL_REORDER_CODE_DEFAULT to restore the default max variable group 528 * @param errorCode Standard ICU error code. Its input value must 529 * pass the U_SUCCESS() test, or else the function returns 530 * immediately. Check for U_FAILURE() on output or use with 531 * function chaining. (See User Guide for details.) 532 * @return *this 533 * @see getMaxVariable 534 * @draft ICU 53 535 */ 536 virtual Collator &setMaxVariable(UColReorderCode group, UErrorCode &errorCode); 537 538 /** 539 * Returns the maximum reordering group whose characters are affected by UCOL_ALTERNATE_HANDLING. 540 * @return the maximum variable reordering group. 541 * @see setMaxVariable 542 * @draft ICU 53 543 */ 544 virtual UColReorderCode getMaxVariable() const; 545 546 /** 547 * Sets the variable top to the primary weight of the specified string. 548 * 549 * Beginning with ICU 53, the variable top is pinned to 550 * the top of one of the supported reordering groups, 551 * and it must not be beyond the last of those groups. 552 * See setMaxVariable(). 553 * @param varTop one or more (if contraction) UChars to which the variable top should be set 554 * @param len length of variable top string. If -1 it is considered to be zero terminated. 555 * @param status error code. If error code is set, the return value is undefined. Errors set by this function are: <br> 556 * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such contraction<br> 557 * U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond 558 * the last reordering group supported by setMaxVariable() 559 * @return variable top primary weight 560 * @deprecated ICU 53 Call setMaxVariable() instead. 561 */ 562 virtual uint32_t setVariableTop(const UChar *varTop, int32_t len, UErrorCode &status); 563 564 /** 565 * Sets the variable top to the primary weight of the specified string. 566 * 567 * Beginning with ICU 53, the variable top is pinned to 568 * the top of one of the supported reordering groups, 569 * and it must not be beyond the last of those groups. 570 * See setMaxVariable(). 571 * @param varTop a UnicodeString size 1 or more (if contraction) of UChars to which the variable top should be set 572 * @param status error code. If error code is set, the return value is undefined. Errors set by this function are: <br> 573 * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such contraction<br> 574 * U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond 575 * the last reordering group supported by setMaxVariable() 576 * @return variable top primary weight 577 * @deprecated ICU 53 Call setMaxVariable() instead. 578 */ 579 virtual uint32_t setVariableTop(const UnicodeString &varTop, UErrorCode &status); 580 581 /** 582 * Sets the variable top to the specified primary weight. 583 * 584 * Beginning with ICU 53, the variable top is pinned to 585 * the top of one of the supported reordering groups, 586 * and it must not be beyond the last of those groups. 587 * See setMaxVariable(). 588 * @param varTop primary weight, as returned by setVariableTop or ucol_getVariableTop 589 * @param status error code 590 * @deprecated ICU 53 Call setMaxVariable() instead. 591 */ 592 virtual void setVariableTop(uint32_t varTop, UErrorCode &status); 593 594 /** 595 * Gets the variable top value of a Collator. 596 * @param status error code (not changed by function). If error code is set, the return value is undefined. 597 * @return the variable top primary weight 598 * @see getMaxVariable 599 * @stable ICU 2.0 600 */ 601 virtual uint32_t getVariableTop(UErrorCode &status) const; 602 603 /** 604 * Get a UnicodeSet that contains all the characters and sequences tailored in 605 * this collator. 606 * @param status error code of the operation 607 * @return a pointer to a UnicodeSet object containing all the 608 * code points and sequences that may sort differently than 609 * in the root collator. The object must be disposed of by using delete 610 * @stable ICU 2.4 611 */ 612 virtual UnicodeSet *getTailoredSet(UErrorCode &status) const; 613 614 /** 615 * Get the sort key as an array of bytes from a UnicodeString. 616 * @param source string to be processed. 617 * @param result buffer to store result in. If NULL, number of bytes needed 618 * will be returned. 619 * @param resultLength length of the result buffer. If if not enough the 620 * buffer will be filled to capacity. 621 * @return Number of bytes needed for storing the sort key 622 * @stable ICU 2.0 623 */ 624 virtual int32_t getSortKey(const UnicodeString& source, uint8_t *result, 625 int32_t resultLength) const; 626 627 /** 628 * Get the sort key as an array of bytes from a UChar buffer. 629 * @param source string to be processed. 630 * @param sourceLength length of string to be processed. If -1, the string 631 * is 0 terminated and length will be decided by the function. 632 * @param result buffer to store result in. If NULL, number of bytes needed 633 * will be returned. 634 * @param resultLength length of the result buffer. If if not enough the 635 * buffer will be filled to capacity. 636 * @return Number of bytes needed for storing the sort key 637 * @stable ICU 2.2 638 */ 639 virtual int32_t getSortKey(const UChar *source, int32_t sourceLength, 640 uint8_t *result, int32_t resultLength) const; 641 642 /** 643 * Retrieves the reordering codes for this collator. 644 * @param dest The array to fill with the script ordering. 645 * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the function 646 * will only return the length of the result without writing any of the result string (pre-flighting). 647 * @param status A reference to an error code value, which must not indicate 648 * a failure before the function call. 649 * @return The length of the script ordering array. 650 * @see ucol_setReorderCodes 651 * @see Collator#getEquivalentReorderCodes 652 * @see Collator#setReorderCodes 653 * @stable ICU 4.8 654 */ 655 virtual int32_t getReorderCodes(int32_t *dest, 656 int32_t destCapacity, 657 UErrorCode& status) const; 658 659 /** 660 * Sets the ordering of scripts for this collator. 661 * @param reorderCodes An array of script codes in the new order. This can be NULL if the 662 * length is also set to 0. An empty array will clear any reordering codes on the collator. 663 * @param reorderCodesLength The length of reorderCodes. 664 * @param status error code 665 * @see Collator#getReorderCodes 666 * @see Collator#getEquivalentReorderCodes 667 * @stable ICU 4.8 668 */ 669 virtual void setReorderCodes(const int32_t* reorderCodes, 670 int32_t reorderCodesLength, 671 UErrorCode& status) ; 672 673 /** 674 * Implements ucol_strcollUTF8(). 675 * @internal 676 */ 677 virtual UCollationResult internalCompareUTF8( 678 const char *left, int32_t leftLength, 679 const char *right, int32_t rightLength, 680 UErrorCode &errorCode) const; 681 682 /** Get the short definition string for a collator. This internal API harvests the collator's 683 * locale and the attribute set and produces a string that can be used for opening 684 * a collator with the same attributes using the ucol_openFromShortString API. 685 * This string will be normalized. 686 * The structure and the syntax of the string is defined in the "Naming collators" 687 * section of the users guide: 688 * http://userguide.icu-project.org/collation/concepts#TOC-Collator-naming-scheme 689 * This function supports preflighting. 690 * 691 * This is internal, and intended to be used with delegate converters. 692 * 693 * @param locale a locale that will appear as a collators locale in the resulting 694 * short string definition. If NULL, the locale will be harvested 695 * from the collator. 696 * @param buffer space to hold the resulting string 697 * @param capacity capacity of the buffer 698 * @param status for returning errors. All the preflighting errors are featured 699 * @return length of the resulting string 700 * @see ucol_openFromShortString 701 * @see ucol_normalizeShortDefinitionString 702 * @see ucol_getShortDefinitionString 703 * @internal 704 */ 705 virtual int32_t internalGetShortDefinitionString(const char *locale, 706 char *buffer, 707 int32_t capacity, 708 UErrorCode &status) const; 709 710 /** 711 * Implements ucol_nextSortKeyPart(). 712 * @internal 713 */ 714 virtual int32_t internalNextSortKeyPart( 715 UCharIterator *iter, uint32_t state[2], 716 uint8_t *dest, int32_t count, UErrorCode &errorCode) const; 717 718#ifndef U_HIDE_INTERNAL_API 719 /** 720 * Only for use in ucol_openRules(). 721 * @internal 722 */ 723 RuleBasedCollator(); 724 725 /** 726 * Implements ucol_getLocaleByType(). 727 * Needed because the lifetime of the locale ID string must match that of the collator. 728 * getLocale() returns a copy of a Locale, with minimal lifetime in a C wrapper. 729 * @internal 730 */ 731 const char *internalGetLocaleID(ULocDataLocaleType type, UErrorCode &errorCode) const; 732 733 /** 734 * Implements ucol_getContractionsAndExpansions(). 735 * Gets this collator's sets of contraction strings and/or 736 * characters and strings that map to multiple collation elements (expansions). 737 * If addPrefixes is TRUE, then contractions that are expressed as 738 * prefix/pre-context rules are included. 739 * @param contractions if not NULL, the set to hold the contractions 740 * @param expansions if not NULL, the set to hold the expansions 741 * @param addPrefixes include prefix contextual mappings 742 * @param errorCode in/out ICU error code 743 * @internal 744 */ 745 void internalGetContractionsAndExpansions( 746 UnicodeSet *contractions, UnicodeSet *expansions, 747 UBool addPrefixes, UErrorCode &errorCode) const; 748 749 /** 750 * Adds the contractions that start with character c to the set. 751 * Ignores prefixes. Used by AlphabeticIndex. 752 * @internal 753 */ 754 void internalAddContractions(UChar32 c, UnicodeSet &set, UErrorCode &errorCode) const; 755 756 /** 757 * Implements from-rule constructors, and ucol_openRules(). 758 * @internal 759 */ 760 void internalBuildTailoring( 761 const UnicodeString &rules, 762 int32_t strength, 763 UColAttributeValue decompositionMode, 764 UParseError *outParseError, UnicodeString *outReason, 765 UErrorCode &errorCode); 766 767 /** @internal */ 768 static inline RuleBasedCollator *rbcFromUCollator(UCollator *uc) { 769 return dynamic_cast<RuleBasedCollator *>(fromUCollator(uc)); 770 } 771 /** @internal */ 772 static inline const RuleBasedCollator *rbcFromUCollator(const UCollator *uc) { 773 return dynamic_cast<const RuleBasedCollator *>(fromUCollator(uc)); 774 } 775 776 /** 777 * Appends the CEs for the string to the vector. 778 * @internal for tests & tools 779 */ 780 void internalGetCEs(const UnicodeString &str, UVector64 &ces, UErrorCode &errorCode) const; 781#endif // U_HIDE_INTERNAL_API 782 783protected: 784 /** 785 * Used internally by registration to define the requested and valid locales. 786 * @param requestedLocale the requested locale 787 * @param validLocale the valid locale 788 * @param actualLocale the actual locale 789 * @internal 790 */ 791 virtual void setLocales(const Locale& requestedLocale, const Locale& validLocale, const Locale& actualLocale); 792 793private: 794 friend class CollationElementIterator; 795 friend class Collator; 796 797 RuleBasedCollator(const CollationTailoring *t, const Locale &vl); 798 799 /** 800 * Enumeration of attributes that are relevant for short definition strings 801 * (e.g., ucol_getShortDefinitionString()). 802 * Effectively extends UColAttribute. 803 */ 804 enum Attributes { 805 ATTR_VARIABLE_TOP = UCOL_ATTRIBUTE_COUNT, 806 ATTR_LIMIT 807 }; 808 809 void adoptTailoring(CollationTailoring *t); 810 811 // Both lengths must be <0 or else both must be >=0. 812 UCollationResult doCompare(const UChar *left, int32_t leftLength, 813 const UChar *right, int32_t rightLength, 814 UErrorCode &errorCode) const; 815 UCollationResult doCompare(const uint8_t *left, int32_t leftLength, 816 const uint8_t *right, int32_t rightLength, 817 UErrorCode &errorCode) const; 818 819 void writeSortKey(const UChar *s, int32_t length, 820 SortKeyByteSink &sink, UErrorCode &errorCode) const; 821 822 void writeIdenticalLevel(const UChar *s, const UChar *limit, 823 SortKeyByteSink &sink, UErrorCode &errorCode) const; 824 825 const CollationSettings &getDefaultSettings() const; 826 827 void setAttributeDefault(int32_t attribute) { 828 explicitlySetAttributes &= ~((uint32_t)1 << attribute); 829 } 830 void setAttributeExplicitly(int32_t attribute) { 831 explicitlySetAttributes |= (uint32_t)1 << attribute; 832 } 833 UBool attributeHasBeenSetExplicitly(int32_t attribute) const { 834 // assert(0 <= attribute < ATTR_LIMIT); 835 return (UBool)((explicitlySetAttributes & ((uint32_t)1 << attribute)) != 0); 836 } 837 838 /** 839 * Tests whether a character is "unsafe" for use as a collation starting point. 840 * 841 * @param c code point or code unit 842 * @return TRUE if c is unsafe 843 * @see CollationElementIterator#setOffset(int) 844 */ 845 UBool isUnsafe(UChar32 c) const; 846 847 static void computeMaxExpansions(const CollationTailoring *t, UErrorCode &errorCode); 848 UBool initMaxExpansions(UErrorCode &errorCode) const; 849 850 void setFastLatinOptions(CollationSettings &ownedSettings) const; 851 852 const CollationData *data; 853 const CollationSettings *settings; // reference-counted 854 const CollationTailoring *tailoring; // reference-counted 855 Locale validLocale; 856 uint32_t explicitlySetAttributes; 857 858 UBool actualLocaleIsSameAsValid; 859}; 860 861U_NAMESPACE_END 862 863#endif // !UCONFIG_NO_COLLATION 864#endif // TBLCOLL_H 865