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.
Constructs and destructs ICollation objects.
![]() |
protected:
ICollation(const ICollation& source)
Windows | OS/2 | AIX |
Yes | Yes | Yes |
protected:
ICollation()
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Assigns one collation object to another.
![]() |
public:
virtual ~ICollation()
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
ICollation& operator =(const ICollation& that)
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Compares, hashes, and transforms text based on the collation.
![]() |
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.
public:
int compare(const IText& source, const IText& target) const
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
int compare( ITextIterator sourceBegin, ITextIterator sourceEnd, ITextIterator targetBegin, ITextIterator targetEnd ) const
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.
IInvalidParameter | If sourceEnd is less than sourceBegin, or targetEnd is less than targetBegin. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
int compare( const UniChar* sourceLow, const UniChar* sourceHigh, const UniChar* targetLow, const UniChar* targetHigh ) const
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.
IInvalidParameter | If sourceHigh is less than sourceLow, or targetHigh is less than targetLow. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
public:
long hash( const UniChar* sourceLow, const UniChar* sourceHigh ) const
Returns the hash value based on the string characters' Unicode values of the characters in the string.
IInvalidParameter | If sourceHigh is less than sourceLow, or targetHigh is less than targetLow. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
long hash( ITextIterator sourceBegin, ITextIterator sourceEnd ) const
Returns the hash value based on the string characters' Unicode values of the characters in the string.
IInvalidParameter | If sourceEnd is less than sourceBegin. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
long hash(const IText& source) const
Returns the hash value based on the string characters' Unicode values of the characters in the string.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
public:
IText transform(const IText& source) const
Returns the transformed text by value.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
IText transform( ITextIterator sourceBegin, ITextIterator sourceEnd ) const
Returns the transformed text by value.
IInvalidParameter | If sourceEnd is less than sourceBegin. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Provides access to the displayable name.
![]() |
public:
virtual IText displayName( const ILocaleKey& desiredLanguage = ILocaleKey::defaultLocale ( ), ILocaleKey::ELookupStrategy strategy = ILocaleKey::kAnyLanguage ) const = 0
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.
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. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Get and set member functions of an ICollation object.
![]() |
public:
ILocaleKey localeKey() const
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
void setStrength(ECollationStrength newStrength)
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
ECollationStrength strength() const
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Class implementation methods.
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual long do_hash( const UniChar* sourceLow, const UniChar* sourceHigh ) const
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual IText do_transform(const IText& source) const = 0
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
void setLocaleKey(const ILocaleKey& newLocale)
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Factory method to create new ICollation derived objects.
![]() |
public:
static ICollation* createCollation( const ILocaleKey& localeId = ILocaleKey::defaultLocale ( ), ECollationStrength strength = kTertiaryDifference )
IInvalidRequestion | If no collation object can be found. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Compare text based on the collation.
![]() |
public:
virtual bool isEqual( const IText& sourceText, const IText& targetText ) const
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual bool isGreaterThan( const IText& sourceText, const IText& targetText ) const
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual bool isLessThan( const IText& sourceText, const IText& targetText ) const
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
enum ECollationStrength { kPrimaryDifference, kSecondaryDifference, kTertiaryDifference, kNoDifference }
Each Unicode character is assigned ordering priority: primary, secondary, tertiary, and no differences, as follows:
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
enum ETextComparisonResult { kSourceLess=-, kSourceEqual=0, kSourceGreater=1 }
kSourceLess; source text < target. kSourceEqual; source text == target. kSourceGreater; source text > target.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
UniChar* createUniCharChunk( const IText& source, IText::length_type& chunkLength ) const