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

## Static Public Member Functions

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

## 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:

    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;
    }
    //...
    icu::CollationKey::compareToCollator::EComparisonResult compareTo(const CollationKey &target) constConvenience method which does a string(bit-wise) comparison of the two collation keys.
    icu::CollationKey::CollationKeyCollationKey()This creates an empty collation key based on the null string.
    icu::CollatorThe Collator class performs locale-sensitive string comparison.Definition coll.h:173
    icu::Collator::createInstancestatic Collator * createInstance(UErrorCode &err)Creates the Collator object for the current default locale.
    icu::Collator::getCollationKeyvirtual CollationKey & getCollationKey(const UnicodeString &source, CollationKey &key, UErrorCode &status) const =0Transforms the string into a series of characters that can be compared with CollationKey::compareTo.
    UErrorCodeUErrorCodeStandard ICU4C error code type, a substitute for exceptions.Definition utypes.h:509
    U_ZERO_ERROR@ U_ZERO_ERRORNo error, no warning.Definition utypes.h:544

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: `Collator`s 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

Referenced by CollationKey(), compareTo(), compareTo(), operator!=(), operator=(), and operator==().

## 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

References CollationKey().

## ~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

References CollationKey().

## 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

  target | target collation key to be compared with
  status | error code

Returns
  Returns UCOL_LESS if sourceKey < targetKey, UCOL_GREATER if sourceKey > targetKey and UCOL_EQUAL otherwise.

Stable
  ICU 2.6

References CollationKey().

## 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

  count | the 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 332 of file sortkey.h.

References getByteArray().

Referenced by getByteArray(), and operator==().

## getDynamicClassID()

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

override virtual

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

Stable
  ICU 2.2

Reimplemented from icu::UObject.

## getStaticClassID()

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 | ( |  | ) | 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 | ( |  | ) | 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 326 of file sortkey.h.

References isBogus().

Referenced by isBogus(), and operator==().

## operator!=()

bool icu::CollationKey::operator!= | ( | const CollationKey & | source | ) | const

inline

Compare if two collation keys are not the same.

Parameters

  source | the collation key to compare to.

Returns
  Returns true if two collation keys are different, false otherwise.

Stable
  ICU 2.0

Definition at line 320 of file sortkey.h.

References CollationKey(), and operator!=().

Referenced by operator!=().

## operator=()

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

Assignment operator.

Parameters

  other | the object to be copied.

Stable
  ICU 2.0

References CollationKey().

## operator==()

bool icu::CollationKey::operator== | ( | const CollationKey & | source | ) | const

Compare if two collation keys are the same.

Parameters

  source | the collation key to compare to.

Returns
  Returns true if two collation keys are equal, false otherwise.

Stable
  ICU 2.0

References CollationKey(), getByteArray(), and isBogus().

## Friends And Related Symbol Documentation

## CollationKeyByteSink

friend class CollationKeyByteSink

friend

Definition at line 286 of file sortkey.h.

## RuleBasedCollator

friend class RuleBasedCollator

friend

Allow private access to RuleBasedCollator.

Definition at line 285 of file sortkey.h.

References RuleBasedCollator.

Referenced by RuleBasedCollator.

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

- i18n/unicode/sortkey.h