[][src]Crate unic_locale

unic-locale is an API for parsing, manipulating, and serializing Unicode Locale Identifiers.

The crate provides algorithms for parsing a string into a well-formed locale identifier as defined by UTS #35: Unicode LDML 3.1 Unicode Locale Identifier.

Locale vs. LanguageIdentifier

LanguageIdentifier is a subset of a Locale that only provides the basic subtags such as language, script, region and variants.

Locale extends that with a set of extensions such as transform, unicode and private.

Examples

use unic_locale::Locale;

let mut loc: Locale = "en-Latn-US-u-hc-h12-t-h0-hybrid".parse()
    .expect("Failed to parse.");

assert_eq!(loc.id.language.as_str(), "en");
assert_eq!(loc.id.script, Some("Latn".parse().unwrap()));
assert_eq!(loc.id.region, Some("US".parse().unwrap()));
assert_eq!(loc.id.variants().len(), 0);
assert_eq!(loc.extensions.unicode.keyword("hc")
    .expect("Getting keyword failed.")
    .collect::<Vec<_>>(), &["h12"]);
assert_eq!(loc.extensions.transform.tfield("h0")
    .expect("Getting tfield failed.")
    .collect::<Vec<_>>(), &["hybrid"]);

loc.id.script = None;
loc.id.region = Some("GB".parse().expect("Region parsing failed."));

assert_eq!(loc.to_string(), "en-GB-t-h0-hybrid-u-hc-h12");

For more details, see Locale.

Optional features

locale! and locale! macros

If feature = "macros" is selected, the crate provides a procedural macro which allows to construct build-time well-formed locale identifiers with zero-cost at runtime.

This example is not tested
use unic_locale::{locale, locales};

let es_ar = locale!("es-AR");
let en_us = locale!("en-US");

assert_eq!(es_ar, "es-AR");
assert_eq!(en_us, "en-US");

let locales = locales!("es-AR", "en-US", "de");

assert_eq!(locales.get(0), "es-AR");
assert_eq!(locales.get(1), "en-US");
assert_eq!(locales.get(2), "de");

The macros produce instances of Locale the same way as parsing from &str does, but since the parsing is performed at build time, it doesn't need a Result.

At the moment locale! can also be used for const variables, but only if no variants or extensions are used.

The macros are optional to reduce the dependency chain and compilation time of unic-locale.

Likely Subtags

If feature = "likelysubtags" is selected, the Locale gains two more methods:

  • add_likely_subtags
  • remove_likely_subtags

Both of them operate in place updating the existing Locale by either extending subtags to most likely values, or removing the subtags that are not needed.

Both methods return a bool that indicates if the identifier has been modified.

This example is not tested
use unic_locale::Locale;

let mut loc: Locale = "fr-FR".parse()
    .expect("Parsing failed.");

assert_eq!(loc.add_likely_subtags(), true);
assert_eq!(loc, "fr-Latn-FR");

assert_eq!(loc.remove_likely_subtags(), true);
assert_eq!(loc, "fr");

The feature is optional because it increases the binary size of the library by including a data table for CLDR likelySubtags.

Modules

extensions

Unicode Extensions provide a mechanism to extend the LanguageIdentifier with additional bits of information.

parser
subtags

Structs

ExtensionsMap

A map of extensions associated with a given `Locale.

LanguageIdentifier

LanguageIdentifier is a core struct representing a Unicode Language Identifier.

Locale

Locale is a core struct representing a Unicode Locale Identifier.

Enums

CharacterDirection

Enum representing available character direction orientations.

ExtensionType

Defines the type of extension.

Functions

canonicalize

This is a best-effort operation that performs all available levels of canonicalization.