Struct icu_provider::AuxiliaryKeys

pub struct AuxiliaryKeys {
    value: AuxiliaryKeysInner,
}

The “auxiliary key” is an annotation on DataLocale that can contain an arbitrary information that does not fit into the LanguageIdentifier or Keywords.

A DataLocale can have multiple auxiliary keys, represented by this struct. The auxiliary keys are stored as private use subtags following -x-.

An auxiliary key currently allows 1-8 lowercase alphanumerics.

🚧 This code is experimental; it may change at any time, in breaking or non-breaking ways, including in SemVer minor releases. It can be enabled with the "experimental" Cargo feature of the `icu_provider` crate. Use with caution. #3632

Examples

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

let mut data_locale: DataLocale = langid!("ar-EG").into();
assert_writeable_eq!(data_locale, "ar-EG");
assert!(!data_locale.has_aux());
assert_eq!(data_locale.get_aux(), None);

let aux = "gbp"
    .parse::<AuxiliaryKeys>()
    .expect("contains valid characters");

data_locale.set_aux(aux);
assert_writeable_eq!(data_locale, "ar-EG-x-gbp");
assert!(data_locale.has_aux());
assert_eq!(data_locale.get_aux(), Some(&"gbp".parse().unwrap()));

Multiple auxiliary keys are allowed:

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

let data_locale = "ar-EG-x-gbp-long".parse::<DataLocale>().unwrap();
assert_writeable_eq!(data_locale, "ar-EG-x-gbp-long");
assert_eq!(data_locale.get_aux().unwrap().iter().count(), 2);

Not all strings are valid auxiliary keys. The string must be well-formed and case-normalized:

use icu_provider::prelude::*;

assert!("abcdefg".parse::<AuxiliaryKeys>().is_ok());
assert!("abc-xyz".parse::<AuxiliaryKeys>().is_ok());

assert!("".parse::<AuxiliaryKeys>().is_err());
assert!("!@#$%".parse::<AuxiliaryKeys>().is_err());
assert!("abc_xyz".parse::<AuxiliaryKeys>().is_err());
assert!("ABC123".parse::<AuxiliaryKeys>().is_err());

Fields

value: AuxiliaryKeysInner

Implementations

impl AuxiliaryKeys

pub fn try_from_iter( iter: impl IntoIterator<Item = Subtag>, ) -> Result<Self, DataError>

Creates an AuxiliaryKeys from an iterator of individual keys.

Examples

use icu_locid::extensions::private::subtag;
use icu_provider::prelude::*;

// Single auxiliary key:
let a = AuxiliaryKeys::try_from_iter([subtag!("abc")]).unwrap();
let b = "abc".parse::<AuxiliaryKeys>().unwrap();
assert_eq!(a, b);

// Multiple auxiliary keys:
let a = AuxiliaryKeys::try_from_iter([subtag!("abc"), subtag!("defg")])
    .unwrap();
let b = "abc-defg".parse::<AuxiliaryKeys>().unwrap();
assert_eq!(a, b);

The iterator can’t be empty:

use icu_provider::prelude::*;

assert!(AuxiliaryKeys::try_from_iter([]).is_err());

pub const fn from_subtag(input: Subtag) -> Self

Creates an AuxiliaryKeys from a single subtag.

Examples

use icu_locid::extensions::private::subtag;
use icu_provider::prelude::*;

// Single auxiliary key:
let a = AuxiliaryKeys::from_subtag(subtag!("abc"));
let b = "abc".parse::<AuxiliaryKeys>().unwrap();
assert_eq!(a, b);

pub fn iter(&self) -> impl Iterator<Item = Subtag> + '_

Iterates over the components of the auxiliary key.

Example

use icu_locid::extensions::private::subtag;
use icu_provider::AuxiliaryKeys;

let aux: AuxiliaryKeys = "abc-defg".parse().unwrap();
assert_eq!(
    aux.iter().collect::<Vec<_>>(),
    vec![subtag!("abc"), subtag!("defg")]
);

pub(crate) const fn separator() -> char

Returns the internal separator byte used for auxiliary keys in data locales.

This is, according to BCP-47, an ASCII hyphen.

Trait Implementations

impl Clone for AuxiliaryKeys

fn clone(&self) -> AuxiliaryKeys

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for AuxiliaryKeys

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

Formats the value using the given formatter.

impl Display for AuxiliaryKeys

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<Subtag> for AuxiliaryKeys

fn from(subtag: Subtag) -> Self

Converts to this type from the input type.

impl FromStr for AuxiliaryKeys

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 AuxiliaryKeys

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 Ord for AuxiliaryKeys

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for AuxiliaryKeys

fn eq(&self, other: &AuxiliaryKeys) -> 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 PartialOrd for AuxiliaryKeys

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

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

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

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

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

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

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

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

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

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

impl Writeable for AuxiliaryKeys

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 AuxiliaryKeys

impl StructuralPartialEq for AuxiliaryKeys