Locale
SHELL API

Locale objects and API for them. More...

Collaboration diagram for Locale:

## Typedefs

typedef struct MLocale | MLocale
| `struct` `MLocale`. More...

## Functions

MPlist * | mlanguage_list (void)
| List 3-letter language codes. More...
MSymbol | mlanguage_code (MSymbol language, int len)
| Get a language code. More...
MPlist * | mlanguage_name_list (MSymbol language, MSymbol target, MSymbol script, MSymbol territory)
| Return the language names written in the specified language. More...
MText * | mlanguage_text (MSymbol language)
| Return the language name written in that language. More...
MPlist * | mscript_list (void)
| List script names. More...
MPlist * | mscript_language_list (MSymbol script)
| List languages that use a specified script. More...
MLocale * | mlocale_set (int category, const char *name)
| Set the current locale. More...
MSymbol | mlocale_get_prop (MLocale *locale, MSymbol key)
| Get the value of a locale property. More...
int | mtext_ftime (MText *mt, const char *format, const struct tm *tm, MLocale *locale)
| Format date and time. More...
MText * | mtext_getenv (const char *name)
| Get an environment variable. More...
int | mtext_putenv (MText *mt)
| Change or add an environment variable. More...
int | mtext_coll (MText *mt1, MText *mt2)
| Compare two M-texts using the current locale. More...

## Variables

MSymbol | Miso639_1
MSymbol | Miso639_2
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

## MLocale

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

## mlanguage_list()

MPlist* mlanguage_list | ( | void |  | ) |

List 3-letter language codes.

The mlanguage_list() funciton returns a well-formed plist whose keys are Msymbol and values are symbols whose names are ISO639-2 3-letter language codes.

Return value:
  This function returns a plist. The caller should free it by m17n_object_unref().

See Also:
  mscript_list().

## mlanguage_code()

MSymbol mlanguage_code | ( | MSymbol | language,
|  | int | len
| ) |  |

Get a language code.

The mlanguage_code() function returns a symbol whose name is the ISO639 language code of language. language is a symbol whose name is an ISO639-2 3-letter language code, an ISO639-1 2-letter language codes, or an English word.

len specifies the type of the returned language code. If it is 3, an ISO639-2 3-letter language code is returned. If it is 2, an ISO639-1 2-letter language code is returned when defined; otherwise Mnil is returned. If it is 0, a 2-letter code is returned when defined; otherwise a 3-letter code is returned.

Return value:
  If the information is available, this function returns a non-Mnil symbol. Otherwise, it returns Mnil.

See Also:
  mlanguage_name_list(), mlanguage_text().

## mlanguage_name_list()

MPlist* mlanguage_name_list | ( | MSymbol | language,
|  | MSymbol | target,
|  | MSymbol | script,
|  | MSymbol | territory
| ) |  |

Return the language names written in the specified language.

The mlanguage_name_list() function returns a plist of LANGUAGE's names written in TARGET language. SCRIPT and TERRITORY, if not Mnil, specifies which script and territory to concern at first.

LANGUAGE and TARGET must be a symbol whose name is an ISO639-2 3-letter language code or an ISO639-1 2-letter language codes. TARGET may be Mnil, in which case, the language of the current locale is used. If locale is not set or is C, English is used.

SCRIPT and TERRITORY must be a symbol whose name is a script and territory name of a locale (e.g. "TW", "SG") respectively.

Return value:
  If the translation is available, this function returns a non-empty plist. The first element has key MText and the value is an M-text of a translated language name. If the succeeding elements also have key MText, their values are M-texts of alternate translations.

If no translation is available, `NULL` is returned.

The returned plist should not be modified nor freed.

See Also:
  mlanguage_code(), mlanguage_text().

## mlanguage_text()

MText* mlanguage_text | ( | MSymbol | language | ) |

Return the language name written in that language.

The mlanguage_text() function returns, in the form of M-text, the language name of language written in language. If the representative characters of the language are known, the characters of the returned M-text has a text property whose key is Mtext and whose value is an M-text that contains the representative characters.

Return value:
  If the information is available, this function returns an M-text that should not be modified nor freed. Otherwise, it returns `NULL`.

See Also:
  mlanguage_code(), mlanguage_name().

## mscript_list()

MPlist* mscript_list | ( | void |  | ) |

List script names.

The mscript_list() funciton returns a well-formed plist whose keys are Msymbol and values are symbols whose names are script names.

Return value:
  This function returns a plist. The caller should free it by m17n_object_unref().

See Also:
  mscript_language_list(), mlanguage_list().

## mscript_language_list()

MPlist* mscript_language_list | ( | MSymbol | script | ) |

List languages that use a specified script.

The mscript_language_list() function lists languages that use script. script is a symbol whose name is the lower-cased version of a script name that appears in the Unicode Character Database.

Return value:

This function returns a well-formed plist whose keys are Msymbol and values are symbols whose names are ISO639-1 2-letter codes (or ISO639-2 3-letter codes, if the former is not available). The caller should not modify nor free it. If the m17n library does not know about script, it returns @ c NULL.

See Also:
  mscript_list(), mlanguage_list().

## mlocale_set()

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`

## mlocale_get_prop()

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.

## mtext_ftime()

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_getenv()

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.

## mtext_putenv()

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.

## mtext_coll()

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

## Miso639_1

MSymbol Miso639_1

## Miso639_2

MSymbol Miso639_2

## Mterritory

MSymbol Mterritory

The symbol whose name is "territory".

## Mmodifier

MSymbol Mmodifier

The symbol whose name is "modifier".

## Mcodeset

MSymbol Mcodeset

The symbol whose name is "codeset".