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.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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.


[view class]
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.


[view class]
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


[view class]
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.


[view class]
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.


[view class]
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.


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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.


[view class]
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


[view class]
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


[view class]
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

Inherited Public Data

Inherited Protected Functions

IMStreamable

Inherited Protected Data