Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Search  

CollationKey Class Reference

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

#include <sortkey.h>

Inheritance diagram for CollationKey::

UObject UMemory List of all members.

Public Methods

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

 ~CollationKey ()
 Sort key destructor. More...

const CollationKey & operator= (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_tgetByteArray (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...


Static Public Methods

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


Private Methods

void adopt (uint8_t *values, int32_t count)
 Returns an array of the collation key values as 16-bit integers. More...

CollationKey & ensureCapacity (int32_t newSize)
 If this CollationKey has capacity less than newSize, its internal capacity will be increased to newSize. More...

CollationKey & setToBogus (void)
 Set the CollationKey to a "bogus" or invalid state. More...

CollationKey & reset (void)
 Resets this CollationKey to an empty state. More...


Private Attributes

UBool fBogus
 Bogus status. More...

int32_t fCount
 Size of fBytes used to store the sortkey. More...

int32_t fCapacity
 Full size of the fBytes. More...

int32_t fHashCode
 Unique hash value of this CollationKey. More...

uint8_tfBytes
 Array to store the sortkey. More...


Static Private Attributes

const char fgClassID
 The address of this static class variable serves as this class's ID for ICU "poor man's RTTI". More...


Friends

class RuleBasedCollator
 Allow private access to RuleBasedCollator. More...


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

Definition at line 90 of file sortkey.h.


Constructor & Destructor Documentation

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::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.
See also:
createBits
Stable:
ICU 2.0

CollationKey::CollationKey const CollationKey &    other
 

Copy constructor.

Parameters:
other  the object to be copied.
Stable:
ICU 2.0

CollationKey::~CollationKey  
 

Sort key destructor.

Stable:
ICU 2.0


Member Function Documentation

void CollationKey::adopt uint8_t   values,
int32_t    count
[private]
 

Returns an array of the collation key values as 16-bit integers.

The caller owns the storage and must delete it.

Parameters:
values  Output param of the collation key values.
count  output parameter of the number of collation key values
Returns:
a pointer to an array of 16-bit collation key values.

UCollationResult 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.
Draft:
This API has been introduced in ICU 2.6. It is still in draft state and may be modified in a future release.

Collator::EComparisonResult 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

CollationKey& CollationKey::ensureCapacity int32_t    newSize [private]
 

If this CollationKey has capacity less than newSize, its internal capacity will be increased to newSize.

Parameters:
newSize  minimum size this CollationKey has to have
Returns:
this CollationKey

const uint8_t * 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 324 of file sortkey.h.

UClassID CollationKey::getDynamicClassID void    const [inline, virtual]
 

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

Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

Reimplemented from UObject.

Definition at line 308 of file sortkey.h.

UClassID CollationKey::getStaticClassID void    [inline, static]
 

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

Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

Definition at line 304 of file sortkey.h.

Referenced by getDynamicClassID().

int32_t 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

UBool 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 318 of file sortkey.h.

UBool CollationKey::operator!= const CollationKey &    other 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 312 of file sortkey.h.

const CollationKey& CollationKey::operator= const CollationKey &    other
 

Assignment operator.

Parameters:
other  the object to be copied.
Stable:
ICU 2.0

UBool 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

CollationKey& CollationKey::reset void    [private]
 

Resets this CollationKey to an empty state.

Returns:
this CollationKey

CollationKey& CollationKey::setToBogus void    [private]
 

Set the CollationKey to a "bogus" or invalid state.

Returns:
this CollationKey


Friends And Related Function Documentation

friend class RuleBasedCollator [friend]
 

Allow private access to RuleBasedCollator.

Stable:
ICU 2.0

Definition at line 273 of file sortkey.h.


Member Data Documentation

UBool CollationKey::fBogus [private]
 

Bogus status.

Definition at line 277 of file sortkey.h.

uint8_t* CollationKey::fBytes [private]
 

Array to store the sortkey.

Definition at line 294 of file sortkey.h.

int32_t CollationKey::fCapacity [private]
 

Full size of the fBytes.

Definition at line 286 of file sortkey.h.

int32_t CollationKey::fCount [private]
 

Size of fBytes used to store the sortkey.

i.e. up till the null-termination.

Definition at line 282 of file sortkey.h.

int32_t CollationKey::fHashCode [private]
 

Unique hash value of this CollationKey.

Definition at line 290 of file sortkey.h.

const char CollationKey::fgClassID [static, private]
 

The address of this static class variable serves as this class's ID for ICU "poor man's RTTI".

Definition at line 300 of file sortkey.h.


The documentation for this class was generated from the following file:
Generated on Thu Jun 12 13:10:54 2003 for ICU 2.6 by doxygen1.2.11.1 written by Dimitri van Heesch, © 1997-2001