icuSources/i18n/unicode/tblcoll.h

   1 /*
   2 ******************************************************************************
   3 * Copyright (C) 1996-2010, International Business Machines Corporation and
   4 * others. All Rights Reserved.
   5 ******************************************************************************
   6 */
   7
   8 /**
   9  * \file
  10  * \brief C++ API: RuleBasedCollator class provides the simple implementation of Collator.
  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 */
  58
  59 #ifndef TBLCOLL_H
  60 #define TBLCOLL_H
  61
  62 #include "unicode/utypes.h"
  63
  64
  65 #if !UCONFIG_NO_COLLATION
  66
  67 #include "unicode/coll.h"
  68 #include "unicode/ucol.h"
  69 #include "unicode/sortkey.h"
  70 #include "unicode/normlzr.h"
  71
  72 U_NAMESPACE_BEGIN
  73
  74 /**
  75 * @stable ICU 2.0
  76 */
  77 class StringSearch;
  78 /**
  79 * @stable ICU 2.0
  80 */
  81 class CollationElementIterator;
  82
  83 /**
  84  * The RuleBasedCollator class provides the simple implementation of
  85  * Collator, using data-driven tables. The user can create a customized
  86  * table-based collation.
  87  * <P>
  88  * <em>Important: </em>The ICU collation service has been reimplemented
  89  * in order to achieve better performance and UCA compliance.
  90  * For details, see the
  91  * <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/collation/ICU_collation_design.htm">
  92  * collation design document</a>.
  93  * <p>
  94  * RuleBasedCollator is a thin C++ wrapper over the C implementation.
  95  * <p>
  96  * For more information about the collation service see
  97  * <a href="http://icu-project.org/userguide/Collate_Intro.html">the users 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/unicode/reports/tr10/">UCA 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://icu-project.org/userguide/Collate_Customization.html">
 105  * Collation customization</a> section of the users guide.
 106  * <p>
 107  * Note, RuleBasedCollator is not to be subclassed.
 108  * @see        Collator
 109  * @version    2.0 11/15/2001
 110  */
 111 class U_I18N_API RuleBasedCollator : public Collator
 112 {
 113 public:
 114
 115   // constructor -------------------------------------------------------------
 116
 117     /**
 118      * RuleBasedCollator constructor. This takes the table rules and builds a
 119      * collation table out of them. Please see RuleBasedCollator class
 120      * description for more details on the collation rule syntax.
 121      * @param rules the collation rules to build the collation table from.
 122      * @param status reporting a success or an error.
 123      * @see Locale
 124      * @stable ICU 2.0
 125      */
 126     RuleBasedCollator(const UnicodeString& rules, UErrorCode& status);
 127
 128     /**
 129      * RuleBasedCollator constructor. This takes the table rules and builds a
 130      * collation table out of them. Please see RuleBasedCollator class
 131      * description for more details on the collation rule syntax.
 132      * @param rules the collation rules to build the collation table from.
 133      * @param collationStrength default strength for comparison
 134      * @param status reporting a success or an error.
 135      * @see Locale
 136      * @stable ICU 2.0
 137      */
 138     RuleBasedCollator(const UnicodeString& rules,
 139                        ECollationStrength collationStrength,
 140                        UErrorCode& status);
 141
 142     /**
 143      * RuleBasedCollator constructor. This takes the table rules and builds a
 144      * collation table out of them. Please see RuleBasedCollator class
 145      * description for more details on the collation rule syntax.
 146      * @param rules the collation rules to build the collation table from.
 147      * @param decompositionMode the normalisation mode
 148      * @param status reporting a success or an error.
 149      * @see Locale
 150      * @stable ICU 2.0
 151      */
 152     RuleBasedCollator(const UnicodeString& rules,
 153                     UColAttributeValue decompositionMode,
 154                     UErrorCode& status);
 155
 156     /**
 157      * RuleBasedCollator constructor. This takes the table rules and builds a
 158      * collation table out of them. Please see RuleBasedCollator class
 159      * description for more details on the collation rule syntax.
 160      * @param rules the collation rules to build the collation table from.
 161      * @param collationStrength default strength for comparison
 162      * @param decompositionMode the normalisation mode
 163      * @param status reporting a success or an error.
 164      * @see Locale
 165      * @stable ICU 2.0
 166      */
 167     RuleBasedCollator(const UnicodeString& rules,
 168                     ECollationStrength collationStrength,
 169                     UColAttributeValue decompositionMode,
 170                     UErrorCode& status);
 171
 172     /**
 173      * Copy constructor.
 174      * @param other the RuleBasedCollator object to be copied
 175      * @see Locale
 176      * @stable ICU 2.0
 177      */
 178     RuleBasedCollator(const RuleBasedCollator& other);
 179
 180
 181     /** Opens a collator from a collator binary image created using
 182     *  cloneBinary. Binary image used in instantiation of the
 183     *  collator remains owned by the user and should stay around for
 184     *  the lifetime of the collator. The API also takes a base collator
 185     *  which usualy should be UCA.
 186     *  @param bin binary image owned by the user and required through the
 187     *             lifetime of the collator
 188     *  @param length size of the image. If negative, the API will try to
 189     *                figure out the length of the image
 190     *  @param base fallback collator, usually UCA. Base is required to be
 191     *              present through the lifetime of the collator. Currently
 192     *              it cannot be NULL.
 193     *  @param status for catching errors
 194     *  @return newly created collator
 195     *  @see cloneBinary
 196     *  @stable ICU 3.4
 197     */
 198     RuleBasedCollator(const uint8_t *bin, int32_t length,
 199                     const RuleBasedCollator *base,
 200                     UErrorCode &status);
 201     // destructor --------------------------------------------------------------
 202
 203     /**
 204      * Destructor.
 205      * @stable ICU 2.0
 206      */
 207     virtual ~RuleBasedCollator();
 208
 209     // public methods ----------------------------------------------------------
 210
 211     /**
 212      * Assignment operator.
 213      * @param other other RuleBasedCollator object to compare with.
 214      * @stable ICU 2.0
 215      */
 216     RuleBasedCollator& operator=(const RuleBasedCollator& other);
 217
 218     /**
 219      * Returns true if argument is the same as this object.
 220      * @param other Collator object to be compared.
 221      * @return true if arguments is the same as this object.
 222      * @stable ICU 2.0
 223      */
 224     virtual UBool operator==(const Collator& other) const;
 225
 226     /**
 227      * Returns true if argument is not the same as this object.
 228      * @param other Collator object to be compared
 229      * @return returns true if argument is not the same as this object.
 230      * @stable ICU 2.0
 231      */
 232     virtual UBool operator!=(const Collator& other) const;
 233
 234     /**
 235      * Makes a deep copy of the object.
 236      * The caller owns the returned object.
 237      * @return the cloned object.
 238      * @stable ICU 2.0
 239      */
 240     virtual Collator* clone(void) const;
 241
 242     /**
 243      * Creates a collation element iterator for the source string. The caller of
 244      * this method is responsible for the memory management of the return
 245      * pointer.
 246      * @param source the string over which the CollationElementIterator will
 247      *        iterate.
 248      * @return the collation element iterator of the source string using this as
 249      *         the based Collator.
 250      * @stable ICU 2.2
 251      */
 252     virtual CollationElementIterator* createCollationElementIterator(
 253                                            const UnicodeString& source) const;
 254
 255     /**
 256      * Creates a collation element iterator for the source. The caller of this
 257      * method is responsible for the memory management of the returned pointer.
 258      * @param source the CharacterIterator which produces the characters over
 259      *        which the CollationElementItgerator will iterate.
 260      * @return the collation element iterator of the source using this as the
 261      *         based Collator.
 262      * @stable ICU 2.2
 263      */
 264     virtual CollationElementIterator* createCollationElementIterator(
 265                                          const CharacterIterator& source) const;
 266
 267     /**
 268      * Compares a range of character data stored in two different strings based
 269      * on the collation rules. Returns information about whether a string is
 270      * less than, greater than or equal to another string in a language.
 271      * This can be overriden in a subclass.
 272      * @param source the source string.
 273      * @param target the target string to be compared with the source string.
 274      * @return the comparison result. GREATER if the source string is greater
 275      *         than the target string, LESS if the source is less than the
 276      *         target. Otherwise, returns EQUAL.
 277      * @deprecated ICU 2.6 Use overload with UErrorCode&
 278      */
 279     virtual EComparisonResult compare(const UnicodeString& source,
 280                                       const UnicodeString& target) const;
 281
 282
 283     /**
 284     * The comparison function compares the character data stored in two
 285     * different strings. Returns information about whether a string is less
 286     * than, greater than or equal to another string.
 287     * @param source the source string to be compared with.
 288     * @param target the string that is to be compared with the source string.
 289     * @param status possible error code
 290     * @return Returns an enum value. UCOL_GREATER if source is greater
 291     * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less
 292     * than target
 293     * @stable ICU 2.6
 294     **/
 295     virtual UCollationResult compare(const UnicodeString& source,
 296                                       const UnicodeString& target,
 297                                       UErrorCode &status) const;
 298
 299     /**
 300      * Compares a range of character data stored in two different strings based
 301      * on the collation rules up to the specified length. Returns information
 302      * about whether a string is less than, greater than or equal to another
 303      * string in a language. This can be overriden in a subclass.
 304      * @param source the source string.
 305      * @param target the target string to be compared with the source string.
 306      * @param length compares up to the specified length
 307      * @return the comparison result. GREATER if the source string is greater
 308      *         than the target string, LESS if the source is less than the
 309      *         target. Otherwise, returns EQUAL.
 310      * @deprecated ICU 2.6 Use overload with UErrorCode&
 311      */
 312     virtual EComparisonResult compare(const UnicodeString& source,
 313                                       const UnicodeString&  target,
 314                                       int32_t length) const;
 315
 316     /**
 317     * Does the same thing as compare but limits the comparison to a specified
 318     * length
 319     * @param source the source string to be compared with.
 320     * @param target the string that is to be compared with the source string.
 321     * @param length the length the comparison is limited to
 322     * @param status possible error code
 323     * @return Returns an enum value. UCOL_GREATER if source (up to the specified
 324     *         length) is greater than target; UCOL_EQUAL if source (up to specified
 325     *         length) is equal to target; UCOL_LESS if source (up to the specified
 326     *         length) is less  than target.
 327     * @stable ICU 2.6
 328     */
 329     virtual UCollationResult compare(const UnicodeString& source,
 330                                       const UnicodeString& target,
 331                                       int32_t length,
 332                                       UErrorCode &status) const;
 333
 334     /**
 335      * The comparison function compares the character data stored in two
 336      * different string arrays. Returns information about whether a string array
 337      * is less than, greater than or equal to another string array.
 338      * <p>Example of use:
 339      * <pre>
 340      * .       UChar ABC[] = {0x41, 0x42, 0x43, 0};  // = "ABC"
 341      * .       UChar abc[] = {0x61, 0x62, 0x63, 0};  // = "abc"
 342      * .       UErrorCode status = U_ZERO_ERROR;
 343      * .       Collator *myCollation =
 344      * .                         Collator::createInstance(Locale::US, status);
 345      * .       if (U_FAILURE(status)) return;
 346      * .       myCollation->setStrength(Collator::PRIMARY);
 347      * .       // result would be Collator::EQUAL ("abc" == "ABC")
 348      * .       // (no primary difference between "abc" and "ABC")
 349      * .       Collator::EComparisonResult result =
 350      * .                             myCollation->compare(abc, 3, ABC, 3);
 351      * .       myCollation->setStrength(Collator::TERTIARY);
 352      * .       // result would be Collator::LESS ("abc" &lt;&lt;&lt; "ABC")
 353      * .       // (with tertiary difference between "abc" and "ABC")
 354      * .       result =  myCollation->compare(abc, 3, ABC, 3);
 355      * </pre>
 356      * @param source the source string array to be compared with.
 357      * @param sourceLength the length of the source string array. If this value
 358      *        is equal to -1, the string array is null-terminated.
 359      * @param target the string that is to be compared with the source string.
 360      * @param targetLength the length of the target string array. If this value
 361      *        is equal to -1, the string array is null-terminated.
 362      * @return Returns a byte value. GREATER if source is greater than target;
 363      *         EQUAL if source is equal to target; LESS if source is less than
 364      *         target
 365      * @deprecated ICU 2.6 Use overload with UErrorCode&
 366      */
 367     virtual EComparisonResult compare(const UChar* source, int32_t sourceLength,
 368                                       const UChar* target, int32_t targetLength)
 369                                       const;
 370
 371     /**
 372     * The comparison function compares the character data stored in two
 373     * different string arrays. Returns information about whether a string array
 374     * is less than, greater than or equal to another string array.
 375     * @param source the source string array to be compared with.
 376     * @param sourceLength the length of the source string array.  If this value
 377     *        is equal to -1, the string array is null-terminated.
 378     * @param target the string that is to be compared with the source string.
 379     * @param targetLength the length of the target string array.  If this value
 380     *        is equal to -1, the string array is null-terminated.
 381     * @param status possible error code
 382     * @return Returns an enum value. UCOL_GREATER if source is greater
 383     * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less
 384     * than target
 385     * @stable ICU 2.6
 386     */
 387     virtual UCollationResult compare(const UChar* source, int32_t sourceLength,
 388                                       const UChar* target, int32_t targetLength,
 389                                       UErrorCode &status) const;
 390
 391     /**
 392      * Compares two strings using the Collator.
 393      * Returns whether the first one compares less than/equal to/greater than
 394      * the second one.
 395      * This version takes UCharIterator input.
 396      * @param sIter the first ("source") string iterator
 397      * @param tIter the second ("target") string iterator
 398      * @param status ICU status
 399      * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER
 400      * @stable ICU 4.2
 401      */
 402     virtual UCollationResult compare(UCharIterator &sIter,
 403                                      UCharIterator &tIter,
 404                                      UErrorCode &status) const;
 405
 406     /**
 407     * Transforms a specified region of the string into a series of characters
 408     * that can be compared with CollationKey.compare. Use a CollationKey when
 409     * you need to do repeated comparisions on the same string. For a single
 410     * comparison the compare method will be faster.
 411     * @param source the source string.
 412     * @param key the transformed key of the source string.
 413     * @param status the error code status.
 414     * @return the transformed key.
 415     * @see CollationKey
 416     * @deprecated ICU 2.8 Use getSortKey(...) instead
 417     */
 418     virtual CollationKey& getCollationKey(const UnicodeString& source,
 419                                           CollationKey& key,
 420                                           UErrorCode& status) const;
 421
 422     /**
 423     * Transforms a specified region of the string into a series of characters
 424     * that can be compared with CollationKey.compare. Use a CollationKey when
 425     * you need to do repeated comparisions on the same string. For a single
 426     * comparison the compare method will be faster.
 427     * @param source the source string.
 428     * @param sourceLength the length of the source string.
 429     * @param key the transformed key of the source string.
 430     * @param status the error code status.
 431     * @return the transformed key.
 432     * @see CollationKey
 433     * @deprecated ICU 2.8 Use getSortKey(...) instead
 434     */
 435     virtual CollationKey& getCollationKey(const UChar *source,
 436                                           int32_t sourceLength,
 437                                           CollationKey& key,
 438                                           UErrorCode& status) const;
 439
 440     /**
 441      * Generates the hash code for the rule-based collation object.
 442      * @return the hash code.
 443      * @stable ICU 2.0
 444      */
 445     virtual int32_t hashCode(void) const;
 446
 447     /**
 448     * Gets the locale of the Collator
 449     * @param type can be either requested, valid or actual locale. For more
 450     *             information see the definition of ULocDataLocaleType in
 451     *             uloc.h
 452     * @param status the error code status.
 453     * @return locale where the collation data lives. If the collator
 454     *         was instantiated from rules, locale is empty.
 455     * @deprecated ICU 2.8 likely to change in ICU 3.0, based on feedback
 456     */
 457     virtual const Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const;
 458
 459     /**
 460      * Gets the table-based rules for the collation object.
 461      * @return returns the collation rules that the table collation object was
 462      *         created from.
 463      * @stable ICU 2.0
 464      */
 465     const UnicodeString& getRules(void) const;
 466
 467     /**
 468      * Gets the version information for a Collator.
 469      * @param info the version # information, the result will be filled in
 470      * @stable ICU 2.0
 471      */
 472     virtual void getVersion(UVersionInfo info) const;
 473
 474     /**
 475      * Return the maximum length of any expansion sequences that end with the
 476      * specified comparison order.
 477      * @param order a collation order returned by previous or next.
 478      * @return maximum size of the expansion sequences ending with the collation
 479      *         element or 1 if collation element does not occur at the end of
 480      *         any expansion sequence
 481      * @see CollationElementIterator#getMaxExpansion
 482      * @stable ICU 2.0
 483      */
 484     int32_t getMaxExpansion(int32_t order) const;
 485
 486     /**
 487      * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
 488      * method is to implement a simple version of RTTI, since not all C++
 489      * compilers support genuine RTTI. Polymorphic operator==() and clone()
 490      * methods call this method.
 491      * @return The class ID for this object. All objects of a given class have
 492      *         the same class ID. Objects of other classes have different class
 493      *         IDs.
 494      * @stable ICU 2.0
 495      */
 496     virtual UClassID getDynamicClassID(void) const;
 497
 498     /**
 499      * Returns the class ID for this class. This is useful only for comparing to
 500      * a return value from getDynamicClassID(). For example:
 501      * <pre>
 502      * Base* polymorphic_pointer = createPolymorphicObject();
 503      * if (polymorphic_pointer->getDynamicClassID() ==
 504      *                                          Derived::getStaticClassID()) ...
 505      * </pre>
 506      * @return The class ID for all objects of this class.
 507      * @stable ICU 2.0
 508      */
 509     static UClassID U_EXPORT2 getStaticClassID(void);
 510
 511     /**
 512      * Returns the binary format of the class's rules. The format is that of
 513      * .col files.
 514      * @param length Returns the length of the data, in bytes
 515      * @param status the error code status.
 516      * @return memory, owned by the caller, of size 'length' bytes.
 517      * @stable ICU 2.2
 518      */
 519     uint8_t *cloneRuleData(int32_t &length, UErrorCode &status);
 520
 521
 522     /** Creates a binary image of a collator. This binary image can be stored and
 523     *  later used to instantiate a collator using ucol_openBinary.
 524     *  This API supports preflighting.
 525     *  @param buffer a fill-in buffer to receive the binary image
 526     *  @param capacity capacity of the destination buffer
 527     *  @param status for catching errors
 528     *  @return size of the image
 529     *  @see ucol_openBinary
 530     *  @stable ICU 3.4
 531     */
 532     int32_t cloneBinary(uint8_t *buffer, int32_t capacity, UErrorCode &status);
 533
 534     /**
 535      * Returns current rules. Delta defines whether full rules are returned or
 536      * just the tailoring.
 537      * @param delta one of UCOL_TAILORING_ONLY, UCOL_FULL_RULES.
 538      * @param buffer UnicodeString to store the result rules
 539      * @stable ICU 2.2
 540      */
 541     void getRules(UColRuleOption delta, UnicodeString &buffer);
 542
 543     /**
 544      * Universal attribute setter
 545      * @param attr attribute type
 546      * @param value attribute value
 547      * @param status to indicate whether the operation went on smoothly or there were errors
 548      * @stable ICU 2.2
 549      */
 550     virtual void setAttribute(UColAttribute attr, UColAttributeValue value,
 551                               UErrorCode &status);
 552
 553     /**
 554      * Universal attribute getter.
 555      * @param attr attribute type
 556      * @param status to indicate whether the operation went on smoothly or there were errors
 557      * @return attribute value
 558      * @stable ICU 2.2
 559      */
 560     virtual UColAttributeValue getAttribute(UColAttribute attr,
 561                                             UErrorCode &status);
 562
 563     /**
 564      * Sets the variable top to a collation element value of a string supplied.
 565      * @param varTop one or more (if contraction) UChars to which the variable top should be set
 566      * @param len length of variable top string. If -1 it is considered to be zero terminated.
 567      * @param status error code. If error code is set, the return value is undefined. Errors set by this function are: <br>
 568      *    U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such a contraction<br>
 569      *    U_PRIMARY_TOO_LONG_ERROR if the primary for the variable top has more than two bytes
 570      * @return a 32 bit value containing the value of the variable top in upper 16 bits. Lower 16 bits are undefined
 571      * @stable ICU 2.0
 572      */
 573     virtual uint32_t setVariableTop(const UChar *varTop, int32_t len, UErrorCode &status);
 574
 575     /**
 576      * Sets the variable top to a collation element value of a string supplied.
 577      * @param varTop an UnicodeString size 1 or more (if contraction) of UChars to which the variable top should be set
 578      * @param status error code. If error code is set, the return value is undefined. Errors set by this function are: <br>
 579      *    U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such a contraction<br>
 580      *    U_PRIMARY_TOO_LONG_ERROR if the primary for the variable top has more than two bytes
 581      * @return a 32 bit value containing the value of the variable top in upper 16 bits. Lower 16 bits are undefined
 582      * @stable ICU 2.0
 583      */
 584     virtual uint32_t setVariableTop(const UnicodeString varTop, UErrorCode &status);
 585
 586     /**
 587      * Sets the variable top to a collation element value supplied. Variable top is set to the upper 16 bits.
 588      * Lower 16 bits are ignored.
 589      * @param varTop CE value, as returned by setVariableTop or ucol)getVariableTop
 590      * @param status error code (not changed by function)
 591      * @stable ICU 2.0
 592      */
 593     virtual void setVariableTop(const uint32_t varTop, UErrorCode &status);
 594
 595     /**
 596      * Gets the variable top value of a Collator.
 597      * Lower 16 bits are undefined and should be ignored.
 598      * @param status error code (not changed by function). If error code is set, the return value is undefined.
 599      * @stable ICU 2.0
 600      */
 601     virtual uint32_t getVariableTop(UErrorCode &status) const;
 602
 603     /**
 604      * Get an 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 UCA. 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      * Thread safe cloning operation.
 616      * @return pointer to the new clone, user should remove it.
 617      * @stable ICU 2.2
 618      */
 619     virtual Collator* safeClone(void);
 620
 621     /**
 622      * Get the sort key as an array of bytes from an UnicodeString.
 623      * @param source string to be processed.
 624      * @param result buffer to store result in. If NULL, number of bytes needed
 625      *        will be returned.
 626      * @param resultLength length of the result buffer. If if not enough the
 627      *        buffer will be filled to capacity.
 628      * @return Number of bytes needed for storing the sort key
 629      * @stable ICU 2.0
 630      */
 631     virtual int32_t getSortKey(const UnicodeString& source, uint8_t *result,
 632                                int32_t resultLength) const;
 633
 634     /**
 635      * Get the sort key as an array of bytes from an UChar buffer.
 636      * @param source string to be processed.
 637      * @param sourceLength length of string to be processed. If -1, the string
 638      *        is 0 terminated and length will be decided by the function.
 639      * @param result buffer to store result in. If NULL, number of bytes needed
 640      *        will be returned.
 641      * @param resultLength length of the result buffer. If if not enough the
 642      *        buffer will be filled to capacity.
 643      * @return Number of bytes needed for storing the sort key
 644      * @stable ICU 2.2
 645      */
 646     virtual int32_t getSortKey(const UChar *source, int32_t sourceLength,
 647                                uint8_t *result, int32_t resultLength) const;
 648
 649     /**
 650     * Determines the minimum strength that will be use in comparison or
 651     * transformation.
 652     * <p>E.g. with strength == SECONDARY, the tertiary difference is ignored
 653     * <p>E.g. with strength == PRIMARY, the secondary and tertiary difference
 654     * are ignored.
 655     * @return the current comparison level.
 656     * @see RuleBasedCollator#setStrength
 657     * @deprecated ICU 2.6 Use getAttribute(UCOL_STRENGTH...) instead
 658     */
 659     virtual ECollationStrength getStrength(void) const;
 660
 661     /**
 662     * Sets the minimum strength to be used in comparison or transformation.
 663     * @see RuleBasedCollator#getStrength
 664     * @param newStrength the new comparison level.
 665     * @deprecated ICU 2.6 Use setAttribute(UCOL_STRENGTH...) instead
 666     */
 667     virtual void setStrength(ECollationStrength newStrength);
 668
 669     /**
 670      * Get the current reordering of scripts (if one has been set).
 671      * @param dest The array to fill with the script ordering.
 672      * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
 673      * @param pErrorCode Must be a valid pointer to an error code value, which must not indicate a failure before the function call.
 674      * @return The length of the array of the script ordering.
 675      * @see ucol_getReorderCodes
 676      * @internal
 677      */
 678     virtual int32_t getReorderCodes(int32_t* dest,
 679                                     int32_t destCapacity,
 680                                     UErrorCode& status) const;
 681
 682     /**
 683      * Set the ordering of scripts for this collator.
 684      * @param reorderCodes An array of script codes in the new order.
 685      * @param reorderCodesLength The length of reorderCodes.
 686      * @see ucol_setReorderCodes
 687      * @internal
 688      */
 689     virtual void setReorderCodes(const int32_t* reorderCodes,
 690                                  int32_t reorderCodesLength,
 691                                  UErrorCode& status);
 692
 693
 694 private:
 695
 696     // private static constants -----------------------------------------------
 697
 698     enum {
 699         /* need look up in .commit() */
 700         CHARINDEX = 0x70000000,
 701         /* Expand index follows */
 702         EXPANDCHARINDEX = 0x7E000000,
 703         /* contract indexes follows */
 704         CONTRACTCHARINDEX = 0x7F000000,
 705         /* unmapped character values */
 706         UNMAPPED = 0xFFFFFFFF,
 707         /* primary strength increment */
 708         PRIMARYORDERINCREMENT = 0x00010000,
 709         /* secondary strength increment */
 710         SECONDARYORDERINCREMENT = 0x00000100,
 711         /* tertiary strength increment */
 712         TERTIARYORDERINCREMENT = 0x00000001,
 713         /* mask off anything but primary order */
 714         PRIMARYORDERMASK = 0xffff0000,
 715         /* mask off anything but secondary order */
 716         SECONDARYORDERMASK = 0x0000ff00,
 717         /* mask off anything but tertiary order */
 718         TERTIARYORDERMASK = 0x000000ff,
 719         /* mask off ignorable char order */
 720         IGNORABLEMASK = 0x0000ffff,
 721         /* use only the primary difference */
 722         PRIMARYDIFFERENCEONLY = 0xffff0000,
 723         /* use only the primary and secondary difference */
 724         SECONDARYDIFFERENCEONLY = 0xffffff00,
 725         /* primary order shift */
 726         PRIMARYORDERSHIFT = 16,
 727         /* secondary order shift */
 728         SECONDARYORDERSHIFT = 8,
 729         /* starting value for collation elements */
 730         COLELEMENTSTART = 0x02020202,
 731         /* testing mask for primary low element */
 732         PRIMARYLOWZEROMASK = 0x00FF0000,
 733         /* reseting value for secondaries and tertiaries */
 734         RESETSECONDARYTERTIARY = 0x00000202,
 735         /* reseting value for tertiaries */
 736         RESETTERTIARY = 0x00000002,
 737
 738         PRIMIGNORABLE = 0x0202
 739     };
 740
 741     // private data members ---------------------------------------------------
 742
 743     UBool dataIsOwned;
 744
 745     UBool isWriteThroughAlias;
 746
 747     /**
 748     * c struct for collation. All initialisation for it has to be done through
 749     * setUCollator().
 750     */
 751     UCollator *ucollator;
 752
 753     /**
 754     * Rule UnicodeString
 755     */
 756     UnicodeString urulestring;
 757
 758     // friend classes --------------------------------------------------------
 759
 760     /**
 761     * Used to iterate over collation elements in a character source.
 762     */
 763     friend class CollationElementIterator;
 764
 765     /**
 766     * Collator ONLY needs access to RuleBasedCollator(const Locale&,
 767     *                                                       UErrorCode&)
 768     */
 769     friend class Collator;
 770
 771     /**
 772     * Searching over collation elements in a character source
 773     */
 774     friend class StringSearch;
 775
 776     // private constructors --------------------------------------------------
 777
 778     /**
 779      * Default constructor
 780      */
 781     RuleBasedCollator();
 782
 783     /**
 784      * RuleBasedCollator constructor. This constructor takes a locale. The
 785      * only caller of this class should be Collator::createInstance(). If
 786      * createInstance() happens to know that the requested locale's collation is
 787      * implemented as a RuleBasedCollator, it can then call this constructor.
 788      * OTHERWISE IT SHOULDN'T, since this constructor ALWAYS RETURNS A VALID
 789      * COLLATION TABLE. It does this by falling back to defaults.
 790      * @param desiredLocale locale used
 791      * @param status error code status
 792      */
 793     RuleBasedCollator(const Locale& desiredLocale, UErrorCode& status);
 794
 795     /**
 796      * common constructor implementation
 797      *
 798      * @param rules the collation rules to build the collation table from.
 799      * @param collationStrength default strength for comparison
 800      * @param decompositionMode the normalisation mode
 801      * @param status reporting a success or an error.
 802      */
 803     void
 804     construct(const UnicodeString& rules,
 805               UColAttributeValue collationStrength,
 806               UColAttributeValue decompositionMode,
 807               UErrorCode& status);
 808
 809     // private methods -------------------------------------------------------
 810
 811     /**
 812     * Creates the c struct for ucollator
 813     * @param locale desired locale
 814     * @param status error status
 815     */
 816     void setUCollator(const Locale& locale, UErrorCode& status);
 817
 818     /**
 819     * Creates the c struct for ucollator
 820     * @param locale desired locale name
 821     * @param status error status
 822     */
 823     void setUCollator(const char* locale, UErrorCode& status);
 824
 825     /**
 826     * Creates the c struct for ucollator. This used internally by StringSearch.
 827     * Hence the responsibility of cleaning up the ucollator is not done by
 828     * this RuleBasedCollator. The isDataOwned flag is set to FALSE.
 829     * @param collator new ucollator data
 830     * @param rules corresponding collation rules
 831     */
 832     void setUCollator(UCollator *collator);
 833
 834 public:
 835     /**
 836     * Get UCollator data struct. Used only by StringSearch & intltest.
 837     * @return UCollator data struct
 838     * @internal
 839     */
 840     const UCollator * getUCollator();
 841
 842 protected:
 843    /**
 844     * Used internally by registraton to define the requested and valid locales.
 845     * @param requestedLocale the requsted locale
 846     * @param validLocale the valid locale
 847     * @param actualLocale the actual locale
 848     * @internal
 849     */
 850     virtual void setLocales(const Locale& requestedLocale, const Locale& validLocale, const Locale& actualLocale);
 851
 852 private:
 853
 854     // if not owned and not a write through alias, copy the ucollator
 855     void checkOwned(void);
 856
 857     // utility to init rule string used by checkOwned and construct
 858     void setRuleStringFromCollator();
 859
 860     /**
 861     * Converts C's UCollationResult to EComparisonResult
 862     * @param result member of the enum UComparisonResult
 863     * @return EComparisonResult equivalent of UCollationResult
 864     * @deprecated ICU 2.6. We will not need it.
 865     */
 866     Collator::EComparisonResult getEComparisonResult(
 867                                             const UCollationResult &result) const;
 868
 869     /**
 870     * Converts C's UCollationStrength to ECollationStrength
 871     * @param strength member of the enum UCollationStrength
 872     * @return ECollationStrength equivalent of UCollationStrength
 873     */
 874     Collator::ECollationStrength getECollationStrength(
 875                                         const UCollationStrength &strength) const;
 876
 877     /**
 878     * Converts C++'s ECollationStrength to UCollationStrength
 879     * @param strength member of the enum ECollationStrength
 880     * @return UCollationStrength equivalent of ECollationStrength
 881     */
 882     UCollationStrength getUCollationStrength(
 883       const Collator::ECollationStrength &strength) const;
 884 };
 885
 886 // inline method implementation ---------------------------------------------
 887
 888 inline void RuleBasedCollator::setUCollator(const Locale &locale,
 889                                                UErrorCode &status)
 890 {
 891     setUCollator(locale.getName(), status);
 892 }
 893
 894
 895 inline void RuleBasedCollator::setUCollator(UCollator     *collator)
 896 {
 897
 898     if (ucollator && dataIsOwned) {
 899         ucol_close(ucollator);
 900     }
 901     ucollator   = collator;
 902     dataIsOwned = FALSE;
 903     isWriteThroughAlias = TRUE;
 904     setRuleStringFromCollator();
 905 }
 906
 907 inline const UCollator * RuleBasedCollator::getUCollator()
 908 {
 909     return ucollator;
 910 }
 911
 912 inline Collator::EComparisonResult RuleBasedCollator::getEComparisonResult(
 913                                            const UCollationResult &result) const
 914 {
 915     switch (result)
 916     {
 917     case UCOL_LESS :
 918         return Collator::LESS;
 919     case UCOL_EQUAL :
 920         return Collator::EQUAL;
 921     default :
 922         return Collator::GREATER;
 923     }
 924 }
 925
 926 inline Collator::ECollationStrength RuleBasedCollator::getECollationStrength(
 927                                        const UCollationStrength &strength) const
 928 {
 929     switch (strength)
 930     {
 931     case UCOL_PRIMARY :
 932         return Collator::PRIMARY;
 933     case UCOL_SECONDARY :
 934         return Collator::SECONDARY;
 935     case UCOL_TERTIARY :
 936         return Collator::TERTIARY;
 937     case UCOL_QUATERNARY :
 938         return Collator::QUATERNARY;
 939     default :
 940         return Collator::IDENTICAL;
 941     }
 942 }
 943
 944 inline UCollationStrength RuleBasedCollator::getUCollationStrength(
 945                              const Collator::ECollationStrength &strength) const
 946 {
 947     switch (strength)
 948     {
 949     case Collator::PRIMARY :
 950         return UCOL_PRIMARY;
 951     case Collator::SECONDARY :
 952         return UCOL_SECONDARY;
 953     case Collator::TERTIARY :
 954         return UCOL_TERTIARY;
 955     case Collator::QUATERNARY :
 956         return UCOL_QUATERNARY;
 957     default :
 958         return UCOL_IDENTICAL;
 959     }
 960 }
 961
 962 U_NAMESPACE_END
 963
 964 #endif /* #if !UCONFIG_NO_COLLATION */
 965
 966 #endif