icuSources/i18n/unicode/sortkey.h

   1 /*
   2  * Copyright (C) 1996-2004, International Business Machines Corporation and others.
   3  * All Rights Reserved.
   4  *****************************************************************************************
   5  *
   6  * File sortkey.h
   7  *
   8  * Created by: Helena Shih
   9  *
  10  * Modification History:
  11  *
  12  *  Date         Name          Description
  13  *
  14  *  6/20/97     helena      Java class name change.
  15  *  8/18/97     helena      Added internal API documentation.
  16  *  6/26/98     erm         Changed to use byte arrays and memcmp.
  17  *****************************************************************************************
  18  */
  19
  20 #ifndef SORTKEY_H
  21 #define SORTKEY_H
  22
  23 #include "unicode/utypes.h"
  24
  25 #if !UCONFIG_NO_COLLATION
  26
  27 #include "unicode/uobject.h"
  28 #include "unicode/unistr.h"
  29 #include "unicode/coll.h"
  30
  31 U_NAMESPACE_BEGIN
  32
  33 /* forward declaration */
  34 class RuleBasedCollator;
  35
  36 /**
  37  * Collation keys are generated by the Collator class.  Use the CollationKey objects
  38  * instead of Collator to compare strings multiple times.  A CollationKey
  39  * preprocesses the comparison information from the Collator object to
  40  * make the comparison faster.  If you are not going to comparing strings
  41  * multiple times, then using the Collator object is generally faster,
  42  * since it only processes as much of the string as needed to make a
  43  * comparison.
  44  * <p> For example (with strength == tertiary)
  45  * <p>When comparing "Abernathy" to "Baggins-Smythworthy", Collator
  46  * only needs to process a couple of characters, while a comparison
  47  * with CollationKeys will process all of the characters.  On the other hand,
  48  * if you are doing a sort of a number of fields, it is much faster to use
  49  * CollationKeys, since you will be comparing strings multiple times.
  50  * <p>Typical use of CollationKeys are in databases, where you store a CollationKey
  51  * in a hidden field, and use it for sorting or indexing.
  52  *
  53  * <p>Example of use:
  54  * <pre>
  55  * \code
  56  *     UErrorCode success = U_ZERO_ERROR;
  57  *     Collator* myCollator = Collator::createInstance(success);
  58  *     CollationKey* keys = new CollationKey [3];
  59  *     myCollator->getCollationKey("Tom", keys[0], success );
  60  *     myCollator->getCollationKey("Dick", keys[1], success );
  61  *     myCollator->getCollationKey("Harry", keys[2], success );
  62  *
  63  *     // Inside body of sort routine, compare keys this way:
  64  *     CollationKey tmp;
  65  *     if(keys[0].compareTo( keys[1] ) > 0 ) {
  66  *         tmp = keys[0]; keys[0] = keys[1]; keys[1] = tmp;
  67  *     }
  68  *     //...
  69  * \endcode
  70  * </pre>
  71  * <p>Because Collator::compare()'s algorithm is complex, it is faster to sort
  72  * long lists of words by retrieving collation keys with Collator::getCollationKey().
  73  * You can then cache the collation keys and compare them using CollationKey::compareTo().
  74  * <p>
  75  * <strong>Note:</strong> <code>Collator</code>s with different Locale,
  76  * CollationStrength and DecompositionMode settings will return different
  77  * CollationKeys for the same set of strings. Locales have specific
  78  * collation rules, and the way in which secondary and tertiary differences
  79  * are taken into account, for example, will result in different CollationKeys
  80  * for same strings.
  81  * <p>
  82
  83  * @see          Collator
  84  * @see          RuleBasedCollator
  85  * @version      1.3 12/18/96
  86  * @author       Helena Shih
  87  * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
  88  */
  89 class U_I18N_API CollationKey : public UObject {
  90 public:
  91     /**
  92     * This creates an empty collation key based on the null string.  An empty
  93     * collation key contains no sorting information.  When comparing two empty
  94     * collation keys, the result is Collator::EQUAL.  Comparing empty collation key
  95     * with non-empty collation key is always Collator::LESS.
  96     * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
  97     */
  98     CollationKey();
  99
 100
 101     /**
 102     * Creates a collation key based on the collation key values.
 103     * @param values the collation key values
 104     * @param count number of collation key values, including trailing nulls.
 105     * @see #createBits
 106     * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
 107     */
 108     CollationKey(const  uint8_t*    values,
 109                 int32_t     count);
 110
 111     /**
 112     * Copy constructor.
 113     * @param other    the object to be copied.
 114     * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
 115     */
 116     CollationKey(const CollationKey& other);
 117
 118     /**
 119     * Sort key destructor.
 120     * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
 121     */
 122     virtual ~CollationKey();
 123
 124     /**
 125     * Assignment operator
 126     * @param other    the object to be copied.
 127     * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
 128     */
 129     const   CollationKey&   operator=(const CollationKey& other);
 130
 131     /**
 132     * Compare if two collation keys are the same.
 133     * @param source the collation key to compare to.
 134     * @return Returns true if two collation keys are equal, false otherwise.
 135     * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
 136     */
 137     UBool                   operator==(const CollationKey& source) const;
 138
 139     /**
 140     * Compare if two collation keys are not the same.
 141     * @param source the collation key to compare to.
 142     * @return Returns TRUE if two collation keys are different, FALSE otherwise.
 143     * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
 144     */
 145     UBool                   operator!=(const CollationKey& source) const;
 146
 147
 148     /**
 149     * Test to see if the key is in an invalid state. The key will be in an
 150     * invalid state if it couldn't allocate memory for some operation.
 151     * @return Returns TRUE if the key is in an invalid, FALSE otherwise.
 152     * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
 153     */
 154     UBool                   isBogus(void) const;
 155
 156     /**
 157     * Returns a pointer to the collation key values. The storage is owned
 158     * by the collation key and the pointer will become invalid if the key
 159     * is deleted.
 160     * @param count the output parameter of number of collation key values,
 161     * including any trailing nulls.
 162     * @return a pointer to the collation key values.
 163     * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
 164     */
 165     const    uint8_t*       getByteArray(int32_t& count) const;
 166
 167 #ifdef U_USE_COLLATION_KEY_DEPRECATES
 168     /**
 169     * Extracts the collation key values into a new array. The caller owns
 170     * this storage and should free it.
 171     * @param count the output parameter of number of collation key values,
 172     * including any trailing nulls.
 173     * @obsolete ICU 2.6. Use getByteArray instead since this API will be removed in that release.
 174     */
 175     uint8_t*                toByteArray(int32_t& count) const;
 176 #endif
 177
 178     /**
 179     * Convenience method which does a string(bit-wise) comparison of the
 180     * two collation keys.
 181     * @param target target collation key to be compared with
 182     * @return Returns Collator::LESS if sourceKey &lt; targetKey,
 183     * Collator::GREATER if sourceKey > targetKey and Collator::EQUAL
 184     * otherwise.
 185     * @deprecated ICU 2.6 use the overload with error code
 186     */
 187     Collator::EComparisonResult compareTo(const CollationKey& target) const;
 188
 189     /**
 190     * Convenience method which does a string(bit-wise) comparison of the
 191     * two collation keys.
 192     * @param target target collation key to be compared with
 193     * @param status error code
 194     * @return Returns UCOL_LESS if sourceKey &lt; targetKey,
 195     * UCOL_GREATER if sourceKey > targetKey and UCOL_EQUAL
 196     * otherwise.
 197     * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
 198     */
 199     UCollationResult compareTo(const CollationKey& target, UErrorCode &status) const;
 200
 201     /**
 202     * Creates an integer that is unique to the collation key.  NOTE: this
 203     * is not the same as String.hashCode.
 204     * <p>Example of use:
 205     * <pre>
 206     * .    UErrorCode status = U_ZERO_ERROR;
 207     * .    Collator *myCollation = Collator::createInstance(Locale::US, status);
 208     * .    if (U_FAILURE(status)) return;
 209     * .    CollationKey key1, key2;
 210     * .    UErrorCode status1 = U_ZERO_ERROR, status2 = U_ZERO_ERROR;
 211     * .    myCollation->getCollationKey("abc", key1, status1);
 212     * .    if (U_FAILURE(status1)) { delete myCollation; return; }
 213     * .    myCollation->getCollationKey("ABC", key2, status2);
 214     * .    if (U_FAILURE(status2)) { delete myCollation; return; }
 215     * .    // key1.hashCode() != key2.hashCode()
 216     * </pre>
 217     * @return the hash value based on the string's collation order.
 218     * @see UnicodeString#hashCode
 219     * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
 220     */
 221     int32_t                 hashCode(void) const;
 222
 223     /**
 224      * ICU "poor man's RTTI", returns a UClassID for the actual class.
 225      * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
 226      */
 227     virtual UClassID getDynamicClassID() const;
 228
 229     /**
 230      * ICU "poor man's RTTI", returns a UClassID for this class.
 231      * @deprecated ICU 2.8 Use Collator::getSortKey(...) instead
 232      */
 233     static UClassID U_EXPORT2 getStaticClassID();
 234
 235 private:
 236     /**
 237     * Returns an array of the collation key values as 16-bit integers.
 238     * The caller owns the storage and must delete it.
 239     * @param values Output param of the collation key values.
 240     * @param count output parameter of the number of collation key values
 241     * @return a pointer to an array of 16-bit collation key values.
 242     */
 243     void adopt(uint8_t *values, int32_t count);
 244
 245     /*
 246     * Creates a collation key with a string.
 247     */
 248
 249     /**
 250     * If this CollationKey has capacity less than newSize,
 251     * its internal capacity will be increased to newSize.
 252     * @param newSize minimum size this CollationKey has to have
 253     * @return this CollationKey
 254     */
 255     CollationKey&           ensureCapacity(int32_t newSize);
 256     /**
 257     * Set the CollationKey to a "bogus" or invalid state
 258     * @return this CollationKey
 259     */
 260     CollationKey&           setToBogus(void);
 261     /**
 262     * Resets this CollationKey to an empty state
 263     * @return this CollationKey
 264     */
 265     CollationKey&           reset(void);
 266
 267     /**
 268     * Allow private access to RuleBasedCollator
 269     */
 270     friend  class           RuleBasedCollator;
 271     /**
 272     * Bogus status
 273     */
 274     UBool                   fBogus;
 275     /**
 276     * Size of fBytes used to store the sortkey. i.e. up till the
 277     * null-termination.
 278     */
 279     int32_t                 fCount;
 280     /**
 281     * Full size of the fBytes
 282     */
 283     int32_t                 fCapacity;
 284     /**
 285     * Unique hash value of this CollationKey
 286     */
 287     int32_t                 fHashCode;
 288     /**
 289     * Array to store the sortkey
 290     */
 291     uint8_t*                fBytes;
 292
 293 };
 294
 295 inline UBool
 296 CollationKey::operator!=(const CollationKey& other) const
 297 {
 298     return !(*this == other);
 299 }
 300
 301 inline UBool
 302 CollationKey::isBogus() const
 303 {
 304     return fBogus;
 305 }
 306
 307 inline const uint8_t*
 308 CollationKey::getByteArray(int32_t &count) const
 309 {
 310     count = fCount;
 311     return fBytes;
 312 }
 313
 314 U_NAMESPACE_END
 315
 316 #endif /* #if !UCONFIG_NO_COLLATION */
 317
 318 #endif