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

CollationKey Class Reference

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

#include <sortkey.h>

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

uint8_ttoByteArray (int32_t& count) const
 Extracts the collation key values into a new array. More...

Collator::EComparisonResult compareTo (const CollationKey& target) 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...


Private Methods

uint16_tcopyValues (int32_t &size) const
 Returns an array of the collation key values as 16-bit integers. More...

void adopt (uint8_t *values, int32_t count)
 CollationKey (int32_t count, uint8_t *values)
 The secret adopting constructor!

 CollationKey (const UnicodeString& value)
int32_t storeBytes (int32_t cursor, uint32_t byteValue)
int32_t storeUnicodeString (int32_t cursor, const UnicodeString &value)
void reverseBytes (int32_t from, int32_t to)
CollationKey& ensureCapacity (int32_t newSize)
CollationKey& copyUnicodeString (const UnicodeString &value)
CollationKey& setToBogus (void)
CollationKey& reset (void)

Private Attributes

UBool fBogus
int32_t fCount
int32_t fCapacity
int32_t fHashCode
uint8_tfBytes

Static Private Attributes

const int32_t kInvalidHashCode
const int32_t kEmptyHashCode

Friends

class  RuleBasedCollator


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(s):
Helena Shih
Deprecated:

Definition at line 86 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.

Deprecated:

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

CollationKey::CollationKey ( const CollationKey & other )
 

Copy constructor.

Deprecated:

CollationKey::~CollationKey ( )
 

Sort key destructor.

Deprecated:

CollationKey::CollationKey ( int32_t count,
uint8_t * values ) [private]
 

The secret adopting constructor!

CollationKey::CollationKey ( const UnicodeString & value ) [private]
 


Member Function Documentation

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

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

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

Parameters:
sourceKey   source collation key
targetKey   target collation key
Returns:
Returns Collator::LESS if sourceKey < targetKey, Collator::GREATER if sourceKey > targetKey and Collator::EQUAL otherwise.
Deprecated:

CollationKey& CollationKey::copyUnicodeString ( const UnicodeString & value ) [private]
 

uint16_t * CollationKey::copyValues ( int32_t & size ) const [private]
 

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

The caller owns the storage and must delete it.

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

CollationKey& CollationKey::ensureCapacity ( int32_t newSize ) [private]
 

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

Definition at line 257 of file sortkey.h.

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

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

Definition at line 251 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.
Deprecated:

Definition at line 245 of file sortkey.h.

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

Assignment operator.

Deprecated:

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

CollationKey& CollationKey::reset ( void ) [private]
 

void CollationKey::reverseBytes ( int32_t from,
int32_t to ) [private]
 

CollationKey& CollationKey::setToBogus ( void ) [private]
 

int32_t CollationKey::storeBytes ( int32_t cursor,
uint32_t byteValue ) [private]
 

int32_t CollationKey::storeUnicodeString ( int32_t cursor,
const UnicodeString & value ) [private]
 

uint8_t * CollationKey::toByteArray ( int32_t & count ) const
 

Extracts the collation key values into a new array.

The caller owns this storage and should free it.

Parameters:
count   the output parameter of number of collation key values, including any trailing nulls.
Deprecated:


Friends And Related Function Documentation

class RuleBasedCollator [friend]
 

Definition at line 232 of file sortkey.h.


Member Data Documentation

UBool CollationKey::fBogus [private]
 

Definition at line 237 of file sortkey.h.

uint8_t * CollationKey::fBytes [private]
 

Definition at line 241 of file sortkey.h.

int32_t CollationKey::fCapacity [private]
 

Definition at line 239 of file sortkey.h.

int32_t CollationKey::fCount [private]
 

Definition at line 238 of file sortkey.h.

int32_t CollationKey::fHashCode [private]
 

Definition at line 240 of file sortkey.h.

const int32_t CollationKey::kEmptyHashCode [static, private]
 

Definition at line 235 of file sortkey.h.

const int32_t CollationKey::kInvalidHashCode [static, private]
 

Definition at line 234 of file sortkey.h.


The documentation for this class was generated from the following file:
Generated at Thu Mar 22 16:13:03 2001 for ICU 1.8 by doxygen1.2.3 written by Dimitri van Heesch, © 1997-2000