Crate locale_settings

An interface to all manner of locale-related information.

This crate provides a higher-level interface to locale settings accessed via POSIX (see ISO/IEC 15897 operating system functions. These are under the module simple_locale::settings.

This crate uses bindgen for the creation of operating system bindings to the langinfo, localcharset, locale, and xlocale headers. Another crate () does something similar, however...

Example - Settings

In the following example we have a naïve implementation of a currency formatter. To format a US dollar amount correctly we first set the current locale for the Currency Category and then call the get_currency_format. From this we use only the simplest of the formatting options to display our currency amount.

use std::str::FromStr;
use locale_types::{Locale, LocaleString};
use locale_settings::locale::{Category, set_locale};
use locale_settings::currency::get_currency_format;

let amount: f64 = 5.909;
let en_us = LocaleString::from_str("en_US.UTF-8").unwrap();

if set_locale(&Locale::String(en_us), &Category::Currency) {
    let format = get_currency_format();
    let local = format.local_format.unwrap();
    println!(
        "{2}{0}{3}{1:.4$}",
        amount.trunc(),
        amount.fract(),
        local.currency_symbol,
        format.number_format.decimal_separator,
        local.decimal_precision
    );
}

FFI Bindings

As mentioned above, this crate depends on FFI bindings to POSIX locale functions, and there are O/S differences that make this a pain. The script create-bindings.sh is used to generate these bindings (using cargo bindgen) in such a way that different O/S bindings can be built effectively.

Typically we treat each of the categories defined by POSIX in locale.h as modules. The categories are show in the table below.

POSIX Category	Module	Function(s)
LC_COLLATE	N/A
LC_CTYPE	codeset	get_code_set_format, get_code_set_format_for_locale
LC_MESSAGES	messages	get_message_format, get_message_format_for_locale
LC_MONETARY	currency	get_currency_format, get_currency_format_for_locale
LC_NUMERIC	numeric	get_numeric_format, get_numeric_format_for_locale
LC_TIME	time	get_date_time_format, get_date_time_format_for_locale, get_calendar_names, get_calendar_names_for_locale

Note: the POSIX category LC_COLLATE is not mapped to modules as there are no calls to retrieve specific information.

For each module there is at least a matching pair of functions, one which takes zero parameters and returns the current locale settings, and one which takes two parameters and allows the retrieval of settings from another locale. The first of these parameters is a Locale enum that denotes the locale to query, and the second parameter is a boolean inherit_current that determines how the specified locale should be interpreted.

Additionally, the module locale has the necessary functions to get and set the locale either for an individual category or for all. This modules provides implementations that use the C API directly as well as an implementation that uses standard environment variables.

Relationship to the POSIX API

The POSIX locale API is spread across a number of functions including localeconv, nl_langinfo, and setlocale. Also, the different categories of data is mixed up in common structures. The intent of this crate is to invert this abstraction, to group together data by common category regardless of the underlying API being used.

Those functions in the table above that end in _for_locale use the xlocale extended API, specifically newlocale, uselocale, and freelocale to obtain the settings for a locale other than the current.

Re-exports

pub use locale::Category;

Modules

codeset	Fetch locale-specific code-set settings.
currency	Fetch locale-specific currency formatting settings.
locale	Provides ability to get/set the current process locale.
messages	Fetch locale-specific message formatting settings.
numeric	Fetch locale-specific number formatting settings.
time	Fetch locale-specific date and time formatting settings.