Struct icu_provider::DataLocale

pub struct DataLocale {
    langid: LanguageIdentifier,
    keywords: Keywords,
    aux: Option<AuxiliaryKeys>,
}

A locale type optimized for use in fallbacking and the ICU4X data pipeline.

DataLocale contains less functionality than Locale but more than LanguageIdentifier for better size and performance while still meeting the needs of the ICU4X data pipeline.

Examples

Convert a Locale to a DataLocale and back:

use icu_locid::locale;
use icu_provider::DataLocale;

let locale = locale!("en-u-ca-buddhist");
let data_locale = DataLocale::from(locale);
let locale = data_locale.into_locale();

assert_eq!(locale, locale!("en-u-ca-buddhist"));

You can alternatively create a DataLocale from a borrowed Locale, which is more efficient than cloning the Locale, but less efficient than converting an owned Locale:

use icu_locid::locale;
use icu_provider::DataLocale;

let locale1 = locale!("en-u-ca-buddhist");
let data_locale = DataLocale::from(&locale1);
let locale2 = data_locale.into_locale();

assert_eq!(locale1, locale2);

If you are sure that you have no Unicode keywords, start with LanguageIdentifier:

use icu_locid::langid;
use icu_provider::DataLocale;

let langid = langid!("es-CA-valencia");
let data_locale = DataLocale::from(langid);
let langid = data_locale.get_langid();

assert_eq!(langid, langid!("es-CA-valencia"));

DataLocale only supports -u keywords, to reflect the current state of CLDR data lookup and fallback. This may change in the future.

use icu_locid::{locale, Locale};
use icu_provider::DataLocale;

let locale = "hi-t-en-h0-hybrid-u-attr-ca-buddhist"
    .parse::<Locale>()
    .unwrap();
let data_locale = DataLocale::from(locale);

assert_eq!(data_locale.into_locale(), locale!("hi-u-ca-buddhist"));

Fields

langid: LanguageIdentifier

keywords: Keywords

aux: Option<AuxiliaryKeys>

Implementations

impl DataLocale

pub fn strict_cmp(&self, other: &[u8]) -> Ordering

Compare this DataLocale with BCP-47 bytes.

The return value is equivalent to what would happen if you first converted this DataLocale to a BCP-47 string and then performed a byte comparison.

This function is case-sensitive and results in a total order, so it is appropriate for binary search. The only argument producing Ordering::Equal is self.to_string().

Examples

use icu_provider::DataLocale;
use std::cmp::Ordering;

let bcp47_strings: &[&str] = &[
    "ca",
    "ca-ES",
    "ca-ES-u-ca-buddhist",
    "ca-ES-valencia",
    "ca-ES-x-gbp",
    "ca-ES-x-gbp-short",
    "ca-ES-x-usd",
    "ca-ES-xyzabc",
    "ca-x-eur",
    "cat",
    "pl-Latn-PL",
    "und",
    "und-fonipa",
    "und-u-ca-hebrew",
    "und-u-ca-japanese",
    "und-x-mxn",
    "zh",
];

for ab in bcp47_strings.windows(2) {
    let a = ab[0];
    let b = ab[1];
    assert_eq!(a.cmp(b), Ordering::Less, "strings: {} < {}", a, b);
    let a_loc: DataLocale = a.parse().unwrap();
    assert_eq!(
        a_loc.strict_cmp(a.as_bytes()),
        Ordering::Equal,
        "strict_cmp: {} == {}",
        a_loc,
        a
    );
    assert_eq!(
        a_loc.strict_cmp(b.as_bytes()),
        Ordering::Less,
        "strict_cmp: {} < {}",
        a_loc,
        b
    );
    let b_loc: DataLocale = b.parse().unwrap();
    assert_eq!(
        b_loc.strict_cmp(b.as_bytes()),
        Ordering::Equal,
        "strict_cmp: {} == {}",
        b_loc,
        b
    );
    assert_eq!(
        b_loc.strict_cmp(a.as_bytes()),
        Ordering::Greater,
        "strict_cmp: {} > {}",
        b_loc,
        a
    );
}

Comparison against invalid strings:

use icu_provider::DataLocale;

let invalid_strings: &[&str] = &[
    // Less than "ca-ES"
    "CA",
    "ar-x-gbp-FOO",
    // Greater than "ca-ES-x-gbp"
    "ca_ES",
    "ca-ES-x-gbp-FOO",
];

let data_locale = "ca-ES-x-gbp".parse::<DataLocale>().unwrap();

for s in invalid_strings.iter() {
    let expected_ordering = "ca-ES-x-gbp".cmp(s);
    let actual_ordering = data_locale.strict_cmp(s.as_bytes());
    assert_eq!(expected_ordering, actual_ordering, "{}", s);
}

impl DataLocale

pub fn is_empty(&self) -> bool

Returns whether this DataLocale has all empty fields (no components).

See also:

• DataLocale::is_und()
• DataLocale::is_langid_und()

Examples

use icu_provider::DataLocale;

assert!("und".parse::<DataLocale>().unwrap().is_empty());
assert!(!"und-u-ca-buddhist"
    .parse::<DataLocale>()
    .unwrap()
    .is_empty());
assert!(!"und-x-aux".parse::<DataLocale>().unwrap().is_empty());
assert!(!"ca-ES".parse::<DataLocale>().unwrap().is_empty());

pub fn total_cmp(&self, other: &Self) -> Ordering

Returns an ordering suitable for use in BTreeSet.

The ordering may or may not be equivalent to string ordering, and it may or may not be stable across ICU4X releases.

pub fn is_und(&self) -> bool

Returns whether this DataLocale is und in the locale and extensions portion.

This ignores auxiliary keys.

See also:

• DataLocale::is_empty()
• DataLocale::is_langid_und()

Examples

use icu_provider::DataLocale;

assert!("und".parse::<DataLocale>().unwrap().is_und());
assert!(!"und-u-ca-buddhist".parse::<DataLocale>().unwrap().is_und());
assert!("und-x-aux".parse::<DataLocale>().unwrap().is_und());
assert!(!"ca-ES".parse::<DataLocale>().unwrap().is_und());

pub fn is_langid_und(&self) -> bool

Returns whether the LanguageIdentifier associated with this request is und.

This ignores extension keywords and auxiliary keys.

See also:

• DataLocale::is_empty()
• DataLocale::is_und()

Examples

use icu_provider::DataLocale;

assert!("und".parse::<DataLocale>().unwrap().is_langid_und());
assert!("und-u-ca-buddhist"
    .parse::<DataLocale>()
    .unwrap()
    .is_langid_und());
assert!("und-x-aux".parse::<DataLocale>().unwrap().is_langid_und());
assert!(!"ca-ES".parse::<DataLocale>().unwrap().is_langid_und());

pub fn get_langid(&self) -> LanguageIdentifier

Gets the LanguageIdentifier for this DataLocale.

This may allocate memory if there are variant subtags. If you need only the language, script, and/or region subtag, use the specific getters for those subtags:

• DataLocale::language()
• DataLocale::script()
• DataLocale::region()

If you have ownership over the DataLocale, use DataLocale::into_locale() and then access the id field.

Examples

use icu_locid::langid;
use icu_provider::prelude::*;

const FOO_BAR: DataKey = icu_provider::data_key!("foo/bar@1");

let req_no_langid = DataRequest {
    locale: &Default::default(),
    metadata: Default::default(),
};

let req_with_langid = DataRequest {
    locale: &langid!("ar-EG").into(),
    metadata: Default::default(),
};

assert_eq!(req_no_langid.locale.get_langid(), langid!("und"));
assert_eq!(req_with_langid.locale.get_langid(), langid!("ar-EG"));

pub fn set_langid(&mut self, lid: LanguageIdentifier)

Overrides the entire LanguageIdentifier portion of this DataLocale.

pub fn into_locale(self) -> Locale

Converts this DataLocale into a Locale.

See also DataLocale::get_langid().

Examples

use icu_locid::{
    langid, locale,
    subtags::{language, region},
};
use icu_provider::prelude::*;

let locale: DataLocale = locale!("it-IT-u-ca-coptic").into();

assert_eq!(locale.get_langid(), langid!("it-IT"));
assert_eq!(locale.language(), language!("it"));
assert_eq!(locale.script(), None);
assert_eq!(locale.region(), Some(region!("IT")));

let locale = locale.into_locale();
assert_eq!(locale, locale!("it-IT-u-ca-coptic"));

Auxiliary keys are retained:

use icu_provider::prelude::*;
use writeable::assert_writeable_eq;

let data_locale: DataLocale = "und-u-nu-arab-x-gbp".parse().unwrap();
assert_writeable_eq!(data_locale, "und-u-nu-arab-x-gbp");

let recovered_locale = data_locale.into_locale();
assert_writeable_eq!(recovered_locale, "und-u-nu-arab-x-gbp");

pub fn language(&self) -> Language

Returns the Language for this DataLocale.

pub fn set_language(&mut self, language: Language)

Returns the Language for this DataLocale.

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

Returns the Script for this DataLocale.

pub fn set_script(&mut self, script: Option<Script>)

Sets the Script for this DataLocale.

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

Returns the Region for this DataLocale.

pub fn set_region(&mut self, region: Option<Region>)

Sets the Region for this DataLocale.

pub fn has_variants(&self) -> bool

Returns whether there are any Variant subtags in this DataLocale.

pub fn set_variants(&mut self, variants: Variants)

Sets all Variants on this DataLocale, overwriting any that were there previously.

pub fn clear_variants(&mut self) -> Variants

Removes all Variant subtags in this DataLocale.

pub fn get_unicode_ext(&self, key: &Key) -> Option<Value>

Gets the value of the specified Unicode extension keyword for this DataLocale.

pub fn has_unicode_ext(&self) -> bool

Returns whether there are any Unicode extension keywords in this DataLocale.

pub fn contains_unicode_ext(&self, key: &Key) -> bool

Returns whether a specific Unicode extension keyword is present in this DataLocale.

pub fn matches_unicode_ext(&self, key: &Key, value: &Value) -> bool

Returns whether this DataLocale contains a Unicode extension keyword with the specified key and value.

Examples

use icu_locid::extensions::unicode::{key, value};
use icu_provider::prelude::*;

let locale: DataLocale = "it-IT-u-ca-coptic".parse().expect("Valid BCP-47");

assert_eq!(locale.get_unicode_ext(&key!("hc")), None);
assert_eq!(locale.get_unicode_ext(&key!("ca")), Some(value!("coptic")));
assert!(locale.matches_unicode_ext(&key!("ca"), &value!("coptic"),));

pub fn set_unicode_ext(&mut self, key: Key, value: Value) -> Option<Value>

Sets the value for a specific Unicode extension keyword on this DataLocale.

pub fn remove_unicode_ext(&mut self, key: &Key) -> Option<Value>

Removes a specific Unicode extension keyword from this DataLocale, returning the value if it was present.

pub fn retain_unicode_ext<F>(&mut self, predicate: F)

where F: FnMut(&Key) -> bool,

Retains a subset of keywords as specified by the predicate function.

pub fn get_aux(&self) -> Option<&AuxiliaryKeys>

Gets the auxiliary key for this DataLocale.

For more information and examples, see AuxiliaryKeys.

pub fn has_aux(&self) -> bool

Returns whether this DataLocale has an auxiliary key.

For more information and examples, see AuxiliaryKeys.

pub fn set_aux(&mut self, value: AuxiliaryKeys) -> Option<AuxiliaryKeys>

Sets an auxiliary key on this DataLocale.

Returns the previous auxiliary key if present.

For more information and examples, see AuxiliaryKeys.

pub fn remove_aux(&mut self) -> Option<AuxiliaryKeys>

Remove an auxiliary key, if present. Returns the removed auxiliary key.

Examples

use icu_locid::langid;
use icu_provider::prelude::*;
use writeable::assert_writeable_eq;

let mut data_locale: DataLocale = langid!("ar-EG").into();
let aux = "gbp"
    .parse::<AuxiliaryKeys>()
    .expect("contains valid characters");
data_locale.set_aux(aux);
assert_writeable_eq!(data_locale, "ar-EG-x-gbp");

let maybe_aux = data_locale.remove_aux();
assert_writeable_eq!(data_locale, "ar-EG");
assert_writeable_eq!(maybe_aux.unwrap(), "gbp");

Trait Implementations

impl Clone for DataLocale

fn clone(&self) -> DataLocale

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for DataLocale

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

Formats the value using the given formatter.

impl<'a> Default for &'a DataLocale

fn default() -> Self

Returns the “default value” for a type.

impl Default for DataLocale

fn default() -> DataLocale

Returns the “default value” for a type.

impl Display for DataLocale

This trait is implemented for compatibility with fmt!. To create a string, Writeable::write_to_string is usually more efficient.

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

Formats the value using the given formatter.

impl From<&LanguageIdentifier> for DataLocale

fn from(langid: &LanguageIdentifier) -> Self

Converts to this type from the input type.

impl From<&Locale> for DataLocale

fn from(locale: &Locale) -> Self

Converts to this type from the input type.

impl From<LanguageIdentifier> for DataLocale

fn from(langid: LanguageIdentifier) -> Self

Converts to this type from the input type.

impl From<Locale> for DataLocale

fn from(locale: Locale) -> Self

Converts to this type from the input type.

impl FromStr for DataLocale

type Err = DataError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

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

impl Hash for DataLocale

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

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for DataLocale

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

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Writeable for DataLocale

fn write_to<W: Write + ?Sized>(&self, sink: &mut W) -> Result

Writes a string to the given sink. Errors from the sink are bubbled up. The default implementation delegates to write_to_parts, and discards any Part annotations.

fn writeable_length_hint(&self) -> LengthHint

Returns a hint for the number of UTF-8 bytes that will be written to the sink.

fn write_to_string(&self) -> Cow<'_, str>

Creates a new String with the data from this Writeable. Like ToString, but smaller and faster.

fn write_to_parts<S>(&self, sink: &mut S) -> Result<(), Error>

where S: PartsWrite + ?Sized,

Write bytes and Part annotations to the given sink. Errors from the sink are bubbled up. The default implementation delegates to write_to, and doesn’t produce any Part annotations.

fn writeable_cmp_bytes(&self, other: &[u8]) -> Ordering

Compares the contents of this Writeable to the given bytes without allocating a String to hold the Writeable contents.

impl Eq for DataLocale

impl StructuralPartialEq for DataLocale