home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 6 / AACD06.ISO / AACD / Programming / ICU / include / sortkey.h < prev    next >
C/C++ Source or Header  |  1999-11-12  |  10KB  |  255 lines
  1. /*
  2. *****************************************************************************************
  3. *                                                                                       *
  4. * COPYRIGHT:                                                                            *
  5. *   (C) Copyright Taligent, Inc.,  1996                                                 *
  6. *   (C) Copyright International Business Machines Corporation,  1996-1999               *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.                  *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure             *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                              *
  10. *                                                                                       *
  11. *****************************************************************************************
  12. */
  13. //===============================================================================
  14. //
  15. // File sortkey.h
  16. //
  17. // 
  18. //
  19. // Created by: Helena Shih
  20. //
  21. // Modification History:
  22. //
  23. //  Date         Name          Description
  24. //
  25. //  6/20/97     helena      Java class name change.
  26. //  8/18/97     helena      Added internal API documentation.
  27. //  6/26/98     erm         Changed to use byte arrays and memcmp. 
  28. //===============================================================================
  29.  
  30. #ifndef SORTKEY_H
  31. #define SORTKEY_H
  32.  
  33.  
  34. #include "utypes.h"
  35. #include "unistr.h"
  36. #include "coll.h"
  37.  
  38.  
  39. /**
  40.  * Collation keys are generated by the Collator class.  Use the CollationKey objects
  41.  * instead of Collator to compare strings multiple times.  A CollationKey
  42.  * preprocesses the comparison information from the Collator object to
  43.  * make the comparison faster.  If you are not going to comparing strings
  44.  * multiple times, then using the Collator object is generally faster,
  45.  * since it only processes as much of the string as needed to make a
  46.  * comparison.
  47.  * <p> For example (with strength == tertiary)
  48.  * <p>When comparing "Abernathy" to "Baggins-Smythworthy", Collator
  49.  * only needs to process a couple of characters, while a comparison
  50.  * with CollationKeys will process all of the characters.  On the other hand,
  51.  * if you are doing a sort of a number of fields, it is much faster to use
  52.  * CollationKeys, since you will be comparing strings multiple times.
  53.  * <p>Typical use of CollationKeys are in databases, where you store a CollationKey
  54.  * in a hidden field, and use it for sorting or indexing.
  55.  *
  56.  * <p>Example of use:
  57.  * <pre>
  58.  * .    UErrorCode success = U_ZERO_ERROR;
  59.  * .    Collator* myCollator = Collator::createInstance(success);
  60.  * .    CollationKey* keys = new CollationKey [3];
  61.  * .    myCollator->getCollationKey("Tom", keys[0], success );
  62.  * .    myCollator->getCollationKey("Dick", keys[1], success );
  63.  * .    myCollator->getCollationKey("Harry", keys[2], success );
  64.  * . 
  65.  * .    // Inside body of sort routine, compare keys this way:
  66.  * .    CollationKey tmp;
  67.  * .    if(keys[0].compareTo( keys[1] ) > 0 ) {
  68.  * .        tmp = keys[0]; keys[0] = keys[1]; keys[1] = tmp;
  69.  * .    }
  70.  * .    //...
  71.  * </pre>
  72.  * <p>Because Collator::compare()'s algorithm is complex, it is faster to sort
  73.  * long lists of words by retrieving collation keys with Collator::getCollationKey().
  74.  * You can then cache the collation keys and compare them using CollationKey::compareTo().
  75.  * <p>
  76.  * <strong>Note:</strong> <code>Collator</code>s with different Locale,
  77.  * CollationStrength and DecompositionMode settings will return different
  78.  * CollationKeys for the same set of strings. Locales have specific 
  79.  * collation rules, and the way in which secondary and tertiary differences 
  80.  * are taken into account, for example, will result in different CollationKeys
  81.  * for same strings.
  82.  * <p>
  83.  
  84.  * @see          Collator
  85.  * @see          RuleBasedCollator
  86.  * @version      1.3 12/18/96
  87.  * @author       Helena Shih
  88.  */
  89. class U_I18N_API CollationKey {
  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.      */
  97.                                     CollationKey();
  98.     /**
  99.      * Creates a collation key based on the collation key values.  
  100.      * @param values the collation key values
  101.      * @param count number of collation key values, including trailing nulls.
  102.      * @see #createBits
  103.      */
  104.                                     CollationKey(const  uint8_t*    values,
  105.                                                         int32_t     count);
  106.  
  107.     /**
  108.      * Copy constructor.
  109.      */
  110.                                     CollationKey(const CollationKey& other);
  111.     /** 
  112.      * Sort key destructor.
  113.      */
  114.                                     ~CollationKey();
  115.  
  116.     /**
  117.      * Assignment operator
  118.      */
  119.     const   CollationKey&           operator=(const CollationKey& other);
  120.  
  121.     /**
  122.      * Compare if two collation keys are the same.
  123.      * @param source the collation key to compare to.
  124.      * @return Returns true if two collation keys are equal, false otherwise.
  125.      */
  126.             bool_t                  operator==(const CollationKey& source) const;
  127.  
  128.     /**
  129.      * Compare if two collation keys are not the same.
  130.      * @param source the collation key to compare to.
  131.      * @return Returns TRUE if two collation keys are different, FALSE otherwise.
  132.      */
  133.             bool_t                  operator!=(const CollationKey& source) const;
  134.  
  135.  
  136.     /**
  137.      * Test to see if the key is in an invalid state. The key will be in an
  138.      * invalid state if it couldn't allocate memory for some operation.
  139.      * @return Returns TRUE if the key is in an invalid, FALSE otherwise.
  140.      */
  141.             bool_t                  isBogus(void) const;
  142.  
  143.     /** 
  144.      * Returns a pointer to the collation key values. The storage is owned
  145.      * by the collation key and the pointer will become invalid if the key
  146.      * is deleted.
  147.      * @param count the output parameter of number of collation key values,
  148.      * including any trailing nulls.
  149.      */
  150.    const    uint8_t*                getByteArray(int32_t& count) const;
  151.  
  152.     /** 
  153.      * Extracts the collation key values into a new array. The caller owns
  154.      * this storage and should free it.
  155.      * @param count the output parameter of number of collation key values,
  156.      * including any trailing nulls.
  157.      */
  158.             uint8_t*                toByteArray(int32_t& count) const;
  159.  
  160.     /**
  161.      * Convenience method which does a string(bit-wise) comparison of the
  162.      * two collation keys.
  163.      * @param sourceKey source collation key
  164.      * @param targetKey target collation key
  165.      * @return Returns Collator::LESS if sourceKey < targetKey, 
  166.      * Collator::GREATER if sourceKey > targetKey and Collator::EQUAL
  167.      * otherwise.
  168.      */
  169.     Collator::EComparisonResult    compareTo(const CollationKey& target) const;
  170.  
  171.     /**
  172.      * Creates an integer that is unique to the collation key.  NOTE: this
  173.      * is not the same as String.hashCode.
  174.      * <p>Example of use:
  175.      * <pre>
  176.      * .    UErrorCode status = U_ZERO_ERROR;
  177.      * .    Collator *myCollation = Collator::createInstance(Locale::US, status);
  178.      * .    if (U_FAILURE(status)) return;
  179.      * .    CollationKey key1, key2;
  180.      * .    UErrorCode status1 = U_ZERO_ERROR, status2 = U_ZERO_ERROR;
  181.      * .    myCollation->getCollationKey("abc", key1, status1);
  182.      * .    if (U_FAILURE(status1)) { delete myCollation; return; }
  183.      * .    myCollation->getCollationKey("ABC", key2, status2);
  184.      * .    if (U_FAILURE(status2)) { delete myCollation; return; }
  185.      * .    // key1.hashCode() != key2.hashCode()
  186.      * </pre>
  187.      * @return the hash value based on the string's collation order.
  188.      * @see UnicodeString#hashCode
  189.      */
  190.             int32_t                 hashCode(void) const;
  191.  
  192. private:
  193.     /**
  194.     * Returns an array of the collation key values as 16-bit integers.
  195.     * The caller owns the storage and must delete it.
  196.     * @param size output parameter of the number of collation key values
  197.     * @return a pointer to an array of 16-bit collation key values.
  198.     */
  199.             uint16_t*               copyValues(int32_t &size) const;
  200.  
  201.     /*
  202.      * Creates a collation key with a string.
  203.      */
  204.                                     CollationKey(const UnicodeString& value);
  205.  
  206.             int32_t                 storeBytes(int32_t cursor, uint32_t byteValue);
  207.             int32_t                    storeUnicodeString(int32_t cursor, const UnicodeString &value);
  208.             void                    reverseBytes(int32_t from, int32_t to);
  209.             CollationKey&           ensureCapacity(int32_t newSize);
  210.             CollationKey&           copyUnicodeString(const UnicodeString &value);
  211.             CollationKey&           setToBogus(void);
  212.             CollationKey&           reset(void);
  213.  
  214.     friend  class                   RuleBasedCollator;
  215.  
  216.     static const int32_t            kInvalidHashCode;
  217.     static const int32_t            kEmptyHashCode;
  218.  
  219.             bool_t                  fBogus;
  220.             int32_t                 fCount;
  221.             int32_t                 fCapacity;
  222.             int32_t                 fHashCode;
  223.             uint8_t*                fBytes;
  224. };
  225.  
  226. inline bool_t
  227. CollationKey::operator!=(const CollationKey& other) const
  228. {
  229.     return !(*this == other);
  230. }
  231.  
  232. inline bool_t
  233. CollationKey::isBogus() const
  234. {
  235.     return fBogus;
  236. }
  237.  
  238. inline const uint8_t*
  239. CollationKey::getByteArray(int32_t &count) const
  240. {
  241.     count = fCount;
  242.     return fBytes;
  243. }
  244.  
  245. inline UTextOffset
  246. CollationKey::storeBytes(UTextOffset cursor, uint32_t byteValue)
  247. {
  248.     fBytes[cursor++] = (uint8_t) (byteValue >> 8);
  249.     fBytes[cursor++] = (uint8_t) byteValue;
  250.  
  251.     return cursor;
  252. }
  253.  
  254. #endif
  255.