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

  - isGreaterThan
  - isEqual
  - isLessThan

  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-&gt;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.

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.

~ICollation

      public:
      virtual ~ICollation()

  Destructor for deleting an ICollation object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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

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

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.

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.

localeKey

      public:
      ILocaleKey localeKey() const

  Gets the locale key of the collation object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setStrength

      public:
      void setStrength(ECollationStrength newStrength)

  Sets the new strength, the new comparison level.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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

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

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

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.

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.

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

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

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

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:

  - Base letters represent a primary difference.
  - Diacritical marks on the same base letter represent a secondary difference.
  - Uppercase and lowercase versions of the same base letter represent a tertiary difference.
  - Two characters are considered "no different" when they have equivalent Unicode spellings. Typically this appears in cases with expanding and contracting characters in which multiple characters combine to create a single ordering difference.
  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

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  ICollation

  -     UniChar*
          createUniCharChunk( const IText& source,
                              IText::length_type& chunkLength ) const

#### Inherited Protected Data

  - None