UniCreateLocaleObject creates a locale object for the locale categories specified by LocaleSpec. The object created is an opaque object containing all the data and methods necessary to perform the language-sensitive operations of functions that accept an argument of type LocaleObject If the function is successful, all categories of the locale object are created and initialized.

When the LocaleSpec argument is a pointer to a character string (UCS character string or multibyte character string), it identifies the name of the locale to be initialized. The locale name is used to locate physical resources associated with this locale. The locale name UNIV is reserved and refers to the definitions that provide default behavior for functions.

When the LocaleSpec argument is a NULL pointer (without regard to the value of the LocaleSpecType argument), UniCreateLocaleObject creates a locale object for the UNIV locale.

When the LocaleSpec argument points to a locale token value as indicated by the value of the LocaleSpecType argument, the token identifies the locale to be initialized.

When the LocaleSpec argument is an empty multibyte or UCS character string, UniCreateLocaleObject creates a locale object based upon the settings of the locale environment variables.

┌───────────────┬───────────────┬──────────────────────────────┐
│Category       │Precedence     │Usage                         │
├───────────────┼───────────────┼──────────────────────────────┤
│LC_ALL         │Highest        │Setting LC_ALL takes          │
│               │               │precedence over any other     │
│               │               │locale environment variable.  │
├───────────────┼───────────────┼──────────────────────────────┤
│LC_COLLATE     │Equal          │Specifies collation (sorting) │
│               │precedence     │rules.                        │
├───────────────┼───────────────┼──────────────────────────────┤
│LC_CTYPE       │Equal          │Specifies character           │
│               │precedence     │classification and case       │
│               │               │conversion.                   │
├───────────────┼───────────────┼──────────────────────────────┤
│LC_MESSAGES    │Equal          │Specifies the values for      │
│               │precedence     │affirmative and negative      │
│               │               │answers, and the language for │
│               │               │displayed messages.           │
├───────────────┼───────────────┼──────────────────────────────┤
│LC_MONETARY    │Equal          │Specifies monetary formats and│
│               │precedence     │currency symbol.              │
├───────────────┼───────────────┼──────────────────────────────┤
│LC_NUMERIC     │Equal          │Specifies decimal formats.    │
│               │precedence     │                              │
├───────────────┼───────────────┼──────────────────────────────┤
│LC_TIME        │Equal          │Specifies date and time       │
│               │precedence     │formats.                      │
├───────────────┼───────────────┼──────────────────────────────┤
│LANG           │Lowest         │Setting LANG takes precedence │
│               │               │over any undefined locale     │
│               │               │environment variable.  This   │
│               │               │may be used in conjunction    │
│               │               │with:                         │
│               │               │LC_COLLATE LC_CTYPE           │
│               │               │LC_MESSAGES LC_MONETARY       │
│               │               │LC_NUMERIC LC_TIME            │
└───────────────┴───────────────┴──────────────────────────────┘

If the specified locale is valid and supported, UniCreateLocaleObject allocates memory for the new object and returns the address of the created locale object in the area pointed to by locale_object. It is the application's responsibility to free this memory with a call to UniFreeLocaleObject when the object is no longer needed. If the function fails for any reason, the contents of the area pointed to by locale_object are undefined.

The locale token provides a shorthand notation for specifying a locale. The format of the locale token is as returned by a call to UniLocaleStrToToken. The format is defined as an unsigned integer of four octets.

Examples of typical usage:

The locale environments variables are set as follows:

LANG=de_DE
LC_MONETARY=en_US

The LocaleSpec argument is an empty multibyte or UCS character string.

This example creates a locale object with all categories set to de_DE except for LC_MONETARY which has the value of en_US. The locale environment variables are set as follows:

LANG=fr_FR

The LocaleSpec argument is an empty multibyte or UCS character string.

This example creates a locale object with all categories set to fr_FR. The locale environment variables are set as follows:

LC_ALL=it_IT
LANG=fr_FR

The LocaleSpec argument is an empty multibyte or UCS character string.