# Locale
[SHELL API]

Locale objects and API for them. More...

## Typedefs
typedef struct MLocale | MLocale
| `struct` `MLocale`.
## Functions
MLocale * | mlocale_set (int category, const char *name)
| Set the current locale.
MSymbol | mlocale_get_prop (MLocale *locale, MSymbol key)
| Get the value of a locale property.
int | mtext_ftime (MText *mt, const char *format, const struct tm *tm, MLocale *locale)
| Format date and time.
MText * | mtext_getenv (const char *name)
| Get an environment variable.
int | mtext_putenv (MText *mt)
| Change or add an environment variable.
int | mtext_coll (MText *mt1, MText *mt2)
| Compare two M-texts using the current locale.
## Variables
MSymbol | Mterritory
MSymbol | Mmodifier
MSymbol | Mcodeset

## Detailed Description

Locale objects and API for them.

The m17n library represents locale related information as objects of type MLocale.

## Typedef Documentation

typedef struct MLocale MLocale

`struct` `MLocale`.

The structure `MLocale` is used to hold information about name, language, territory, modifier, codeset, and the corresponding coding system of locales.

The contents of this structure are implementation dependent. Its internal structure is concealed from application programs.

See Also:
  mlocale_get_prop()

## Function Documentation

MLocale* mlocale_set | ( | int | category,
|  | const char * | name |
| ) |  |  |

Set the current locale.

The mlocale_set() function sets or query a part of the current locale. The part is specified by category which must be a valid first argument to `setlocale()`.

If locale is not NULL, the locale of the specified part is set to locale. If locale is not supported by the system, the current locale is not changed.

If locale is NULL, the current locale of the specified part is queried.

Return value:
  If the call is successful, mlocale_set() returns an opaque locale object that corresponds to the locale. The name of the locale can be acquired by the function mlocale_get_prop(). Otherwise, it returns NULL.

Errors:
  `MERROR_LOCALE`

MSymbol mlocale_get_prop | ( | MLocale * | locale,
|  | MSymbol | key |
| ) |  |  |

Get the value of a locale property.

The mlocale_get_prop() function returns the value of a property key of local locale. key must be Mname, Mlanguage, Mterritory, Mcodeset, Mmodifier, or Mcoding.

int mtext_ftime | ( | MText * | mt,
|  | const char * | format,
|  | const struct tm * | tm,
|  | MLocale * | locale |
| ) |  |  |

Format date and time.

The mtext_ftime() function formats the broken-down time tm according to the format specification format and append the result to the M-text mt. The formating is done according to the locale locale (if not NULL) or the current locale (LC_TIME).

The meaning of the arguments tm and format are the same as those of strftime().

See Also:
  strftime().

MText* mtext_getenv | ( | const char * | name | ) |

Get an environment variable.

The mtext_getenv() function searches the environment variable list for a string that matches the string pointed to by name.

If there is a match, the function decodes the value according to the current locale (LC_CTYPE) into an M-text, and return that M-text.

If there is no match, the function returns NULL.

int mtext_putenv | ( | MText * | mt | ) |

Change or add an environment variable.

The mtext_putenv() function changes or adds the value of environment variables according to M-text mt. It calls the function `putenv` with an argument generated by encoding mt according to the current locale (LC_CTYPE).

Return value:
  This function returns zero on success, or -1 if an error occurs.

int mtext_coll | ( | MText * | mt1,
|  | MText * | mt2 |
| ) |  |  |

Compare two M-texts using the current locale.

The mtext_coll() function compares the two M-texts mt1 and mt2. It returns an integer less than, equal to, or greater than zero if mt1 is found, respectively, to be less than, to match, or to be greater than mt2. The comparison is based on texts as appropriate for the current locale (LC_COLLATE).

This function makes use of information that is automatically cached in the M-texts as a text property. So, the second call of this function with mt1 or mt2 finishes faster than the first call.

## Variable Documentation

MSymbol Mterritory

The symbol whose name is "territory".

MSymbol Mmodifier

The symbol whose name is "modifier".

MSymbol Mcodeset

The symbol whose name is "codeset".