16f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org/* 26f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org ***************************************************************************** 36f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Copyright (C) 1996-2013, International Business Machines Corporation and others. 46f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * All Rights Reserved. 56f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org ***************************************************************************** 66f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * 76f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * File sortkey.h 86f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * 96f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Created by: Helena Shih 106f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * 116f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Modification History: 126f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * 136f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Date Name Description 146f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * 156f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * 6/20/97 helena Java class name change. 166f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * 8/18/97 helena Added internal API documentation. 176f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * 6/26/98 erm Changed to use byte arrays and memcmp. 186f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org ***************************************************************************** 196f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 206f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 216f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org#ifndef SORTKEY_H 226f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org#define SORTKEY_H 236f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 246f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org#include "unicode/utypes.h" 256f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 266f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org/** 276f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * \file 286f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * \brief C++ API: Keys for comparing strings multiple times. 296f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 306f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 316f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org#if !UCONFIG_NO_COLLATION 326f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 336f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org#include "unicode/uobject.h" 346f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org#include "unicode/unistr.h" 356f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org#include "unicode/coll.h" 366f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 376f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.orgU_NAMESPACE_BEGIN 386f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 396f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org/* forward declaration */ 406f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.orgclass RuleBasedCollator; 416f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 426f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org/** 436f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * 446f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Collation keys are generated by the Collator class. Use the CollationKey objects 456f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * instead of Collator to compare strings multiple times. A CollationKey 466f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * preprocesses the comparison information from the Collator object to 476f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * make the comparison faster. If you are not going to comparing strings 486f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * multiple times, then using the Collator object is generally faster, 496f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * since it only processes as much of the string as needed to make a 506f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * comparison. 516f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * <p> For example (with strength == tertiary) 526f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * <p>When comparing "Abernathy" to "Baggins-Smythworthy", Collator 536f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * only needs to process a couple of characters, while a comparison 546f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * with CollationKeys will process all of the characters. On the other hand, 556f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * if you are doing a sort of a number of fields, it is much faster to use 566f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * CollationKeys, since you will be comparing strings multiple times. 576f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * <p>Typical use of CollationKeys are in databases, where you store a CollationKey 586f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * in a hidden field, and use it for sorting or indexing. 596f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * 606f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * <p>Example of use: 616f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * <pre> 626f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * \code 636f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * UErrorCode success = U_ZERO_ERROR; 646f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Collator* myCollator = Collator::createInstance(success); 656f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * CollationKey* keys = new CollationKey [3]; 666f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * myCollator->getCollationKey("Tom", keys[0], success ); 676f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * myCollator->getCollationKey("Dick", keys[1], success ); 686f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * myCollator->getCollationKey("Harry", keys[2], success ); 696f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * 706f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * // Inside body of sort routine, compare keys this way: 716f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * CollationKey tmp; 726f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * if(keys[0].compareTo( keys[1] ) > 0 ) { 736f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * tmp = keys[0]; keys[0] = keys[1]; keys[1] = tmp; 746f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * } 756f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * //... 766f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * \endcode 776f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * </pre> 786f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * <p>Because Collator::compare()'s algorithm is complex, it is faster to sort 796f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * long lists of words by retrieving collation keys with Collator::getCollationKey(). 806f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * You can then cache the collation keys and compare them using CollationKey::compareTo(). 816f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * <p> 826f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * <strong>Note:</strong> <code>Collator</code>s with different Locale, 836f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * CollationStrength and DecompositionMode settings will return different 846f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * CollationKeys for the same set of strings. Locales have specific 856f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * collation rules, and the way in which secondary and tertiary differences 866f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * are taken into account, for example, will result in different CollationKeys 876f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * for same strings. 886f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * <p> 896f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 906f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @see Collator 916f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @see RuleBasedCollator 926f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @version 1.3 12/18/96 936f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @author Helena Shih 946f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.0 956f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 966f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.orgclass U_I18N_API CollationKey : public UObject { 976f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.orgpublic: 986f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 996f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * This creates an empty collation key based on the null string. An empty 1006f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * collation key contains no sorting information. When comparing two empty 1016f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * collation keys, the result is Collator::EQUAL. Comparing empty collation key 1026f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * with non-empty collation key is always Collator::LESS. 1036f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.0 1046f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 1056f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org CollationKey(); 1066f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 1076f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 1086f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 1096f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Creates a collation key based on the collation key values. 1106f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @param values the collation key values 1116f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @param count number of collation key values, including trailing nulls. 1126f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.0 1136f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 1146f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org CollationKey(const uint8_t* values, 1156f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org int32_t count); 1166f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 1176f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 1186f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Copy constructor. 1196f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @param other the object to be copied. 1206f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.0 1216f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 1226f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org CollationKey(const CollationKey& other); 1236f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 1246f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 1256f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Sort key destructor. 1266f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.0 1276f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 1286f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org virtual ~CollationKey(); 1296f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 1306f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 1316f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Assignment operator 1326f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @param other the object to be copied. 1336f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.0 1346f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 1356f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org const CollationKey& operator=(const CollationKey& other); 1366f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 1376f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 1386f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Compare if two collation keys are the same. 1396f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @param source the collation key to compare to. 1406f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @return Returns true if two collation keys are equal, false otherwise. 1416f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.0 1426f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 1436f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org UBool operator==(const CollationKey& source) const; 1446f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 1456f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 1466f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Compare if two collation keys are not the same. 1476f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @param source the collation key to compare to. 1486f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @return Returns TRUE if two collation keys are different, FALSE otherwise. 1496f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.0 1506f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 1516f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org UBool operator!=(const CollationKey& source) const; 1526f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 1536f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 1546f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 1556f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Test to see if the key is in an invalid state. The key will be in an 1566f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * invalid state if it couldn't allocate memory for some operation. 1576f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @return Returns TRUE if the key is in an invalid, FALSE otherwise. 1586f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.0 1596f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 1606f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org UBool isBogus(void) const; 1616f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 1626f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 1636f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Returns a pointer to the collation key values. The storage is owned 1646f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * by the collation key and the pointer will become invalid if the key 1656f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * is deleted. 1666f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @param count the output parameter of number of collation key values, 1676f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * including any trailing nulls. 1686f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @return a pointer to the collation key values. 1696f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.0 1706f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 1716f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org const uint8_t* getByteArray(int32_t& count) const; 1726f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 1736f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org#ifdef U_USE_COLLATION_KEY_DEPRECATES 1746f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 1756f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Extracts the collation key values into a new array. The caller owns 1766f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * this storage and should free it. 1776f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @param count the output parameter of number of collation key values, 1786f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * including any trailing nulls. 1796f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @obsolete ICU 2.6. Use getByteArray instead since this API will be removed in that release. 1806f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 1816f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org uint8_t* toByteArray(int32_t& count) const; 1826f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org#endif 1836f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 1846f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org#ifndef U_HIDE_DEPRECATED_API 1856f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 1866f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Convenience method which does a string(bit-wise) comparison of the 1876f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * two collation keys. 1886f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @param target target collation key to be compared with 1896f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @return Returns Collator::LESS if sourceKey < targetKey, 1906f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Collator::GREATER if sourceKey > targetKey and Collator::EQUAL 1916f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * otherwise. 1926f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @deprecated ICU 2.6 use the overload with error code 1936f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 1946f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org Collator::EComparisonResult compareTo(const CollationKey& target) const; 1956f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org#endif /* U_HIDE_DEPRECATED_API */ 1966f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 1976f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 1986f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Convenience method which does a string(bit-wise) comparison of the 1996f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * two collation keys. 2006f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @param target target collation key to be compared with 2016f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @param status error code 2026f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @return Returns UCOL_LESS if sourceKey < targetKey, 2036f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * UCOL_GREATER if sourceKey > targetKey and UCOL_EQUAL 2046f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * otherwise. 2056f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.6 2066f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 2076f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org UCollationResult compareTo(const CollationKey& target, UErrorCode &status) const; 2086f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 2096f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 2106f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Creates an integer that is unique to the collation key. NOTE: this 2116f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * is not the same as String.hashCode. 2126f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * <p>Example of use: 2136f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * <pre> 2146f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * . UErrorCode status = U_ZERO_ERROR; 2156f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * . Collator *myCollation = Collator::createInstance(Locale::US, status); 2166f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * . if (U_FAILURE(status)) return; 2176f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * . CollationKey key1, key2; 2186f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * . UErrorCode status1 = U_ZERO_ERROR, status2 = U_ZERO_ERROR; 2196f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * . myCollation->getCollationKey("abc", key1, status1); 2206f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * . if (U_FAILURE(status1)) { delete myCollation; return; } 2216f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * . myCollation->getCollationKey("ABC", key2, status2); 2226f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * . if (U_FAILURE(status2)) { delete myCollation; return; } 2236f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * . // key1.hashCode() != key2.hashCode() 2246f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * </pre> 2256f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @return the hash value based on the string's collation order. 2266f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @see UnicodeString#hashCode 2276f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.0 2286f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 2296f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org int32_t hashCode(void) const; 2306f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 2316f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 2326f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * ICU "poor man's RTTI", returns a UClassID for the actual class. 2336f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.2 2346f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 2356f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org virtual UClassID getDynamicClassID() const; 2366f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 2376f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 2386f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * ICU "poor man's RTTI", returns a UClassID for this class. 2396f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @stable ICU 2.2 2406f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 2416f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org static UClassID U_EXPORT2 getStaticClassID(); 2426f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 2436f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.orgprivate: 2446f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 2456f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Replaces the current bytes buffer with a new one of newCapacity 2466f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * and copies length bytes from the old buffer to the new one. 2476f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @return the new buffer, or NULL if the allocation failed 2486f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 2496f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org uint8_t *reallocate(int32_t newCapacity, int32_t length); 2506f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 2516f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Set a new length for a new sort key in the existing fBytes. 2526f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 2536f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org void setLength(int32_t newLength); 2546f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 2556f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org uint8_t *getBytes() { 2566f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org return (fFlagAndLength >= 0) ? fUnion.fStackBuffer : fUnion.fFields.fBytes; 2576f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org } 2586f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org const uint8_t *getBytes() const { 2596f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org return (fFlagAndLength >= 0) ? fUnion.fStackBuffer : fUnion.fFields.fBytes; 2606f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org } 2616f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org int32_t getCapacity() const { 2626f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org return (fFlagAndLength >= 0) ? (int32_t)sizeof(fUnion) : fUnion.fFields.fCapacity; 2636f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org } 2646f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org int32_t getLength() const { return fFlagAndLength & 0x7fffffff; } 2656f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 2666f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 2676f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Set the CollationKey to a "bogus" or invalid state 2686f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @return this CollationKey 2696f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 2706f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org CollationKey& setToBogus(void); 2716f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 2726f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Resets this CollationKey to an empty state 2736f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * @return this CollationKey 2746f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 2756f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org CollationKey& reset(void); 2766f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 2776f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 2786f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Allow private access to RuleBasedCollator 2796f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 2806f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org friend class RuleBasedCollator; 2816f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org friend class CollationKeyByteSink; 2826f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 2836f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org // Class fields. sizeof(CollationKey) is intended to be 48 bytes 2846f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org // on a machine with 64-bit pointers. 2856f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org // We use a union to maximize the size of the internal buffer, 2866f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org // similar to UnicodeString but not as tight and complex. 2876f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 2886f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org // (implicit) *vtable; 2896f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 2906f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Sort key length and flag. 2916f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Bit 31 is set if the buffer is heap-allocated. 2926f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Bits 30..0 contain the sort key length. 2936f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 2946f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org int32_t fFlagAndLength; 2956f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 2966f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Unique hash value of this CollationKey. 2976f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * Special value 2 if the key is bogus. 2986f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 2996f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org mutable int32_t fHashCode; 3006f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** 3016f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * fUnion provides 32 bytes for the internal buffer or for 3026f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org * pointer+capacity. 3036f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org */ 3046f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org union StackBufferOrFields { 3056f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org /** fStackBuffer is used iff fFlagAndLength>=0, else fFields is used */ 3066f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org uint8_t fStackBuffer[32]; 3076f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org struct { 3086f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org uint8_t *fBytes; 3096f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org int32_t fCapacity; 3106f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org } fFields; 3116f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org } fUnion; 3126f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org}; 3136f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 3146f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.orginline UBool 3156f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.orgCollationKey::operator!=(const CollationKey& other) const 3166f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org{ 3176f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org return !(*this == other); 3186f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org} 3196f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 3206f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.orginline UBool 3216f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.orgCollationKey::isBogus() const 3226f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org{ 3236f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org return fHashCode == 2; // kBogusHashCode 3246f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org} 3256f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 3266f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.orginline const uint8_t* 3276f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.orgCollationKey::getByteArray(int32_t &count) const 3286f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org{ 3296f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org count = getLength(); 3306f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org return getBytes(); 3316f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org} 3326f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 3336f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.orgU_NAMESPACE_END 3346f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 3356f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org#endif /* #if !UCONFIG_NO_COLLATION */ 3366f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org 3376f31ac30b9092fd02a8c97e5216cf53f3e4fae4jshin@chromium.org#endif 338