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, Hash, Default)]
pub enum EmojiPresentationStyle {
    Emoji,
    Text,
    #[default]
    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, Hash)]
pub struct CustomFormat {
    value: String
}

impl PreferenceKey for CustomFormat {}

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