### ILocaleKey

  ILocaleKey class provides an access mechanism for any localizable resources.

  ILocaleKey class provides an access mechanism for any localizable resources. The purpose of the locale key component is to provide support for identifying linguistic and local conventions.

  Since locales are only a mechanism that allows programmers to access certain resources associated with a given country or region, the ILocaleKey itself is not a set of objects. Rather, it is a key that can be used to access a particular international object. Many international objects can be created using a locale. As a convenience, there is a default locale that is used when none is specified. The locale key mechanism is intended to be used with Unicode text manipulation. Note : International objects are those whose data/code may depend on the country or language, and which are used to support globalized programs. Globalized programs are those written so that they work no matter what language or country they are used with. Examples of international objects are collation, date, time, or number classes.

  Do not derive your own classes from this class.

### ILocaleKey - Member Functions and Data by Group

### Constructors & Destructor

Use the constructors and destructor in this group to create and destroy objects of class ILocaleKey.

~ILocaleKey

      public:
      ~ILocaleKey()

  Destructor for deleting an ILocaleKey object.

Supported Platforms

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

ILocaleKey

  Overload 1

      public:
      ILocaleKey(const ILocaleKey& that)

  Initializes an ILocaleKey object from another ILocaleKey object.

  that
    the ILocaleKey object being copied in.

Supported Platforms

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

  Overload 2

      public:
      ILocaleKey()

  Creates a default locale key.

Supported Platforms

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

  Overload 3

      public:
      ILocaleKey( const IText& languageID,
                  const IText& regionID = IText ( ),
                  const IText& extension = IText ( ) )

  Creates a locale key based on the language, region and extension information.

  languageID
    the portable POSIX language ID.
  regionID
    the portable POSIX region ID. The default value of this parameter is an empty string.
  ext
    the extension for making duplicate POSIX locale IDs unique. The default value of this parameter is an empty string.

Exception

  IInvalidParameter | If an invalid locale ID is given.
  IInvalidRequestion | When the valid locale ID corresponds to a supported locale that is not installed on the machine; there is no international resources associated with the locale, an IInvalidRequest exception will be thrown.

Supported Platforms

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

  Overload 4

      public:
      ILocaleKey(unsigned long hostLocaleID)

  Creates a locale key based on the host locale ID.

  hostLocaleID
    the host locale ID. The host locale ID is the LCID on WIN32 environments.

Exception

  IInvalidParameter | If an invalid locale ID is given.
  IInvalidRequestion | When the valid locale ID corresponds to a supported locale that is not installed on the machine; there is no international resources associated with the locale, an IInvalidRequest exception will be thrown.

Supported Platforms

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

### Assignment Operator

Use the operator in this group to replace the current locale key object with the given one.

operator =

      public:
      ILocaleKey& operator =(const ILocaleKey& that)

  Replaces the entire contents of *this with the specified value.

  that
    The ILocaleKey object use to replace the current one.

Supported Platforms

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

### Comparing the Given and Current ILocaleKey Objects for Equality or Inequality

Use the operators in this group to test the given ILocaleKey object against the current one for equality or inequality.

operator !=
  Checks if two locale keys are not the same.

      public:
      bool operator !=(const ILocaleKey& other) const

  Tests the given locale key object against the current one to determine if they are different.

  other
    the locale key object to be compared with this.

Return
  true if the two locale keys are not the same, false otherwise.

Supported Platforms

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

operator ==
  Checks if two locale keys are the same.

      public:
      bool operator ==(const ILocaleKey& other) const

  Test the given locale key object against the current one to determine if they are the same.

  other
    the locale key object to be compared with this.

Return
  true if the two locale keys are the same, false otherwise.

Supported Platforms

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

### Creating an ILocaleKey Object from the Default Locale

Use this function to create a locale key object based on the default locale.

defaultLocale

      public:
      static ILocaleKey defaultLocale()

  Creates a locale key object based on the default locale.

