Struct unic_locale_macros::Locale

pub struct Locale {
    pub langid: LanguageIdentifier,
    pub extensions: ExtensionsMap,
}

Locale is a core struct representing a Unicode Locale Identifier.

A locale is made of two parts:

• langid - Unicode Language Identifier
• extensions - A set of Unicode Extensions

Locale exposes all of the same methods as LanguageIdentifier, and on top of that is able to parse, manipulate and serialize unicode extension fields.

Examples

use unic_locale_impl::Locale;

let loc: Locale = "en-US-u-ca-buddhist".parse()
    .expect("Failed to parse.");

assert_eq!(loc.language(), "en");
assert_eq!(loc.script(), None);
assert_eq!(loc.region(), Some("US"));
assert_eq!(loc.variants().len(), 0);
assert_eq!(loc.extensions.unicode.keyword("ca")
    .expect("Getting keyword failed.")
    .collect::<Vec<_>>(),
    &["buddhist"]);

Parsing

Unicode recognizes three levels of standard conformance for a locale:

• well-formed - syntactically correct
• valid - well-formed and only uses registered language subtags, extensions, keywords, types...
• canonical - valid and no deprecated codes or structure.

At the moment parsing normalizes a well-formed language identifier converting _ separators to - and adjusting casing to conform to the Unicode standard.

Any bogus subtags will cause the parsing to fail with an error. No subtag validation is performed.

Examples:

use unic_locale_impl::Locale;

let loc: Locale = "eN_latn_Us-Valencia_u-hC-H12".parse()
    .expect("Failed to parse.");

assert_eq!(loc.language(), "en");
assert_eq!(loc.script(), Some("Latn"));
assert_eq!(loc.region(), Some("US"));
assert_eq!(loc.variants().collect::<Vec<_>>(), &["valencia"]);

Fields

langid: LanguageIdentifier

extensions: ExtensionsMap

Methods

impl Locale

pub fn from_bytes(v: &[u8]) -> Result<Locale, LocaleError>

A constructor which takes a utf8 slice, parses it and produces a well-formed Locale.

Examples

use unic_locale_impl::Locale;

let loc = Locale::from_bytes("en-US-u-hc-h12".as_bytes())
    .expect("Parsing failed.");

assert_eq!(loc.to_string(), "en-US-u-hc-h12");

pub fn from_parts<S>(
    language: Option<S>,
    script: Option<S>,
    region: Option<S>,
    variants: &[S],
    extensions: Option<ExtensionsMap>
) -> Result<Locale, LocaleError> where
    S: AsRef<[u8]>, 

A constructor which takes optional subtags as AsRef<[u8]>, parses them and produces a well-formed Locale.

Examples

use unic_locale_impl::Locale;

let loc = Locale::from_parts(Some("fr"), None, Some("CA"), &[], None)
    .expect("Parsing failed.");

assert_eq!(loc.to_string(), "fr-CA");

pub fn into_raw_parts(
    self
) -> (Option<u64>, Option<u32>, Option<u32>, Option<Box<[u64]>>, String)

Consumes Locale and produces raw internal representations of all subtags in form of u64/u32.

Primarily used for storing internal representation and restoring via from_raw_parts_unchecked.

Examples

use unic_locale_impl::Locale;
use tinystr::{TinyStr8, TinyStr4};

let loc: Locale = "en-US".parse()
    .expect("Parsing failed.");

let (lang, script, region, variants, extensions) = loc.into_raw_parts();

let loc2 = Locale::from_raw_parts_unchecked(
    lang.map(|l| unsafe { TinyStr8::new_unchecked(l) }),
    script.map(|s| unsafe { TinyStr4::new_unchecked(s) }),
    region.map(|r| unsafe { TinyStr4::new_unchecked(r) }),
    variants.map(|v| v.into_iter().map(|v| unsafe { TinyStr8::new_unchecked(*v) }).collect()),
    extensions.parse().unwrap()
);

assert_eq!(loc2.to_string(), "en-US");

pub fn from_raw_parts_unchecked(
    language: Option<TinyStr8>,
    script: Option<TinyStr4>,
    region: Option<TinyStr4>,
    variants: Option<Box<[TinyStr8]>>,
    extensions: ExtensionsMap
) -> Locale

Consumes raw representation of subtags generating new Locale without any checks.

