icu::CollationKey Class Reference

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

#include <sortkey.h>

Inheritance diagram for icu::CollationKey:

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 CollationKey &	operator= (const CollationKey &other)
	Assignment operator. More...
bool	operator== (const CollationKey &source) const
	Compare if two collation keys are the same. More...
bool	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 override
	ICU "poor man's RTTI", returns a UClassID for the actual class. More...
Public Member Functions inherited from icu::UObject
virtual	~UObject ()
	Destructor. More...
virtual UClassID	getDynamicClassID () const
	ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class. 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. More...
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:

UErrorCode success = U_ZERO_ERROR;
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:
CollationKey tmp;
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 101 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

values	the collation key values
count	number of collation key values, including trailing nulls.

Stable:

ICU 2.0

CollationKey() [3/3]

icu::CollationKey::CollationKey

(

const CollationKey &

other

)

Copy constructor.

Parameters

other

the 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

target

target 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 &