ICU 59.1  59.1
Data Structures | Public Member Functions | Static Public Member Functions | Friends
icu::CollationKey Class Reference

Collation keys are generated by the Collator class. More...

#include <sortkey.h>

Inheritance diagram for icu::CollationKey:
icu::UObject icu::UMemory

Public Member Functions

 CollationKey ()
 This creates an empty collation key based on the null string. More...
 
 CollationKey (const uint8_t *values, int32_t count)
 Creates a collation key based on the collation key values. More...
 
 CollationKey (const CollationKey &other)
 Copy constructor. More...
 
virtual ~CollationKey ()
 Sort key destructor. More...
 
const CollationKeyoperator= (const CollationKey &other)
 Assignment operator. More...
 
UBool operator== (const CollationKey &source) const
 Compare if two collation keys are the same. More...
 
UBool operator!= (const CollationKey &source) const
 Compare if two collation keys are not the same. More...
 
UBool isBogus (void) const
 Test to see if the key is in an invalid state. More...
 
const uint8_t * getByteArray (int32_t &count) const
 Returns a pointer to the collation key values. More...
 
Collator::EComparisonResult compareTo (const CollationKey &target) const
 Convenience method which does a string(bit-wise) comparison of the two collation keys. More...
 
UCollationResult compareTo (const CollationKey &target, UErrorCode &status) const
 Convenience method which does a string(bit-wise) comparison of the two collation keys. More...
 
int32_t hashCode (void) const
 Creates an integer that is unique to the collation key. More...
 
virtual UClassID getDynamicClassID () const
 ICU "poor man's RTTI", returns a UClassID for the actual class. More...
 
- Public Member Functions inherited from icu::UObject
virtual ~UObject ()
 Destructor. More...
 

Static Public Member Functions

static UClassID getStaticClassID ()
 ICU "poor man's RTTI", returns a UClassID for this class. More...
 

Friends

class RuleBasedCollator
 Allow private access to RuleBasedCollator.
 
class CollationKeyByteSink
 

Detailed Description

Collation keys are generated by the Collator class.

Use the CollationKey objects instead of Collator to compare strings multiple times. A CollationKey preprocesses the comparison information from the Collator object to make the comparison faster. If you are not going to comparing strings multiple times, then using the Collator object is generally faster, since it only processes as much of the string as needed to make a comparison.

For example (with strength == tertiary)

When comparing "Abernathy" to "Baggins-Smythworthy", Collator only needs to process a couple of characters, while a comparison with CollationKeys will process all of the characters. On the other hand, if you are doing a sort of a number of fields, it is much faster to use CollationKeys, since you will be comparing strings multiple times.

Typical use of CollationKeys are in databases, where you store a CollationKey in a hidden field, and use it for sorting or indexing.

Example of use:

Collator* myCollator = Collator::createInstance(success);
CollationKey* keys = new CollationKey [3];
myCollator->getCollationKey("Tom", keys[0], success );
myCollator->getCollationKey("Dick", keys[1], success );
myCollator->getCollationKey("Harry", keys[2], success );
// Inside body of sort routine, compare keys this way:
if(keys[0].compareTo( keys[1] ) > 0 ) {
tmp = keys[0]; keys[0] = keys[1]; keys[1] = tmp;
}
//...

Because Collator::compare()'s algorithm is complex, it is faster to sort long lists of words by retrieving collation keys with Collator::getCollationKey(). You can then cache the collation keys and compare them using CollationKey::compareTo().

Note: Collators with different Locale, CollationStrength and DecompositionMode settings will return different CollationKeys for the same set of strings. Locales have specific collation rules, and the way in which secondary and tertiary differences are taken into account, for example, will result in different CollationKeys for same strings.

See also
Collator
RuleBasedCollator
Version
1.3 12/18/96
Author
Helena Shih
Stable:
ICU 2.0

Definition at line 99 of file sortkey.h.

Constructor & Destructor Documentation

§ CollationKey() [1/3]

icu::CollationKey::CollationKey ( )

This creates an empty collation key based on the null string.

An empty collation key contains no sorting information. When comparing two empty collation keys, the result is Collator::EQUAL. Comparing empty collation key with non-empty collation key is always Collator::LESS.

Stable:
ICU 2.0

§ CollationKey() [2/3]

icu::CollationKey::CollationKey ( const uint8_t *  values,
int32_t  count 
)

Creates a collation key based on the collation key values.

