Using Collation Keys

Internationalization Module User's Guide
Rogue Wave web site: Home Page | Main Documentation Page

6.4 Using Collation Keys

An RWUCollationKey stores preprocessed comparison information for a Unicode string, and can be used to speed repeated string comparisons; for example, when sorting a set of strings. The RWUCollator class calculates collation weights incrementally. This ensures good performance, as most strings differ in their first few characters. However, if string comparisons are to be made repeatedly, then best performance can be achieved by obtaining an RWUCollationKey for each string and comparing the keys.

Collation keys can be compared meaningfully only if they are created by the same collator, or by collators with the same attributes.

6.4.1 Using RWUCollationKey

You can obtain a collation key for a given string using the getCollationKey() method on RWUCollator. For example:

RWUCollationKey myKey1 = myCollator.getCollationKey("RogueWave");
RWUCollationKey myKey2 = myCollator.getCollationKey("Software");

The returned key may be compared to other keys produced by collators with the same attributes. Note that generating a key using RWUCollator::getCollationKey() not a trivial operation, as it involves determining the collation elements and weights for an entire string. Comparing two RWUCollationKey objects, however, is fast.

Collation keys can be compared using logical operators ==, !=, and <. Thus:

if (myKey1 < myKey2) {
   // Do something here
}

Collation keys can also be inserted into collections that use operators ==, !=, and < to order items. For example:

RWTValSortedVector<RWUCollationKey,                       
                   std::less<RWUCollationKey> > vector;
vector.insert(myKey1);
vector.insert(myKey2);

To get back the string associated with a collation key, use the getString() method:

RWUString str1 = myKey1.getString();     //str1 = "RogueWave"
RWUString str2 = myKey2.getString();     //str2 = "Software"

6.4.2 Sorting Strings with Collation Keys

A common use of collation keys is in sorting a set of strings, where string comparisons are made repeatedly, as demonstrated in the code below:

RWUConversionContext context("UTF-8");                      //1

RWUString array[] = {                                       //2
  "United States",
  "Netherlands",
  "United Kingdom",
  "Germany",
  "France",
  "Italy",
  "Japan",
  "Australia",
  ""
};

RWUCollator collator;                                       //3
RWTValSortedVector<RWUCollationKey,                         //4
                   std::less<RWUCollationKey> > vector;
  
int i;
for (i = 0; array[i].isNull() == false; ++i) {
  vector.insert(collator.getCollationKey(array[i]));        //5
}

for (i = 0; i < vector.entries(); ++i) {                    //6
   std::cout << "  " << vector[i].getString() << std::endl;      
}

`//1`	Indicates that source and target strings are encoded as UTF-8.
`//2`	Creates an array of country names.
`//3`	Creates a collator based on the default locale.
`//4`	Creates an empty vector. An *RWTValSortedVector<T>* automatically keeps its contents in sorted order.
`//5`	Populates the vector with *RWUCollationKey* objects. Note that the vector uses `RWUCollationKey::operator<()` and `operator==()` for sorting.
`//6`	Prints the sorted vector. Obtains each *RWUString* object from the stored *RWUCollationKey* object using `getString()`, implicitly converts it to UTF-8, and prints the UTF-8.

The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.