ICollation

ICollation class is an abstract class which provides Unicode text comparison services. ICollation provides language-sensitive text comparison when you want to compare text data according to the alphabetical ordering rules of a natural language rather than the numeric values of the character encoding set. Language-sensitive processing is required for case-insensitive ordering. For example, without using the language-sensitive processing, in the Roman script the letter Z would be ordered before the letter a.

Language-sensitive text comparisons are based on text collation objects that provide correct collation and selection for a particular natural language. End users specify a preferred text collation object in their locale. Text comparison functions use the preferred object to analyze text according to the rules of that language. The host- specific collation services use Win32 APIs on NT and Window's 95. For AIX, OS/2 and AS400, the current implmentation calls to the POSIX interface.

The host-specific and portable collation classes are both derived from ICollation which provides the protocol for text-ordering. The client can create the collation object based on the current locale using the locale key, ILocaleKey, and the level of comparison. A locale key is equivalent to the cross-environment locale item identifier and the comparison level defines how the text will be ordered in a locale. The comparison level, aka collation strength, are primary, secondary and tertiary. The strength defines what will be ignored in a language sensitive text comparison.

An ICollation instance can be created by calling ICollation::createCollation with a locale key and the comparison level: A locale key is used to identify the current locale, which can be obtained by creating an ILocaleKey instance. For a locale key, if it is a valid host locale key, the host-specific collation object will be created. If a locale key is not a valid host locale key but has a corresponding portable locale, the portable collation object will be created. Otherwise, an exception will be thrown. The clients can define how the text will be ordered in a locale by specifying the level of comparison, aka collation strength. In general, clients tend to compare the strings at the same comparison level in an application. However, the collation strength can be set to a different comparison level. The default strength is kTertiaryDifference.

To create a portable collation object, you can call IPortableCollation::createCollation directly with a portable locale key. IBitwiseCollation can be directly constructed or call through ICollation::createCollation with the POSIX "C" locale key. ICollation also provides a set of functions that do simple ordering tests and return a boolean value. These functions just call the compare function directly:

The following example compares the primary differences between text1 and text2 strings in the french locale:

  // create an ILocaleKey object (French)
  ILocaleKey frLoc(IText("FR_FR"));
  ICollation*  order =
      ICollation::createCollation(frLoc, ICollation::kPrimaryDifference);
  int result = order->compare(text1, text2);
  // do something

For this release, it is not recommended that you derive from ICollation since there is no registration services yet with createCollation(). Open Class Library provides the derived classes IBitwiseCollation and IPortableCollation.


ICollation - Member Functions and Data by Group

Constructors & Destructor

Constructs and destructs ICollation objects.


[view class]
ICollation


Overload 1
protected:
ICollation(const ICollation& source)
Initializes an ICollation object from another ICollation object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
ICollation()
The default constructor for creating a collation object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Assignment Operator

Assigns one collation object to another.


[view class]
~ICollation
public:
virtual ~ICollation()
Destructor for deleting an ICollation object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator =
protected:
ICollation& operator =(const ICollation& that)
Replaces the entire contents with the ICollation object being copied in.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Comparison/Transforming/Hashing

Compares, hashes, and transforms text based on the collation.


[view class]
compare
This comparison function compares character data stored in two different text objects.

Returns information about whether a string is less than, greater than or equal to another string. The compare function that takes UniChar pointers as text range is merely for the compatibility with the ANSI C++ standard collate class. For substring text ordering capability, use ITextIterator.


Overload 1
public:
int compare(const IText& source, const IText& target) const
source
The source text to be compared with.
target
The text string that is to be compared to the source text.

Returns 1 if the source is greater than the target, 0 if both are equal and -1 if the source is less than the target.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
int compare( ITextIterator sourceBegin, ITextIterator sourceEnd, ITextIterator targetBegin, ITextIterator targetEnd ) const
sourceBegin
Iterator whose current offset is at the beginning of the source string.
sourceEnd
Iterator whose current offset is at the end of the source string.
targetBegin
Iterator whose current offset is at the beginning of the target string.
targetEnd
Iterator whose current offset is at the end of the target string.

Returns 1 if the source is greater than the target, 0 if both are equal and -1 if the source is less than the target.

Exception

IInvalidParameter If sourceEnd is less than sourceBegin, or targetEnd is less than targetBegin.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
int compare( const UniChar* sourceLow, const UniChar* sourceHigh, const UniChar* targetLow, const UniChar* targetHigh ) const
sourceLow
Source string beginning offset.
sourceHigh
Source string ending offset.
targetLow
Target string beginning offset.
targetHigh
Target string ending offset.

Returns 1 if the source is greater than the target, 0 if both are equal and -1 if the source is less than the target.

Exception

IInvalidParameter If sourceHigh is less than sourceLow, or targetHigh is less than targetLow.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
hash

Creates a long integer that is unique for the source string. If two objects are identical, their hash values should be the same. This is useful for dictionary hashing.


Overload 1
public:
long hash( const UniChar* sourceLow, const UniChar* sourceHigh ) const
sourceLow
Source string beginning offset.
sourceHigh
Source string ending offset.

Returns the hash value based on the string characters' Unicode values of the characters in the string.

Exception

IInvalidParameter If sourceHigh is less than sourceLow, or targetHigh is less than targetLow.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
long hash( ITextIterator sourceBegin, ITextIterator sourceEnd ) const
sourceBegin
Iterator whose current offset is at the beginning of the source string.
sourceEnd
Iterator whose current offset is at the end of the source string.

Returns the hash value based on the string characters' Unicode values of the characters in the string.

Exception

IInvalidParameter If sourceEnd is less than sourceBegin.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
long hash(const IText& source) const
source
The source text to be hashed.

