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

~IPortableCollation

      public:
      virtual ~IPortableCollation()

  Destructor for deleting an IPortableCollation object.

Supported Platforms

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

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.

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

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

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.

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.

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.

  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.

  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

    -     virtual ~ICollation()

    -     int compare(const IText& source, const IText& target) const

    -     int
            compare( const UniChar* sourceLow,
                     const UniChar* sourceHigh,
                     const UniChar* targetLow,
                     const UniChar* targetHigh ) const

    -     int
            compare( ITextIterator sourceBegin,
                     ITextIterator sourceEnd,
                     ITextIterator targetBegin,
                     ITextIterator targetEnd ) const

    -     static ICollation*
            createCollation( const ILocaleKey& localeId = ILocaleKey::defaultLocale ( ),
                             ECollationStrength strength = kTertiaryDifference )

    -     virtual IText
            displayName( const ILocaleKey& desiredLanguage = ILocaleKey::defaultLocale ( ),
                         ILocaleKey::ELookupStrategy strategy = ILocaleKey::kAnyLanguage ) const = 0

    -     long
            hash( const UniChar* sourceLow,
                  const UniChar* sourceHigh ) const

    -     long hash(const IText& source) const

    -     long
            hash( ITextIterator sourceBegin,
                  ITextIterator sourceEnd ) const

    -     virtual bool
            isEqual( const IText& sourceText,
                     const IText& targetText ) const

    -     virtual bool
            isGreaterThan( const IText& sourceText,
                           const IText& targetText ) const

    -     virtual bool
            isLessThan( const IText& sourceText,
                        const IText& targetText ) const

    -     ILocaleKey localeKey() const

    -     void setStrength(ECollationStrength newStrength)

    -     ECollationStrength strength() const

    -     IText
            transform( ITextIterator sourceBegin,
                       ITextIterator sourceEnd ) const

    -     IText transform(const IText& source) const

  #### Inherited Public Data

    - None

  #### Inherited Protected Functions

    ICollation

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

    -     virtual int
            do_compare( const UniChar* sourceLow,
                        const UniChar* sourceHigh,
                        const UniChar* targetLow,
                        const UniChar* targetHigh ) const = 0

    -     virtual long
            do_hash( const UniChar* sourceLow,
                     const UniChar* sourceHigh ) const

    -     ICollation(const ICollation& source)

    -     ICollation()

    -     ICollation& operator =(const ICollation& that)

    -     void setLocaleKey(const ILocaleKey& newLocale)

  #### Inherited Protected Data

    - None