Return
  the default user-defined locale for the thread if there is one. Returns the thread's system default locale otherwise.

Supported Platforms

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

### Displayable Name

Use the functions in this group to obtain the locale's displayable based on the given key, language, and search values.

displayName
  Returns the displayable name of a selected locale based on the lookup strategy. If there is no display name for the locale and the locale has associated international resources, this class throws the IOutofSystemResource exception. If the locale is supported but not installed, this class throws the IInvalidRequest exception. If the locale ID is invalid, this class throws the IInvalidParameter exception.

  Overload 1
  Returns the locale's displayable name.

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

  Use this function to obtain the locale's displayable name the desired language used to express the name and a lookup strategy.

  desiredLanguage
    A constant reference to the language of the locale, which is used express its displayable name.
  strategy
    The strategy used to look up the display name. The default value is kAnyLanguage.

Return
  the displayable name of the current locale.

Exception

  IOutofSystemResource | If there is no display name for the given locale and the locale has associated international resources.
  IInvalidRequest | If the locale is supported but not installed.
  IInvalidParameter | If the locale ID is invalid.

Supported Platforms

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

  Overload 2
  Returns the locale's displayable name.

      public:
      static IText
        displayName( const IText& key,
                     const ILocaleKey& desiredLanguage = defaultLocale ( ),
                     ELookupStrategy strategy = kAnyLanguage )

  Use this function to obtain the locale's displayable name, given a key, the desired language used to express the name, and a lookup strategy.

  key
    The POSIX ID to get the displayable name with
  desiredLanguage
    A constant reference to the locale used to display the name. in.
  strategy
    The look-up strategy for the display name of the POSIX ID. The default value is kAnyLanguage.

Return
  the displayable name of the POSIX ID.

Exception

  IOutofSystemResource | If there is no display name for the given locale and the locale has associated international resources.
  IInvalidRequest | If the locale is supported but not installed.
  IInvalidParameter | If the locale ID is invalid.

Supported Platforms

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

### Getting and Setting the ILocaleKey Information

Use these functions to get and set the entire POSIX ID, which is composed of a language ID, region ID and extension, or any of its parts. Using the functions in this group, you can also get and set the host locale ID of the ILocaleKey object and determine whether the current locale is the POSIX C or POSIX locale.

extension

      public:
      IText extension() const

  Gets the POSIX extension of the locale key.

Return
  the POSIX extension of the locale key.

Supported Platforms

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

hostID

      public:
      unsigned long hostID() const

  Gets the host locale ID of this ILocaleKey object. The returned ID is the Window's LCID.

Return
  the current host locale ID.

Supported Platforms

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

isCLocale

      public:
      bool isCLocale() const

  Checks if the current locale is the POSIX C or POSIX locale.

Return
  true if the locale key corresponds to the POSIX "C" or "POSIX" locale, false otherwise.

Supported Platforms

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

languageID

      public:
      IText languageID() const

  Gets the POSIX language ID of the locale key.

Return
  the POSIX language ID of the locale key.

Supported Platforms

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

posixID
  Gets the POSIX ID of this ILocaleKey object.

      public:
      IText posixID() const

  This function returns the POSIX ID, which is composed of a language ID, region ID and extension.

Return
  the current POSIX ID.

Supported Platforms

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

regionID

      public:
      IText regionID() const

  Gets the POSIX region ID of the locale key.

Return
  the POSIX region ID of the locale key.

Supported Platforms

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

setExtension

      public:
      void setExtension(const IText& extension)

  Sets the current locale POSIX extension to the new extension.

  IText
    A constant reference to the new extension.

Exception

  IInvalidParameter | If the new POSIX ID is not a valid locale ID, set the POSIX ID to be the valid locale with the same language ID (the region ID and extension will be ignored). If no corresponding locale can be found, throws the IInvalidParameter exception.
  IInvalidRequest | If the new POSIX ID of the matched locale is supported but not installed on the machine; there is no associated international resources, an IInvalidRequest exception will be thrown.

