Struct KnownValuesStore

Source

pub struct KnownValuesStore { /* private fields */ }

Expand description

A store that maps between Known Values and their assigned names.

The KnownValuesStore provides a bidirectional mapping between:

Numeric values (u64) and their corresponding KnownValue instances
String names and their corresponding KnownValue instances

This enables efficient lookup in both directions, making it possible to:

Find the name for a given numeric value
Find the numeric value for a given name
Retrieve complete KnownValue instances by either name or value

The store is typically populated with predefined Known Values from the registry, but can also be extended with custom values.

§Examples

use std::collections::HashMap;

use known_values::{KnownValue, KnownValuesStore};

// Create a store with predefined Known Values
let store = KnownValuesStore::new([
    known_values::IS_A,
    known_values::NOTE,
    known_values::SIGNED,
]);

// Look up a Known Value by name
let is_a = store.known_value_named("isA").unwrap();
assert_eq!(is_a.value(), 1);

// Look up a name for a raw value
let name = store.name(KnownValue::new(3));
assert_eq!(name, "signed");

// Insert a custom Known Value
let mut custom_store = store.clone();
custom_store
    .insert(KnownValue::new_with_name(100u64, "customValue".to_string()));
assert_eq!(
    custom_store
        .known_value_named("customValue")
        .unwrap()
        .value(),
    100
);

Implementations§

Source §

impl KnownValuesStore

Source

pub fn new<T>(known_values: T) -> Self
where T: IntoIterator<Item = KnownValue>,

Creates a new KnownValuesStore with the provided Known Values.

This constructor takes any iterable of KnownValue instances and populates the store with them, creating mappings from both raw values and names to the corresponding KnownValue instances.

§Examples

use known_values::KnownValuesStore;

// Create a store with predefined Known Values
let store = KnownValuesStore::new([
    known_values::IS_A,
    known_values::NOTE,
    known_values::SIGNED,
]);

// Look up Known Values
assert_eq!(store.known_value_named("isA").unwrap().value(), 1);
assert_eq!(store.known_value_named("note").unwrap().value(), 4);

Source

pub fn insert(&mut self, known_value: KnownValue)

Inserts a KnownValue into the store.

If the KnownValue has an assigned name, it will be indexed by both its raw value and its name. If a KnownValue with the same raw value or name already exists in the store, it will be replaced.

§Examples

use known_values::{KnownValue, KnownValuesStore};

let mut store = KnownValuesStore::default();
store.insert(KnownValue::new_with_name(100u64, "customValue".to_string()));
assert_eq!(store.known_value_named("customValue").unwrap().value(), 100);

Source

pub fn assigned_name(&self, known_value: &KnownValue) -> Option<&str>

Returns the assigned name for a KnownValue, if present in the store.

§Examples

use known_values::{KnownValue, KnownValuesStore};

let store = KnownValuesStore::new([known_values::IS_A, known_values::NOTE]);

assert_eq!(store.assigned_name(&known_values::IS_A), Some("isA"));
assert_eq!(store.assigned_name(&KnownValue::new(999)), None);

Source

pub fn name(&self, known_value: KnownValue) -> String

Returns a human-readable name for a KnownValue.

If the KnownValue has an assigned name in the store, that name is returned. Otherwise, the KnownValue’s default name (which may be its numeric value as a string) is returned.

§Examples

use known_values::{KnownValue, KnownValuesStore};

let store = KnownValuesStore::new([known_values::IS_A, known_values::NOTE]);

assert_eq!(store.name(known_values::IS_A), "isA");
assert_eq!(store.name(KnownValue::new(999)), "999");

Source

pub fn known_value_named(&self, assigned_name: &str) -> Option<&KnownValue>

Looks up a KnownValue by its assigned name.

Returns a reference to the KnownValue if found, or None if no KnownValue with the given name exists in the store.

§Examples

use known_values::KnownValuesStore;

let store = KnownValuesStore::new([known_values::IS_A, known_values::NOTE]);

let is_a = store.known_value_named("isA").unwrap();
assert_eq!(is_a.value(), 1);

assert!(store.known_value_named("nonexistent").is_none());

Source

pub fn known_value_for_raw_value( raw_value: u64, known_values: Option<&Self>, ) -> KnownValue

Retrieves a KnownValue for a raw value, using a store if provided.

This static method allows looking up a KnownValue by its raw numeric value:

If a store is provided and contains a mapping for the raw value, that KnownValue is returned
Otherwise, a new KnownValue with no assigned name is created and returned

§Examples

use known_values::KnownValuesStore;

let store = KnownValuesStore::new([known_values::IS_A, known_values::NOTE]);

// Known value from store
let is_a = KnownValuesStore::known_value_for_raw_value(1, Some(&store));
assert_eq!(is_a.name(), "isA");

// Unknown value creates a new KnownValue
let unknown =
    KnownValuesStore::known_value_for_raw_value(999, Some(&store));
assert_eq!(unknown.name(), "999");

// No store provided also creates a new KnownValue
let unknown = KnownValuesStore::known_value_for_raw_value(1, None);
assert_eq!(unknown.name(), "1");

Source

pub fn known_value_for_name( name: &str, known_values: Option<&Self>, ) -> Option<KnownValue>

Attempts to find a KnownValue by its name, using a store if provided.

This static method allows looking up a KnownValue by its name:

If a store is provided and contains a mapping for the name, that KnownValue is returned
Otherwise, None is returned

§Examples

use known_values::KnownValuesStore;

let store = KnownValuesStore::new([known_values::IS_A, known_values::NOTE]);

// Known value from store
let is_a = KnownValuesStore::known_value_for_name("isA", Some(&store));
assert_eq!(is_a.unwrap().value(), 1);

// Unknown name returns None
assert!(
    KnownValuesStore::known_value_for_name("unknown", Some(&store))
        .is_none()
);

// No store provided also returns None
assert!(KnownValuesStore::known_value_for_name("isA", None).is_none());

Source

pub fn name_for_known_value( known_value: KnownValue, known_values: Option<&Self>, ) -> String

Returns a human-readable name for a KnownValue, using a store if provided.

This static method allows getting a name for a KnownValue:

If a store is provided and contains a mapping for the KnownValue, its assigned name is returned
Otherwise, the KnownValue’s default name (which may be its numeric value as a string) is returned

§Examples

use known_values::{KnownValue, KnownValuesStore};

let store = KnownValuesStore::new([known_values::IS_A, known_values::NOTE]);

// Known value from store
let name = KnownValuesStore::name_for_known_value(
    known_values::IS_A,
    Some(&store),
);
assert_eq!(name, "isA");

// Unknown value in store uses KnownValue's name method
let name = KnownValuesStore::name_for_known_value(
    KnownValue::new(999),
    Some(&store),
);
assert_eq!(name, "999");

// No store provided also uses KnownValue's name method
let name = KnownValuesStore::name_for_known_value(known_values::IS_A, None);
assert_eq!(name, "isA");