Primarily used for restoring internal representation.

Examples

use unic_locale_impl::Locale;
use tinystr::{TinyStr8, TinyStr4};

let loc: Locale = "en-US".parse()
    .expect("Parsing failed.");

let (lang, script, region, variants, extensions) = loc.into_raw_parts();

let loc2 = unsafe { Locale::from_raw_parts_unchecked(
    lang.map(|l| unsafe { TinyStr8::new_unchecked(l) }),
    script.map(|s| unsafe { TinyStr4::new_unchecked(s) }),
    region.map(|r| unsafe { TinyStr4::new_unchecked(r) }),
    variants.map(|v| v.into_iter().map(|v| unsafe { TinyStr8::new_unchecked(*v) }).collect()),
    extensions.parse().unwrap()
) };

assert_eq!(loc2.to_string(), "en-US");

pub fn matches<O>(
    &self,
    other: &O,
    self_as_range: bool,
    other_as_range: bool
) -> bool where
    O: AsRef<Locale>, 

Compares a Locale to another AsRef<Locale allowing for either side to use the missing fields as wildcards.

This allows for matching between en (treated as en-*-*-*) and en-US.

Examples

use unic_locale_impl::Locale;

let loc1: Locale = "en".parse()
    .expect("Parsing failed.");

let loc2: Locale = "en-US".parse()
    .expect("Parsing failed.");

assert_ne!(loc1, loc2); // "en" != "en-US"
assert_ne!(loc1.to_string(), loc2.to_string()); // "en" != "en-US"

assert_eq!(loc1.matches(&loc2, false, false), false); // "en" != "en-US"
assert_eq!(loc1.matches(&loc2, true, false), true); // "en-*-*-*" == "en-US"
assert_eq!(loc1.matches(&loc2, false, true), false); // "en" != "en-*-US-*"
assert_eq!(loc1.matches(&loc2, true, true), true); // "en-*-*-*" == "en-*-US-*"

pub fn language(&self) -> &str

Returns the language subtag of the Locale.

If the language is empty, "und" is returned.

Examples

use unic_locale_impl::Locale;

let loc1: Locale = "de-AT".parse()
    .expect("Parsing failed.");

assert_eq!(loc1.language(), "de");

let loc2: Locale = "und-AT".parse()
    .expect("Parsing failed.");

assert_eq!(loc2.language(), "und");

pub fn set_language<S>(&mut self, language: S) -> Result<(), LocaleError> where
    S: AsRef<[u8]>, 

Sets the language subtag of the Locale.

Examples

use unic_locale_impl::Locale;

let mut loc: Locale = "de-Latn-AT".parse()
    .expect("Parsing failed.");

loc.set_language("fr")
    .expect("Parsing failed.");

assert_eq!(loc.to_string(), "fr-Latn-AT");

pub fn clear_language(&mut self)

Clears the language subtag of the Locale.

An empty language subtag is serialized to und.

Examples

use unic_locale_impl::Locale;

let mut loc: Locale = "de-Latn-AT".parse()
    .expect("Parsing failed.");

loc.clear_language();

assert_eq!(loc.to_string(), "und-Latn-AT");

pub fn script(&self) -> Option<&str>

Returns the script subtag of the Locale, if set.

Examples

use unic_locale_impl::Locale;

let loc1: Locale = "de-Latn-AT".parse()
    .expect("Parsing failed.");

assert_eq!(loc1.script(), Some("Latn"));

let loc2: Locale = "de-AT".parse()
    .expect("Parsing failed.");

assert_eq!(loc2.script(), None);

pub fn set_script<S>(&mut self, script: S) -> Result<(), LocaleError> where
    S: AsRef<[u8]>, 

Sets the script subtag of the Locale.

Examples

use unic_locale_impl::Locale;

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

loc.set_script("Cyrl")
    .expect("Parsing failed.");

assert_eq!(loc.to_string(), "sr-Cyrl");

pub fn clear_script(&mut self)

Clears the script subtag of the Locale.

Examples

use unic_locale_impl::Locale;

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

loc.clear_script();

assert_eq!(loc.to_string(), "sr");

pub fn region(&self) -> Option<&str>

Returns the region subtag of the Locale, if set.

Examples

use unic_locale_impl::Locale;

let loc1: Locale = "de-Latn-AT".parse()
    .expect("Parsing failed.");

assert_eq!(loc1.region(), Some("AT"));

let loc2: Locale = "de".parse()
    .expect("Parsing failed.");

assert_eq!(loc2.region(), None);

pub fn set_region<S>(&mut self, region: S) -> Result<(), LocaleError> where
    S: AsRef<[u8]>, 

Sets the region subtag of the Locale.

Examples

use unic_locale_impl::Locale;

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

loc.set_region("CA")
    .expect("Parsing failed.");

assert_eq!(loc.to_string(), "fr-CA");

pub fn clear_region(&mut self)

Clears the region subtag of the Locale.

Examples

use unic_locale_impl::Locale;

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

loc.clear_region();

assert_eq!(loc.to_string(), "fr");

pub fn variants(&self) -> impl ExactSizeIterator

Returns a vector of variants subtags of the Locale.

Examples

use unic_locale_impl::Locale;

let loc1: Locale = "ca-ES-valencia".parse()
    .expect("Parsing failed.");

assert_eq!(loc1.variants().collect::<Vec<_>>(), &["valencia"]);

let loc2: Locale = "de".parse()
    .expect("Parsing failed.");

assert_eq!(loc2.variants().len(), 0);

pub fn set_variants<S>(
    &mut self,
    variants: impl IntoIterator<Item = S>
) -> Result<(), LocaleError> where
    S: AsRef<[u8]>, 

Sets variant subtags of the Locale.

Examples

use unic_locale_impl::Locale;

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

loc.set_variants(&["valencia"])
    .expect("Parsing failed.");

assert_eq!(loc.to_string(), "ca-ES-valencia");

pub fn has_variant<S>(&self, variant: S) -> Result<bool, LocaleError> where
    S: AsRef<[u8]>, 

Tests if a variant subtag is present in the Locale.

Examples

use unic_locale_impl::Locale;

let mut loc: Locale = "ca-ES-macos".parse()
    .expect("Parsing failed.");

assert_eq!(loc.has_variant("valencia"), Ok(false));
assert_eq!(loc.has_variant("macos"), Ok(true));

pub fn clear_variants(&mut self)

Clears variant subtags of the Locale.

Examples

use unic_locale_impl::Locale;

let mut loc: Locale = "ca-ES-valencia".parse()
    .expect("Parsing failed.");

loc.clear_variants();

assert_eq!(loc.to_string(), "ca-ES");

pub fn character_direction(&self) -> CharacterDirection

Returns character direction of the Locale.

Examples

use unic_locale_impl::{Locale, CharacterDirection};

let loc1: Locale = "es-AR".parse()
    .expect("Parsing failed.");
let loc2: Locale = "fa".parse()
    .expect("Parsing failed.");

assert_eq!(loc1.character_direction(), CharacterDirection::LTR);
assert_eq!(loc2.character_direction(), CharacterDirection::RTL);

Trait Implementations

impl AsRef<LanguageIdentifier> for Locale

fn as_ref(&self) -> &LanguageIdentifier

Performs the conversion.

impl AsRef<Locale> for Locale

fn as_ref(&self) -> &Locale

Performs the conversion.

impl Clone for Locale

fn clone(&self) -> Locale

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Locale

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Locale

fn default() -> Locale

Returns the "default value" for a type.

impl Display for Locale

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

impl Eq for Locale

impl From<LanguageIdentifier> for Locale

fn from(langid: LanguageIdentifier) -> Locale

Performs the conversion.

impl FromStr for Locale

type Err = LocaleError

The associated error which can be returned from parsing.

fn from_str(source: &str) -> Result<Locale, <Locale as FromStr>::Err>

Parses a string s to return a value of this type.

impl Hash for Locale

fn hash<__H>(&self, state: &mut __H) where
    __H: Hasher, 

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl Into<LanguageIdentifier> for Locale

fn into(self) -> LanguageIdentifier

Performs the conversion.

impl Ord for Locale

fn cmp(&self, other: &Locale) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl PartialEq<Locale> for Locale

fn eq(&self, other: &Locale) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Locale) -> bool

This method tests for !=.

impl PartialOrd<Locale> for Locale

fn partial_cmp(&self, other: &Locale) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Locale) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Locale) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Locale) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Locale) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralEq for Locale

impl StructuralPartialEq for Locale