Using the Locale Structure

The main use of the International folio is to obtain the target language and country codes. The folio also provides tools to format dates, numbers, and currency for the target language and country. This section describes how to use these tools.

Determining the Current Language and Country

The intlOpenLocale() call determines the current user settings for language or country:

Item intlOpenLocale(const TagArg *tags)

This call accepts one argument, tags, a pointer to a tag argument list. This pointer is currently unused and should be set to NULL. intlOpenLocale() returns an Item.

The application should then use the following call to obtain the Locale structure for the Item:

Locale *intlLookupLocale(Item locItem)

This call accepts one argument, locItem, an Item as returned from intlOpenLocale(). The language code in the Locale structure can then determine which set of messages and artwork to use.

For example, if the language code were "de," the application would use a directory containing the German message text and artwork ("de" being the code for Deutsch). The application has a directory containing message text and artwork for each language code it uses.

Note: An application must supply any text or artwork it displays. The application must supply text strings or artwork for each language it supports.

When an application finishes using an Item, use the following call to terminate its use of it:

Err intlCloseLocale(Item locItem)

intlCloseLocale() l accepts one argument, locItem, the item to be closed. It returns zero if the call was successful, otherwise, an error code is returned.

Working With International Character Strings

Comparing Character Strings

Applications use the intlCompareStrings() function to compare strings and sort text to be displayed. Each language sorts text in different ways. intlCompareStrings() adapts its behavior to the current language. By using this function, your title sorts text in the appropriate manner for the target culture:

int32 intlCompareStrings(Item locItem, const unichar *string1, const char *string2)

This call accepts three arguments: locItem is a Locale Item obtained from intlOpenLocale(), string1 is a pointer to the first string to compare, and string2 is a pointer to the second string to compare.

The comparison is performed according to the collation rules of locItem. intlCompareStrings() is similar to the standard C strcmp() function, except that it handles sorting variations of different languages.

IntlCompareStrings() returns -1 if string1 is less than string2; 0 if string1 is equal to string2; and 1 if string1 is greater than string2. INTL_ERR_BADITEM is returned if locItem was not a valid Item.

Changing Letters In Character Strings

intlConvertString() strips diacritical marks and changes the letter case of words or characters. This function handles the language differences in rules for case conversion. It is similar to the standard C toupper() and tolower() functions.

int32 intlConvertString(Item locItem, const unichar *string, unichar *result, uint32 resultSize, uint32 flags);

The call accepts five arguments: locItem is an Item returned from intlOpenLocale(), string is the string to be changed, result is where the result of the conversion is placed, resultSize is the number of bytes available in result, and flags indicates the conversion to be performed. The string copied to result is guaranteed to be NULL-terminated.

If successful, intlConvertString() returns a positive number indicating the number of characters in result. Otherwise, it returns an error code.

Changing Character Sets

intlTransliterateString() converts a string from one character set to another character set.

The International folio always generates UniCode strings. For example, intlFormatNumber() generates a UniCode string holding the formatted number. The 3DO Portfolio currently supplies simple text output routines in Lib3DO which only accept ASCII text. To display the formatted number, an application must convert the UniCode string generated by the International folio to ASCII and call the text output routines.

intlTransliterateString() can be used to convert data files generated in ASCII to UniCode or to convert the output of the International folio into ASCII for use by other tools.

intlTranliterateString() is called as follows:

int32 intlTransliterateString(const void *string, CharacterSets stringSet, void *result, CharacterSets resultSet, uint32 resultSize, uint8 unknownFiller);

The call accepts six arguments: string is the string to convert, stringSet is the character set of the string to convert, result is where to put the converted string, resultSet is the character set to use for the resulting string, resultSize is the number of bytes available in result, and unknownFiller is used as filler for characters that cannot be converted.

If successful, intlTransliterateString() returns a positive number indicating the number of characters in result. Otherwise, it returns an error code.

Providing C Functionality

intlGetCharAttrs() provides functionality similar to the standard C functions isupper(), islower(), etc. It is called as follows:

uint32 intlGetCharAttrs(Item locItem, unichar character);

The call accepts two arguments: locItem, an Item as returned by intlOpenLocale(); and character, the character for which attributes should be returned.

If successful, intlGetCharAttrs() returns a bit mask which indicates the attributes of the character. INTL_ERR_BADITEM is returned if locItem is not a valid Item.

Formatting Numbers or Currency

Numbers are represented in different ways in different countries, so a title should use the following call to format a number to be displayed in the correct manner:

int32 intlFormatNumber(Item locItem, const NumericSpec *spec, uint32 whole, uint32 frac, bool negative, bool doFrac, unichar *result, uint32 resultSize);

The call accepts seven arguments: locItem is an Item returned from intlOpenLocale(), spec is the format specification for the number (usually taken from the Locale structure), whole is the whole component of the number, frac is the decimal component of the number expressed in billionths (to the right of the decimal mark), negative is a Boolean that indicates whether the number is negative, doFrac is a flag indicating which portions of the number should be formatted (if TRUE, the entire number with a decimal mark is output, if FALSE, only the whole part of the number is output), result is where the formatted number is put, and resultSize is the number of bytes in result.

The number is formatted according to the rules specified in locItem and spec. The string copied to result is guaranteed to be NULL-terminated.

If successful, intlFormatNumber() returns a positive number indicating the number of characters in result. Otherwise, it returns an error code.

Formatting Dates

An application should use the following call to format a date to be displayed:

int32 intlFormatDate(Item locItem, DateSpec spec, const GregorianDate *date, unichar *result, uint32 resultSize);

The call accepts five arguments: locItem is an Item as returned from intlOpenLocale(), spec is the format specification for the date (usually taken from the Locale structure), date is the date to format, result is where to put the formatted date, and resultSize is the number of bytes in result. The date is formatted according to the rules of locItem and spec arguments. The string copied into result is guaranteed to be NULL-terminated.

If successful, intlFormatDate() returns a positive number indicating the number of characters in result. Otherwise, an error code is returned.