Trait icu_locale::preferences::PreferenceKey

pub trait PreferenceKey: Sized {
    // Provided methods
    fn try_from_key_value(
        _key: &Key,
        _value: &Value,
    ) -> Result<Option<Self>, PreferencesParseError> { ... }
    fn unicode_extension_key() -> Option<Key> { ... }
    fn unicode_extension_value(&self) -> Option<Value> { ... }
}
Expand description

A low-level trait implemented on each preference exposed in component preferences.

PreferenceKey has to be implemented on preferences that are to be included in Formatter preferences. The trait may be implemented to indicate that the given preference has a unicode key corresponding to it or be a custom one.

ICU4X provides an implementation of PreferenceKey for all Unicode Extension Keys. The only external use of this trait is to implement it on custom preferences that are to be included in a component preferences bag.

The below example show cases a manual generation of an em (emoji) unicode extension key and a custom struct to showcase the difference in their behavior. For all use purposes, the EmojiPresentationStyle preference exposed by this crate should be used.

§Examples

use icu::locale::{
  extensions::unicode::{key, Key, value, Value},
  preferences::{
    define_preferences, PreferenceKey,
    extensions::unicode::errors::PreferencesParseError,
  },
};

#[non_exhaustive]
#[derive(Debug, Clone, Eq, PartialEq, Copy)]
pub enum EmojiPresentationStyle {
    Emoji,
    Text,
    Default,
}

impl PreferenceKey for EmojiPresentationStyle {
    fn unicode_extension_key() -> Option<Key> {
        Some(key!("em"))
    }

    fn try_from_key_value(
        key: &Key,
        value: &Value,
    ) -> Result<Option<Self>, PreferencesParseError> {
        if Self::unicode_extension_key() == Some(*key) {
            let subtag = value.as_single_subtag()
                              .ok_or(PreferencesParseError::InvalidKeywordValue)?;
            match subtag.as_str() {
                "emoji" => Ok(Some(Self::Emoji)),
                "text" => Ok(Some(Self::Text)),
                "default" => Ok(Some(Self::Default)),
                _ => Err(PreferencesParseError::InvalidKeywordValue)
            }
        } else {
            Ok(None)
        }
    }

    fn unicode_extension_value(&self) -> Option<Value> {
        Some(match self {
            EmojiPresentationStyle::Emoji => value!("emoji"),
            EmojiPresentationStyle::Text => value!("text"),
            EmojiPresentationStyle::Default => value!("default"),
        })
    }
}

#[non_exhaustive]
#[derive(Debug, Clone, Eq, PartialEq)]
pub struct CustomFormat {
    value: String
}

impl PreferenceKey for CustomFormat {}

define_preferences!(
    MyFormatterPreferences,
    {
        emoji: EmojiPresentationStyle,
        custom: CustomFormat
    }
);

Provided Methods§

fn try_from_key_value( _key: &Key, _value: &Value, ) -> Result<Option<Self>, PreferencesParseError>

Optional constructor of the given preference. It takes the unicode extension key and if the key matches it attemptes to construct the preference based on the given value. If the value is not a valid value for the given key, the constructor throws.

fn unicode_extension_key() -> Option<Key>

Retrieve unicode extension key corresponding to a given preference.

fn unicode_extension_value(&self) -> Option<Value>

Retrieve unicode extension value corresponding to the given instance of the preference.

Object Safety§

This trait is not object safe.

Implementors§