Supported Platforms

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

setHostID

      public:
      void setHostID(unsigned long localeID)

  Set the host locale ID.

  localeID
    The new host locale ID.

Supported Platforms

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

setLanguageID

      public:
      void setLanguageID(const IText& languageID)

  Sets the current locale POSIX language ID to the new language ID.

  languageID
    A constant reference to the new language ID.

Exception

  IInvalidParameter | If the new POSIX ID is not a valid locale ID, set the POSIX ID to be the valid locale with the same language ID (the region ID and extension will be ignored). If no corresponding locale can be found, throws the IInvalidParameter exception.
  IInvalidRequest | If the new POSIX ID of the matched locale is supported but not installed on the machine; there is no associated international resources, an IInvalidRequest exception will be thrown.

Supported Platforms

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

setPOSIXID
  Sets the current locale POSIX ID to the new ID.

      public:
      void setPOSIXID(const IText& localeID)

  This function sets the POSIX ID, which is composed of a language ID, region ID and extension.

  localeID
    A constant reference to the new locale ID.

Exception

  IInvalidParameter | If the POSIX ID is not a valid locale ID, set the POSIX ID to be the valid locale with the same language ID (the region ID and extension will be ignored). If no corresponding locale can be found, throws the IInvalidParameter exception.
  IInvalidRequest | If the POSIX ID of the matched locale is supported but not installed on the machine; there is no associated international resources, an IInvalidRequest exception will be thrown.

Supported Platforms

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

setRegionID

      public:
      void setRegionID(const IText& regionID)

  Sets the current locale POSIX region ID to the new region ID.

  regionID
    A constant reference to the new region ID.

Exception

  IInvalidParameter | If the new POSIX ID is not a valid locale ID, set the POSIX ID to be the valid locale with the same language ID (the region ID and extension will be ignored). If no corresponding locale can be found, throws the IInvalidParameter exception.
  IInvalidRequest | If the new POSIX ID of the matched locale is supported but not installed on the machine; there is no associated international resources, an IInvalidRequest exception will be thrown.

Supported Platforms

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

### Streaming an ILocaleKey Object In and Out

Use these functions to read the ILocaleKey object in from the given stream or write it out to it.

readFromStream

      protected:
      virtual void readFromStream(IDataStream& fromWhere)

  fromWhere
    where the locale ID will be read from.

Supported Platforms

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

writeToStream

      protected:
      virtual void writeToStream(IDataStream& toWhere) const

  toWhere
    where the loale ID will be written to.

Supported Platforms

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

### ILocaleKey - Enumerations

ELookupStrategy

      enum ELookupStrategy { kExactLocale,
                             kExactLanguage,
                             kAnyLanguage }

  ELookupStrategy is used to specify the look-up strategy for a locale key display name. Use these constants enumerated by ELookupStrategy to specify the lookup strategy for a locale key display name:
  kExactLocale
    The display name of the locale key for the exact given locale ID will be looked up.
  kExactLanguage
    The display name of the locale key for the given locale ID will be returned. If there is no display name for the exact given locale ID, the display name for the given language will be looked up. It will consider only the language portion of the language and the region ID will be ignored.
  kAnyLanguage
    If the display name cannot be found for the exact given locale ID nor the given language, displayName() will look for the display name in the default locale. This is the default display name look-up strategy.

Supported Platforms

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

### ILocaleKey - Inherited Member Functions and Data

#### Inherited Public Functions

  IMStreamable

  -     virtual ~IMStreamable()

  -     void externalizeToStream(IDataStream& towhere) const

  -     void internalizeFromStream(IDataStream& fromwhere)

  -     virtual const ITypeRepresentation&
          typeRepresentation() const = 0

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IMStreamable

  -     IMStreamable()

  -     IMStreamable(const IMStreamable& other)

  -     virtual void readFromStream(IDataStream& fromwhere) = 0

  -     virtual void writeToStream(IDataStream& towhere) const = 0

#### Inherited Protected Data

  - None