Crate simple_locale

An interface to all manner of locale-related information.

This crate provides a higher-level interface to a number of locale-related sources, in three areas:

1. Locale-related codes/identifiers and any standards-based information concerning them. For example, ISO-396 language identifiers, or ISO-3166 country identifiers. These are under the module simple_locale::codes.
2. Locale settings, usually accessed via POSIX (see ISO/IEC 15897 operating system functions. These are under the module simple_locale::settings.
3. A Locale enumeration, and a LocaleString structure are provided that may be used to parse and construct locale identifiers in a standards-conformant manner.

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 - Codes

The following example demonstrates some of the components of the crate, at least some reasonable use cases.

1. Construct a strict locale string where identifiers are checked against known standard codes where possible.
2. Lookup the ISO-3166 data for the country (in the CountryInfo struct) identified by the ISO-3166, part 2, 3-character identifier.
3. The data fromn the last call contains one or more regions (in the RegionInfo struct), determine the countries name from the country_code.
4. Now we have the country name we can lookup the details of the currencies (in, the CurrencyInfo struct).

use simple_locale::LocaleString;
use simple_locale::codes::{country, currency, region};

let locale = LocaleString::new_strict("en".to_string())
    .with_territory("US".to_string())
    .with_code_set("UTF-8".to_string())
    .with_modifier("collation=pinyin;currency=CNY".to_string());
println!("{}", locale);

let mexico = country::lookup("MEX").unwrap();
println!("{:?}", mexico);

let mexico_region = region::lookup(mexico.country_code).unwrap();
println!("{:?}", mexico_region);

let currencies = currency::currencies_for_country_name(mexico_region.name.as_str());
println!("{:?}", currencies);

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 simple_locale::{Locale, LocaleString};
use simple_locale::settings::locale::{Category, set_locale};
use simple_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.

JSON Data Files

The script create-data-modules on the other hand is used to process files downloaded, or scraped, from standards web sites to create data used by the library. This data is generated as JSON files in the src/codes/data folder and read as a part of the build for codes modules using the Rust include! macro.

Currently data is generated for the following standards:

• ISO 639 Codes for the representation of names of languages; Parts 1-4, 2-character and 3-character codes supported.
• ISO 3166 Codes for the representation of names of countries and their subdivisions; Part 1, 2-character codes, only.
• ISO 4217 Codes for the representation of currencies; alphabetic and numeric codes supported.
• ISO 15924 Codes for the representation of names of scripts; alphabetic and numeric codes supported.

Each folder under src-data represents a single standard, which may generate one or more data sets. Each directory will contain a Python script, generate.py which is called by the top-level script to create the JSON in the correct location. Each should also contain a README that includes attribution for any data retrieved to make this possible.

Re-exports

pub use string::LocaleString;

pub use locale::Locale;

Modules

codes

Parent to a set of standard code/identifier lookup modules.

locale

Provides a layer above the LocaleString for different locale specifiers.

settings

Parent to a set of operating system, locale functions.

string

The LocaleString type provides the a structure for locale identifier strings.

Enums

LocaleError

Common error type for functions in this crate.

Type Aliases

LocaleResult

Common result type for functions in this crate.