icuSources/i18n/unicode/tblcoll.h

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