Parameters
valuesthe collation key values
countnumber of collation key values, including trailing nulls.
Stable:
ICU 2.0

§ CollationKey() [3/3]

icu::CollationKey::CollationKey ( const CollationKey other)

Copy constructor.

Parameters
otherthe object to be copied.
Stable:
ICU 2.0

§ ~CollationKey()

virtual icu::CollationKey::~CollationKey ( )
virtual

Sort key destructor.

Stable:
ICU 2.0

Member Function Documentation

§ compareTo() [1/2]

Collator::EComparisonResult icu::CollationKey::compareTo ( const CollationKey target) const

Convenience method which does a string(bit-wise) comparison of the two collation keys.

Parameters
targettarget collation key to be compared with
Returns
Returns Collator::LESS if sourceKey < targetKey, Collator::GREATER if sourceKey > targetKey and Collator::EQUAL otherwise.
Deprecated:
ICU 2.6 use the overload with error code

§ compareTo() [2/2]

UCollationResult icu::CollationKey::compareTo ( const CollationKey target,
UErrorCode status 
) const

Convenience method which does a string(bit-wise) comparison of the two collation keys.

Parameters
targettarget collation key to be compared with
statuserror code
Returns
Returns UCOL_LESS if sourceKey < targetKey, UCOL_GREATER if sourceKey > targetKey and UCOL_EQUAL otherwise.
Stable:
ICU 2.6

§ getByteArray()

const uint8_t * icu::CollationKey::getByteArray ( int32_t &  count) const
inline

Returns a pointer to the collation key values.

The storage is owned by the collation key and the pointer will become invalid if the key is deleted.

Parameters
countthe output parameter of number of collation key values, including any trailing nulls.
Returns
a pointer to the collation key values.
Stable:
ICU 2.0

Definition at line 330 of file sortkey.h.

References U_NAMESPACE_END.

§ getDynamicClassID()

virtual UClassID icu::CollationKey::getDynamicClassID ( ) const
virtual

ICU "poor man's RTTI", returns a UClassID for the actual class.

Stable:
ICU 2.2

Reimplemented from icu::UObject.

§ getStaticClassID()

static UClassID icu::CollationKey::getStaticClassID ( )
static

ICU "poor man's RTTI", returns a UClassID for this class.

Stable:
ICU 2.2

§ hashCode()

int32_t icu::CollationKey::hashCode ( void  ) const

Creates an integer that is unique to the collation key.

NOTE: this is not the same as String.hashCode.

Example of use:

.    UErrorCode status = U_ZERO_ERROR;
.    Collator *myCollation = Collator::createInstance(Locale::US, status);
.    if (U_FAILURE(status)) return;
.    CollationKey key1, key2;
.    UErrorCode status1 = U_ZERO_ERROR, status2 = U_ZERO_ERROR;
.    myCollation->getCollationKey("abc", key1, status1);
.    if (U_FAILURE(status1)) { delete myCollation; return; }
.    myCollation->getCollationKey("ABC", key2, status2);
.    if (U_FAILURE(status2)) { delete myCollation; return; }
.    // key1.hashCode() != key2.hashCode()
Returns
the hash value based on the string's collation order.
See also
UnicodeString::hashCode
Stable:
ICU 2.0

§ isBogus()

UBool icu::CollationKey::isBogus ( void  ) const
inline

Test to see if the key is in an invalid state.

The key will be in an invalid state if it couldn't allocate memory for some operation.

Returns
Returns TRUE if the key is in an invalid, FALSE otherwise.
Stable:
ICU 2.0

Definition at line 324 of file sortkey.h.

§ operator!=()

UBool icu::CollationKey::operator!= ( const CollationKey source) const
inline

Compare if two collation keys are not the same.

Parameters
sourcethe collation key to compare to.
Returns
Returns TRUE if two collation keys are different, FALSE otherwise.
Stable:
ICU 2.0

Definition at line 318 of file sortkey.h.

§ operator=()

const CollationKey& icu::CollationKey::operator= ( const CollationKey other)

Assignment operator.

Parameters
otherthe object to be copied.
Stable:
ICU 2.0

§ operator==()

UBool icu::CollationKey::operator== ( const CollationKey source) const

Compare if two collation keys are the same.

Parameters
sourcethe collation key to compare to.
Returns
Returns true if two collation keys are equal, false otherwise.
Stable:
ICU 2.0

The documentation for this class was generated from the following file: