IPortableCollation

IPortableCollation provides portable language-sensitive text string comparison. IPortableCollation is an abstract class derived from ICollation. It provides the protocol for portable language-sensitive text collation. The client calls IPortableCollation::createCollation to instantiate an IPortableCollation object. The provision of a portable text collation is not only for Unicode support for non-multibyte text support platforms. More importantly, it supports portable information sharing between machines for client/server applications.


IPortableCollation - Member Functions and Data by Group

Constructors & Destructor

Construct and destruct IPortableCollation objects.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IPortableCollation

Constructors for creating a portable collation object.


Overload 1
protected:
IPortableCollation()
The default constructor for creating a portable collation object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
IPortableCollation(const IPortableCollation& copy)
Initializes an IPortableCollation object from another IPortableCollation object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
protected:
IPortableCollation(const IText& rules)
Initializes an IPortableCollation object with a set of collation rules.
rules
The collation rules.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ANSI Compliant Implementation

Overrides for parent's implementation methods.


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

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.

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]
do_matchCompare
protected:
virtual int do_matchCompare( const UniChar* sourceLow, const UniChar* sourceHigh, const UniChar* targetLow, const UniChar* targetHigh, IText::length_type& matchSourceLen, IText::length_type& matchTargetLen ) const = 0
The actual comparison algorithm for the portable collation object. The length of compared characters in the source and target strings will be returned.

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.
matchSourceLen
The length of matched source string.
matchTargetLen
The length of matched target string.

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


Assignment Operator

Assign one IPortableCollation object to another.


[view class]
operator =
protected:
IPortableCollation& operator =( const IPortableCollation& that )
Replaces the entire contents of *this with the specified value.
that
The IPortableCollation object being copied in.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Comparing, Transforming, and Hashing

Compares, transforms, or hashes text based on this collation.


[view class]
compare
This comparison function overloads the ICollation::compare function. Returns the result of comparison between two strings as well as the matching strength. Returns 1 if source is greater than target, 0 if both are equal and -1 if source is less than target. The result determines whether a string is less than, greater than, or equal to another string.


Overload 1
public:
virtual int compare( const UniChar* sourceLow, const UniChar* sourceHigh, const UniChar* targetLow, const UniChar* targetHigh, IText::length_type& matchSourceLen = nlength, IText::length_type& matchTargetLen = nlength ) const
sourceLow
Source string beginning offset.
sourceHigh
Source string ending offset.
targetLow
Target string beginning offset.
targetHigh
Target string ending offset.
matchSourceLen
The length of matched source string.
matchTargetLen
The length of matched target 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:
virtual int compare( const IText& source, const IText& target, IText::length_type& matchSourceLen = nlength, IText::length_type& matchTargetLen = nlength ) const
source
The source text to be compared with.
target
The text string that is to be compared to the source text.
matchSourceLen
The length of matched source string.
matchTargetLen
The length of matched target string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual int compare( const ITextIterator& sourceBegin, const ITextIterator& sourceEnd, const ITextIterator& targetBegin, const ITextIterator& targetEnd, IText::length_type& matchSourceLen = nlength, IText::length_type& matchTargetLen = nlength ) 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.
matchSourceLen
The length of matched source string.
matchTargetLen
The length of matched target string.

Exception

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Display Name

Provides access to the displayable name.


[view class]
displayName
public:
IText displayName( const ILocaleKey& desiredLanguage = ILocaleKey::defaultLocale ( ), ILocaleKey::ELookupStrategy strategy = ILocaleKey::kAnyLanguage ) const

Returns the displayable name of a bitwise 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.

At the current time IPortableCollation::displayName always returns an IText().

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


Instantiation Helper

Factory method to create new objects of this class.


[view class]
createCollation
public:
static IPortableCollation* createCollation( const ILocaleKey& key, ICollation::ECollationStrength strength = kTertiaryDifference )
An IPortableCollation object can only be created by calling this static member. It creates an IPortableCollation instance based on the locale key:
  1. If the locale key argument is omitted, it uses the current locale as the default locale. If the current locale is not a portable locale, use the default portable locale.
  2. If the locale key corresponds to a portable locale, portable collation is created.

Returns a pointer to constructed IPortableCollation instance.

At the current time IPortableCollation::createCollation always returns a NULL pointer.

localeKey
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 portable collation object can be found.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IPortableCollation - Inherited Member Functions and Data

Inherited Public Functions

ICollation

Inherited Public Data

  • None

Inherited Protected Functions

ICollation

Inherited Protected Data

  • None