Returns the hash value based on the string characters' Unicode values of the characters in the string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
transform
Creates an IText value that is compared lexicographically to the original text.

For any two strings, the results of doing bitwise comparison on the transformed strings will be the same as calling compare() on the original strings. Use IText::operator== for the equality test of two transformed strings. Use transform when dealing with index building on large amount of data as one example.


Overload 1
public:
IText transform(const IText& source) const
source
The source text to be transformed with.

Returns the transformed text by value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IText transform( ITextIterator sourceBegin, ITextIterator sourceEnd ) const
sourceBegin
Iterator whose current offset is at the beginning of the source string.
sourceEnd
Iterator whose current offset is at the end of the source string.

Returns the transformed text by value.

Exception

IInvalidParameter If sourceEnd is less than sourceBegin.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Displayable Name

Provides access to the displayable name.


[view class]
displayName
public:
virtual IText displayName( const ILocaleKey& desiredLanguage = ILocaleKey::defaultLocale ( ), ILocaleKey::ELookupStrategy strategy = ILocaleKey::kAnyLanguage ) const = 0
Returns the displayable name of a collation object.

Specify the desired locale and look-up strategy for which the display name is based on. Refer to the ILocaleKey class description for details on look-up strategy.

desiredLanguage
The locale which the current locale name of this collation object will be displayed in.
strategy
The look-up strategy for the display name of the current collation object. The default value is kAnyLanguage.

Exception

IOutofSystemResource If there is no display name for the given collation object.
IInvalidRequest If the desired locale is supported but not installed.
IInvalidParameter If the desired locale ID is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Getter/Setter for Information Access

Get and set member functions of an ICollation object.


[view class]
localeKey
public:
ILocaleKey localeKey() const
Gets the locale key of the collation object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setStrength
public:
void setStrength(ECollationStrength newStrength)
Sets the new strength, the new comparison level.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
strength
public:
ECollationStrength strength() const
Gets the comparison level of the collation object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Implementation Methods

Class implementation methods.


[view class]
do_compare
protected:
virtual int do_compare( const UniChar* sourceLow, const UniChar* sourceHigh, const UniChar* targetLow, const UniChar* targetHigh ) const = 0

The actual comparison algorithm. Returns 1 if the source is greater than the target, 0 if both are equal and -1 if the source is less than the target.

sourceLow
Source string beginning offset.
sourceHigh
Source string ending offset.
targetLow
Target string beginning offset.
targetHigh
Target string ending offset.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
do_hash
protected:
virtual long do_hash( const UniChar* sourceLow, const UniChar* sourceHigh ) const
The actual hashing implementation. Returns the hash value based on the string characters' Unicode values of the characters in the string.
sourceLow
Source string beginning offset.
sourceHigh
Source string ending offset.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
do_transform
protected:
virtual IText do_transform(const IText& source) const = 0
The actual text transforming algorithm Use IText::operator== for the equality test of two transformed strings. Use transform when dealing with index building on large amount of data as one example. Returns the transformed text by value.
source
The source text to be transformed with.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setLocaleKey
protected:
void setLocaleKey(const ILocaleKey& newLocale)
Sets the locale key of the collation object to a new locale.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Instantiation Helper

Factory method to create new ICollation derived objects.


[view class]
createCollation
public:
static ICollation* createCollation( const ILocaleKey& localeId = ILocaleKey::defaultLocale ( ), ECollationStrength strength = kTertiaryDifference )
An ICollation object can only be created by calling this static member. Returns a pointer to the constructed ICollation instance.
localeId
Locale identifier. The default value for this argument is the current locale.
strength
The collation strength. The default value is kTertiaryDifference.

Exception

IInvalidRequestion If no collation object can be found.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Simple Comparison Helper Functions

Compare text based on the collation.


[view class]
isEqual
public:
virtual bool isEqual( const IText& sourceText, const IText& targetText ) const
Simple ordering test function. Tests the linguistic equality of two strings. Returns true if the result of calling compare returns 0: otherwise, returns false. It is equivalent to compare(source, target) == 0.
sourceText
The source text to be compared with.
targetText
The text string that is to be compared to the source text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isGreaterThan
public:
virtual bool isGreaterThan( const IText& sourceText, const IText& targetText ) const
Simple ordering test function. Tests the linguistic equality of two strings. Returns true if the result of calling compare returns 1: otherwise, returns false. It is equivalent to compare(source, target) == 1.
sourceText
The source text to be compared with.
targetText
The text string that is to be compared to the source text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isLessThan
public:
virtual bool isLessThan( const IText& sourceText, const IText& targetText ) const
Simple ordering test function. Tests the linguistic equality of two strings. Returns true if the result of calling compare returns -1; otherwise, returns false. It is equivalent to compare(source, target) == -1.
sourceText
The source text to be compared with.
targetText
The text string that is to be compared to the source text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ICollation - Enumerations


[view class]
ECollationStrength
enum ECollationStrength { kPrimaryDifference, 
                          kSecondaryDifference, 
                          kTertiaryDifference, 
                          kNoDifference }
ECollationStrength is used to specify the comparison level.

Each Unicode character is assigned ordering priority: primary, secondary, tertiary, and no differences, as follows:

Note: For POSIX, there is no support for comparing strings with different comparison level. Therefore, the comparison result of two strings in primary, secondary or tertiary strength will be the same. For example, "abc" is always compared greater than "ABC" in primary, secondary, or tertiary strength.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ETextComparisonResult
enum ETextComparisonResult { kSourceLess=-, 
                             kSourceEqual=0, 
                             kSourceGreater=1 }
Identifies the result of Unicode text strings comparison.

kSourceLess; source text < target.
kSourceEqual; source text == target.
kSourceGreater; source text > target.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ICollation - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

ICollation

Inherited Protected Data