[−][src]Crate locale_codes

An interface to all manner of locale-related information.

This crate provides a 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 locale_codes::codes. These modules are effectively registries of standard code/identifiers and any metadate published as a part of the associated standard(s). For example, Codes for the representation of currencies, or ISO 4217 is based on a spreadsheet published directly by ISO itself with some additional fields added from other publicly accessible sources.

While there is no formal type system or traits for modules exporting codes, there are definitely some patterns all of the current implementations follow.

  1. modules typically implement a lookup() function that returns an Option,
  2. although where some standards have both alphabetic and numeric identifiers there are lookup_by_alpha() and lookup_by_numeric() instead, .
  3. Most will also include a function all_codes() to retrieve a vector of all the known identifiers,
  4. or, all_alpha_codes() and all_numeric_codes() as appropriate.

Some standards, specifically language and country, support 2-character and 3-character alphabetic identifiers, a single lookup() function is used to lookup either.

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 locale_codes::{country, currency, region};

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);

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.

Modules

codeset

Character sets registered with IANA.

country

Codes for the representation of names of countries and their subdivisions.

currency

Codes for the representation of currencies.

language

Codes for the representation of names of languages.

region

Codes for the representation of names of countries and their subdivisions.

script

Codes for the representation of names of scripts