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