1ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru/* 2ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru ***************************************************************************** 3fceb39872958b9fa2505e63f8b8699a9e0f882f4ccornelius * Copyright (C) 1996-2014, International Business Machines Corporation and others. 4ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * All Rights Reserved. 5ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru ***************************************************************************** 6ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * 7ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * File sortkey.h 8ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * 9ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Created by: Helena Shih 10ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * 11ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Modification History: 12ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * 13ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Date Name Description 14ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * 15ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * 6/20/97 helena Java class name change. 16ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * 8/18/97 helena Added internal API documentation. 17ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * 6/26/98 erm Changed to use byte arrays and memcmp. 18ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru ***************************************************************************** 19ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 20ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 21ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru#ifndef SORTKEY_H 22ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru#define SORTKEY_H 23ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 24ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru#include "unicode/utypes.h" 25ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 26ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru/** 27ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * \file 28ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * \brief C++ API: Keys for comparing strings multiple times. 29ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 30ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 31ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru#if !UCONFIG_NO_COLLATION 32ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 33ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru#include "unicode/uobject.h" 34ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru#include "unicode/unistr.h" 35ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru#include "unicode/coll.h" 36ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 37ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste QueruU_NAMESPACE_BEGIN 38ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 39ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru/* forward declaration */ 40ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queruclass RuleBasedCollator; 41fceb39872958b9fa2505e63f8b8699a9e0f882f4ccorneliusclass CollationKeyByteSink; 42ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 43ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru/** 44ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * 45ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Collation keys are generated by the Collator class. Use the CollationKey objects 46ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * instead of Collator to compare strings multiple times. A CollationKey 47ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * preprocesses the comparison information from the Collator object to 48ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * make the comparison faster. If you are not going to comparing strings 49ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * multiple times, then using the Collator object is generally faster, 50ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * since it only processes as much of the string as needed to make a 51ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * comparison. 52ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * <p> For example (with strength == tertiary) 53ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * <p>When comparing "Abernathy" to "Baggins-Smythworthy", Collator 54ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * only needs to process a couple of characters, while a comparison 55ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * with CollationKeys will process all of the characters. On the other hand, 56ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * if you are doing a sort of a number of fields, it is much faster to use 57ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * CollationKeys, since you will be comparing strings multiple times. 58ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * <p>Typical use of CollationKeys are in databases, where you store a CollationKey 59ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * in a hidden field, and use it for sorting or indexing. 60ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * 61ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * <p>Example of use: 62ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * <pre> 63ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * \code 64ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * UErrorCode success = U_ZERO_ERROR; 65ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Collator* myCollator = Collator::createInstance(success); 66ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * CollationKey* keys = new CollationKey [3]; 67ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * myCollator->getCollationKey("Tom", keys[0], success ); 68ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * myCollator->getCollationKey("Dick", keys[1], success ); 69ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * myCollator->getCollationKey("Harry", keys[2], success ); 70ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * 71ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * // Inside body of sort routine, compare keys this way: 72ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * CollationKey tmp; 73ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * if(keys[0].compareTo( keys[1] ) > 0 ) { 74ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * tmp = keys[0]; keys[0] = keys[1]; keys[1] = tmp; 75ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * } 76ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * //... 77ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * \endcode 78ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * </pre> 79ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * <p>Because Collator::compare()'s algorithm is complex, it is faster to sort 80ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * long lists of words by retrieving collation keys with Collator::getCollationKey(). 81ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * You can then cache the collation keys and compare them using CollationKey::compareTo(). 82ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * <p> 83ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * <strong>Note:</strong> <code>Collator</code>s with different Locale, 84ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * CollationStrength and DecompositionMode settings will return different 85ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * CollationKeys for the same set of strings. Locales have specific 86ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * collation rules, and the way in which secondary and tertiary differences 87ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * are taken into account, for example, will result in different CollationKeys 88ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * for same strings. 89ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * <p> 90ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 91ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @see Collator 92ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @see RuleBasedCollator 93ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @version 1.3 12/18/96 94ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @author Helena Shih 9554dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.0 96ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 97ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queruclass U_I18N_API CollationKey : public UObject { 98ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Querupublic: 99ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 100ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * This creates an empty collation key based on the null string. An empty 101ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * collation key contains no sorting information. When comparing two empty 102ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * collation keys, the result is Collator::EQUAL. Comparing empty collation key 103ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * with non-empty collation key is always Collator::LESS. 10454dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.0 105ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 106ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru CollationKey(); 107ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 108ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 109ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 110ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Creates a collation key based on the collation key values. 111ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @param values the collation key values 112ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @param count number of collation key values, including trailing nulls. 11354dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.0 114ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 115ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru CollationKey(const uint8_t* values, 116ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru int32_t count); 117ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 118ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 119ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Copy constructor. 120ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @param other the object to be copied. 12154dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.0 122ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 123ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru CollationKey(const CollationKey& other); 124ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 125ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 126ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Sort key destructor. 12754dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.0 128ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 129ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru virtual ~CollationKey(); 130ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 131ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 132ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Assignment operator 133ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @param other the object to be copied. 13454dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.0 135ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 136ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru const CollationKey& operator=(const CollationKey& other); 137ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 138ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 139ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Compare if two collation keys are the same. 140ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @param source the collation key to compare to. 141ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @return Returns true if two collation keys are equal, false otherwise. 14254dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.0 143ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 144ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru UBool operator==(const CollationKey& source) const; 145ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 146ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 147ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Compare if two collation keys are not the same. 148ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @param source the collation key to compare to. 149ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @return Returns TRUE if two collation keys are different, FALSE otherwise. 15054dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.0 151ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 152ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru UBool operator!=(const CollationKey& source) const; 153ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 154ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 155ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 156ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Test to see if the key is in an invalid state. The key will be in an 157ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * invalid state if it couldn't allocate memory for some operation. 158ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @return Returns TRUE if the key is in an invalid, FALSE otherwise. 15954dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.0 160ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 161ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru UBool isBogus(void) const; 162ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 163ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 164ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Returns a pointer to the collation key values. The storage is owned 165ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * by the collation key and the pointer will become invalid if the key 166ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * is deleted. 167ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @param count the output parameter of number of collation key values, 168ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * including any trailing nulls. 169ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @return a pointer to the collation key values. 17054dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.0 171ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 172ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru const uint8_t* getByteArray(int32_t& count) const; 173ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 174ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru#ifdef U_USE_COLLATION_KEY_DEPRECATES 175ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 176ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Extracts the collation key values into a new array. The caller owns 177ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * this storage and should free it. 178ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @param count the output parameter of number of collation key values, 179ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * including any trailing nulls. 180ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @obsolete ICU 2.6. Use getByteArray instead since this API will be removed in that release. 181ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 182ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru uint8_t* toByteArray(int32_t& count) const; 183ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru#endif 184ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 1858393335b955da7340c9f19b1b4b2d6c0c2c04be7Craig Cornelius#ifndef U_HIDE_DEPRECATED_API 186ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 187ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Convenience method which does a string(bit-wise) comparison of the 188ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * two collation keys. 189ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @param target target collation key to be compared with 190ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @return Returns Collator::LESS if sourceKey < targetKey, 191ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Collator::GREATER if sourceKey > targetKey and Collator::EQUAL 192ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * otherwise. 193ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @deprecated ICU 2.6 use the overload with error code 194ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 195ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru Collator::EComparisonResult compareTo(const CollationKey& target) const; 1968393335b955da7340c9f19b1b4b2d6c0c2c04be7Craig Cornelius#endif /* U_HIDE_DEPRECATED_API */ 197ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 198ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 199ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Convenience method which does a string(bit-wise) comparison of the 200ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * two collation keys. 201ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @param target target collation key to be compared with 202ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @param status error code 203ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @return Returns UCOL_LESS if sourceKey < targetKey, 204ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * UCOL_GREATER if sourceKey > targetKey and UCOL_EQUAL 205ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * otherwise. 20654dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.6 207ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 208ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru UCollationResult compareTo(const CollationKey& target, UErrorCode &status) const; 209ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 210ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 211ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Creates an integer that is unique to the collation key. NOTE: this 212ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * is not the same as String.hashCode. 213ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * <p>Example of use: 214ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * <pre> 215ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * . UErrorCode status = U_ZERO_ERROR; 216ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * . Collator *myCollation = Collator::createInstance(Locale::US, status); 217ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * . if (U_FAILURE(status)) return; 218ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * . CollationKey key1, key2; 219ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * . UErrorCode status1 = U_ZERO_ERROR, status2 = U_ZERO_ERROR; 220ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * . myCollation->getCollationKey("abc", key1, status1); 221ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * . if (U_FAILURE(status1)) { delete myCollation; return; } 222ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * . myCollation->getCollationKey("ABC", key2, status2); 223ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * . if (U_FAILURE(status2)) { delete myCollation; return; } 224ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * . // key1.hashCode() != key2.hashCode() 225ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * </pre> 226ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @return the hash value based on the string's collation order. 227ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @see UnicodeString#hashCode 22854dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.0 229ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 230ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru int32_t hashCode(void) const; 231ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 232ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 233ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * ICU "poor man's RTTI", returns a UClassID for the actual class. 23454dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.2 235ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 236ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru virtual UClassID getDynamicClassID() const; 237ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 238ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 239ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * ICU "poor man's RTTI", returns a UClassID for this class. 24054dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @stable ICU 2.2 241ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 242ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru static UClassID U_EXPORT2 getStaticClassID(); 243ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 244ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queruprivate: 245ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 24654dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * Replaces the current bytes buffer with a new one of newCapacity 24754dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * and copies length bytes from the old buffer to the new one. 24854dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @return the new buffer, or NULL if the allocation failed 24954dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius */ 25054dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius uint8_t *reallocate(int32_t newCapacity, int32_t length); 251b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** 252b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * Set a new length for a new sort key in the existing fBytes. 253b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho */ 254b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho void setLength(int32_t newLength); 255ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 25654dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius uint8_t *getBytes() { 25754dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius return (fFlagAndLength >= 0) ? fUnion.fStackBuffer : fUnion.fFields.fBytes; 25854dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius } 25954dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius const uint8_t *getBytes() const { 26054dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius return (fFlagAndLength >= 0) ? fUnion.fStackBuffer : fUnion.fFields.fBytes; 26154dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius } 26254dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius int32_t getCapacity() const { 26354dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius return (fFlagAndLength >= 0) ? (int32_t)sizeof(fUnion) : fUnion.fFields.fCapacity; 26454dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius } 26554dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius int32_t getLength() const { return fFlagAndLength & 0x7fffffff; } 266ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 267ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 268ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Set the CollationKey to a "bogus" or invalid state 269ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @return this CollationKey 270ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 271ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru CollationKey& setToBogus(void); 272ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 273ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Resets this CollationKey to an empty state 274ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * @return this CollationKey 275ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 276ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru CollationKey& reset(void); 27754dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius 278ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 279ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru * Allow private access to RuleBasedCollator 280ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 281ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru friend class RuleBasedCollator; 28254dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius friend class CollationKeyByteSink; 28354dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius 28454dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius // Class fields. sizeof(CollationKey) is intended to be 48 bytes 28554dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius // on a machine with 64-bit pointers. 28654dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius // We use a union to maximize the size of the internal buffer, 28754dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius // similar to UnicodeString but not as tight and complex. 28854dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius 28954dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius // (implicit) *vtable; 290ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 29154dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * Sort key length and flag. 29254dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * Bit 31 is set if the buffer is heap-allocated. 29354dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * Bits 30..0 contain the sort key length. 29454dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius */ 29554dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius int32_t fFlagAndLength; 296ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 29754dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * Unique hash value of this CollationKey. 29854dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * Special value 2 if the key is bogus. 299ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru */ 30054dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius mutable int32_t fHashCode; 301ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru /** 30254dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * fUnion provides 32 bytes for the internal buffer or for 30354dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * pointer+capacity. 30454dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius */ 30554dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius union StackBufferOrFields { 30654dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius /** fStackBuffer is used iff fFlagAndLength>=0, else fFields is used */ 30754dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius uint8_t fStackBuffer[32]; 30854dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius struct { 30954dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius uint8_t *fBytes; 31054dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius int32_t fCapacity; 31154dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius } fFields; 31254dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius } fUnion; 313ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru}; 314ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 315ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queruinline UBool 316ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste QueruCollationKey::operator!=(const CollationKey& other) const 317ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru{ 318ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru return !(*this == other); 319ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru} 320ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 321ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queruinline UBool 322ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste QueruCollationKey::isBogus() const 323ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru{ 32454dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius return fHashCode == 2; // kBogusHashCode 325ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru} 326ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 327ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queruinline const uint8_t* 328ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste QueruCollationKey::getByteArray(int32_t &count) const 329ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru{ 33054dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius count = getLength(); 33154dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius return getBytes(); 332ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru} 333ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 334ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste QueruU_NAMESPACE_END 335ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 336ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru#endif /* #if !UCONFIG_NO_COLLATION */ 337ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru 338ac04d0bbe12b3ef54518635711412f178cb4d16Jean-Baptiste Queru#endif 339