Struct XvcStore

pub struct XvcStore<T>
where
    T: Storable,
{ /* private fields */ }

A database table like store for type T

It’s used as the general purpose persistence data structure for all components. It contains an XvcEntity -> T map, and an index T -> Vec<XvcEntity> for these entries for quick reverse lookup. It loads these data from EventLog collections. It has basic functionality to insert, delete, filter and iterate over the elements.

Implementations

impl<T> XvcStore<T>

where T: Storable,

pub fn new() -> XvcStore<T>

Creates an empty store with empty maps and event logs.

pub fn from_event_logs( previous: EventLog<T>, current: EventLog<T>, ) -> XvcStore<T>

Creates a store from previous and current EventLog.

This is used when conversions between stores are required. When elements are inserted with XvcStore::insert, they are added to current and serialized to disk over and over. See https://github.com/iesahin/xvc/issues/45

pub fn all_event_log_for_entity( &self, entity: XvcEntity, ) -> Result<EventLog<T>, Error>

Returns all events associated with the entity

pub fn previous_event_log_for_entity( &self, entity: XvcEntity, ) -> Result<EventLog<T>, Error>

Returns (loaded) previous events for the entity

Doesn’t return events in the current invocation

pub fn insert(&mut self, entity: XvcEntity, value: T) -> Option<T>

Inserts an entity into the current event log, the map and the index.

Note that this shouldn’t be used in store conversions (from crate::VStore or crate::HStore). This function adds events to current set, and these are serialized. See https://github.com/iesahin/xvc/issues/45

pub fn update(&mut self, entity: XvcEntity, value: T) -> Option<T>

Updates the data associated with an entity.

This is equivalent to [remove] and [insert], and adds two events to the event log. Returns the previous value if there is one.

pub fn remove(&mut self, entity: XvcEntity) -> Option<T>

Removes the data associated with entity.

It returns the value if found, otherwise returns None.

pub fn from_dir(dir: &Path) -> Result<XvcStore<T>, Error>

Loads the timestamp named EventLog files from dir and replays them to build maps.

pub fn to_dir(&self, dir: &Path) -> Result<(), Error>

Saves the current EventLog to the directory. This is enough to reload it to the saved state.

pub fn len(&self) -> usize

Return the number of elements

pub fn is_empty(&self) -> bool

Returns true if the map is empty

pub fn subset<I>(&self, keys: I) -> Result<HStore<T>, Error>

where I: Iterator<Item = XvcEntity>,

A subset of this maps identified by XvcEntity elements of the iterator.

This can be used to split the map arbitrarily.

pub fn filter<F>(&self, predicate: F) -> HStore<T>

where F: Fn(&XvcEntity, &T) -> bool,

Creates a new map by calling the predicate with each value.

predicate must be a function or closure that returns bool.

This returns HStore not to create a new event log.

pub fn any<F>(&self, predicate: F) -> bool

where F: Fn(&XvcEntity, &T) -> bool,

Runs predicate for all elements and returns true if one of them is true.

predicate must be a function or closure that returns bool.

pub fn first(&self) -> Option<(&XvcEntity, &T)>

Returns the first element of the map

This is useful when there is only one element after Self::filter

pub fn entities_for(&self, value: &T) -> Option<&Vec<XvcEntity>>

where T: PartialEq,

Returns the entities for a value.

There may be more than one entity for a given value, hence it returns a Vec. It uses internal reverse index for fast lookup.

pub fn entity_by_value(&self, value: &T) -> Option<XvcEntity>

Returns the first entity matched with Self::entities_for

pub fn previous_events(&self) -> &EventLog<T>

Return the previous (immutable) EventLog.

The event log contains the Event records before the last load.

pub fn current_events(&self) -> &EventLog<T>

Return the current (mutable) EventLog.

The event log contains the Event records since the last load.

pub fn left_join<U>(&self, other: XvcStore<U>) -> XvcStore<(T, Option<U>)>

where U: Storable,

Performs a left join with XvcEntity keys.

The returned store contains (T, Option<U>) values that correspond to the identical XvcEntity values.

In SQL terms, this is a LEFT JOIN.

Note that, it may be more convenient to keep this relationship in a crate::R11Store relative to your use case.

use xvc_ecs::{XvcEntity, XvcStore};

let mut store1 = XvcStore::<String>::new();
store1.insert(10u128.into(), "John Doe".into());
store1.insert(12u128.into(), "George Mason".into());
store1.insert(19u128.into(), "Ali Canfield".into());

let mut store2 = XvcStore::<String>::new();
store2.insert(10u128.into(), "Carpenter".into());
store2.insert(17u128.into(), "Developer".into());
store2.insert(15u128.into(), "Plumber".into());
store2.insert(19u128.into(), "Artist".into());

let result = store1.left_join(store2);

assert_eq!(result.len(), 3);
assert_eq!(result[&10u128.into()], ("John Doe".into(), Some("Carpenter".into())));
assert_eq!(result[&12u128.into()], ("George Mason".into(), None));
assert_eq!(result[&19u128.into()], ("Ali Canfield".into(), Some("Artist".into())));

pub fn index_map(&self) -> Result<BTreeMap<T, XvcEntity>, Error>

Returns an inverted map to get entity values quickly

This uses entity_index with a caveat:

• Each value of T must be unique.

Otherwise this panics

pub fn load_store(store_root: &Path) -> Result<XvcStore<T>, Error>

Loads a store from the directory built from store_root and the type name.

pub fn save_store(store: &XvcStore<T>, store_root: &Path) -> Result<(), Error>

Records the given store to the directory built from store_root and type description of T.

pub fn save(&self, store_root: &Path) -> Result<(), Error>

Saves the current store using [save_store] to a directory built from store_root and type description of T.

Methods from Deref<Target = BTreeMap<XvcEntity, T>>

pub fn get<Q>(&self, key: &Q) -> Option<&V>

where K: Borrow<Q> + Ord, Q: Ord + ?Sized,

Returns a reference to the value corresponding to the key.

The key may be any borrowed form of the map’s key type, but the ordering on the borrowed form must match the ordering on the key type.

Examples

use std::collections::BTreeMap;

let mut map = BTreeMap::new();
map.insert(1, "a");
assert_eq!(map.get(&1), Some(&"a"));
assert_eq!(map.get(&2), None);

pub fn get_key_value<Q>(&self, k: &Q) -> Option<(&K, &V)>

where K: Borrow<Q> + Ord, Q: Ord + ?Sized,

Returns the key-value pair corresponding to the supplied key. This is potentially useful:

• for key types where non-identical keys can be considered equal;
• for getting the &K stored key value from a borrowed &Q lookup key; or
• for getting a reference to a key with the same lifetime as the collection.

The supplied key may be any borrowed form of the map’s key type, but the ordering on the borrowed form must match the ordering on the key type.

Examples

use std::cmp::Ordering;
use std::collections::BTreeMap;

#[derive(Clone, Copy, Debug)]
struct S {
    id: u32,
    name: &'static str, // ignored by equality and ordering operations
}

impl PartialEq for S {
    fn eq(&self, other: &S) -> bool {
        self.id == other.id
    }
}

impl Eq for S {}

impl PartialOrd for S {
    fn partial_cmp(&self, other: &S) -> Option<Ordering> {
        self.id.partial_cmp(&other.id)
    }
}

impl Ord for S {
    fn cmp(&self, other: &S) -> Ordering {
        self.id.cmp(&other.id)
    }
}

let j_a = S { id: 1, name: "Jessica" };
let j_b = S { id: 1, name: "Jess" };
let p = S { id: 2, name: "Paul" };
assert_eq!(j_a, j_b);

let mut map = BTreeMap::new();
map.insert(j_a, "Paris");
assert_eq!(map.get_key_value(&j_a), Some((&j_a, &"Paris")));
assert_eq!(map.get_key_value(&j_b), Some((&j_a, &"Paris"))); // the notable case
assert_eq!(map.get_key_value(&p), None);

pub fn first_key_value(&self) -> Option<(&K, &V)>

where K: Ord,

Returns the first key-value pair in the map. The key in this pair is the minimum key in the map.

Examples

use std::collections::BTreeMap;

let mut map = BTreeMap::new();
assert_eq!(map.first_key_value(), None);
map.insert(1, "b");
map.insert(2, "a");
assert_eq!(map.first_key_value(), Some((&1, &"b")));

pub fn last_key_value(&self) -> Option<(&K, &V)>

where K: Ord,

Returns the last key-value pair in the map. The key in this pair is the maximum key in the map.

Examples

use std::collections::BTreeMap;

let mut map = BTreeMap::new();
map.insert(1, "b");
map.insert(2, "a");
assert_eq!(map.last_key_value(), Some((&2, &"a")));

pub fn contains_key<Q>(&self, key: &Q) -> bool

where K: Borrow<Q> + Ord, Q: Ord + ?Sized,

Returns true if the map contains a value for the specified key.

The key may be any borrowed form of the map’s key type, but the ordering on the borrowed form must match the ordering on the key type.

Examples

use std::collections::BTreeMap;

let mut map = BTreeMap::new();
map.insert(1, "a");
assert_eq!(map.contains_key(&1), true);
assert_eq!(map.contains_key(&2), false);

pub fn range<T, R>(&self, range: R) -> Range<'_, K, V>

where T: Ord + ?Sized, K: Borrow<T> + Ord, R: RangeBounds<T>,

Constructs a double-ended iterator over a sub-range of elements in the map. The simplest way is to use the range syntax min..max, thus range(min..max) will yield elements from min (inclusive) to max (exclusive). The range may also be entered as (Bound<T>, Bound<T>), so for example range((Excluded(4), Included(10))) will yield a left-exclusive, right-inclusive range from 4 to 10.

Panics

Panics if range start > end. Panics if range start == end and both bounds are Excluded.

Examples

use std::collections::BTreeMap;
use std::ops::Bound::Included;

let mut map = BTreeMap::new();
map.insert(3, "a");
map.insert(5, "b");
map.insert(8, "c");
for (&key, &value) in map.range((Included(&4), Included(&8))) {
    println!("{key}: {value}");
}
assert_eq!(Some((&5, &"b")), map.range(4..).next());

pub fn iter(&self) -> Iter<'_, K, V>

Gets an iterator over the entries of the map, sorted by key.

Examples

use std::collections::BTreeMap;

let mut map = BTreeMap::new();
map.insert(3, "c");
map.insert(2, "b");
map.insert(1, "a");

for (key, value) in map.iter() {
    println!("{key}: {value}");
}

let (first_key, first_value) = map.iter().next().unwrap();
assert_eq!((*first_key, *first_value), (1, "a"));

pub fn keys(&self) -> Keys<'_, K, V>

Gets an iterator over the keys of the map, in sorted order.

Examples

use std::collections::BTreeMap;

let mut a = BTreeMap::new();
a.insert(2, "b");
a.insert(1, "a");

let keys: Vec<_> = a.keys().cloned().collect();
assert_eq!(keys, [1, 2]);

pub fn values(&self) -> Values<'_, K, V>

Gets an iterator over the values of the map, in order by key.

Examples

use std::collections::BTreeMap;

let mut a = BTreeMap::new();
a.insert(1, "hello");
a.insert(2, "goodbye");

let values: Vec<&str> = a.values().cloned().collect();
assert_eq!(values, ["hello", "goodbye"]);

pub fn len(&self) -> usize

Returns the number of elements in the map.

Examples

use std::collections::BTreeMap;

let mut a = BTreeMap::new();
assert_eq!(a.len(), 0);
a.insert(1, "a");
assert_eq!(a.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if the map contains no elements.

Examples

use std::collections::BTreeMap;

let mut a = BTreeMap::new();
assert!(a.is_empty());
a.insert(1, "a");
assert!(!a.is_empty());

pub fn lower_bound<Q>(&self, bound: Bound<&Q>) -> Cursor<'_, K, V>

where K: Borrow<Q> + Ord, Q: Ord + ?Sized,

🔬This is a nightly-only experimental API. (btree_cursors)

Returns a Cursor pointing at the gap before the smallest key greater than the given bound.

Passing Bound::Included(x) will return a cursor pointing to the gap before the smallest key greater than or equal to x.

Passing Bound::Excluded(x) will return a cursor pointing to the gap before the smallest key greater than x.

Passing Bound::Unbounded will return a cursor pointing to the gap before the smallest key in the map.

Examples

#![feature(btree_cursors)]

use std::collections::BTreeMap;
use std::ops::Bound;

let map = BTreeMap::from([
    (1, "a"),
    (2, "b"),
    (3, "c"),
    (4, "d"),
]);

let cursor = map.lower_bound(Bound::Included(&2));
assert_eq!(cursor.peek_prev(), Some((&1, &"a")));
assert_eq!(cursor.peek_next(), Some((&2, &"b")));

let cursor = map.lower_bound(Bound::Excluded(&2));
assert_eq!(cursor.peek_prev(), Some((&2, &"b")));
assert_eq!(cursor.peek_next(), Some((&3, &"c")));

let cursor = map.lower_bound(Bound::Unbounded);
assert_eq!(cursor.peek_prev(), None);
assert_eq!(cursor.peek_next(), Some((&1, &"a")));

pub fn upper_bound<Q>(&self, bound: Bound<&Q>) -> Cursor<'_, K, V>

where K: Borrow<Q> + Ord, Q: Ord + ?Sized,

🔬This is a nightly-only experimental API. (btree_cursors)

Returns a Cursor pointing at the gap after the greatest key smaller than the given bound.

Passing Bound::Included(x) will return a cursor pointing to the gap after the greatest key smaller than or equal to x.

Passing Bound::Excluded(x) will return a cursor pointing to the gap after the greatest key smaller than x.

Passing Bound::Unbounded will return a cursor pointing to the gap after the greatest key in the map.

Examples

#![feature(btree_cursors)]

use std::collections::BTreeMap;
use std::ops::Bound;

let map = BTreeMap::from([
    (1, "a"),
    (2, "b"),
    (3, "c"),
    (4, "d"),
]);

let cursor = map.upper_bound(Bound::Included(&3));
assert_eq!(cursor.peek_prev(), Some((&3, &"c")));
assert_eq!(cursor.peek_next(), Some((&4, &"d")));

let cursor = map.upper_bound(Bound::Excluded(&3));
assert_eq!(cursor.peek_prev(), Some((&2, &"b")));
assert_eq!(cursor.peek_next(), Some((&3, &"c")));

let cursor = map.upper_bound(Bound::Unbounded);
assert_eq!(cursor.peek_prev(), Some((&4, &"d")));
assert_eq!(cursor.peek_next(), None);

Trait Implementations

impl<T> Clone for XvcStore<T>

where T: Clone + Storable,

fn clone(&self) -> XvcStore<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for XvcStore<T>

where T: Debug + Storable,

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

Formats the value using the given formatter.

impl<T> Default for XvcStore<T>

where T: Storable,

fn default() -> XvcStore<T>

Returns the “default value” for a type.

impl<T> Deref for XvcStore<T>

where T: Storable,

type Target = BTreeMap<XvcEntity, T>

The resulting type after dereferencing.

fn deref(&self) -> &<XvcStore<T> as Deref>::Target

Dereferences the value.

impl<T> From<&XvcStore<T>> for HStore<T>

where T: Storable,

fn from(store: &XvcStore<T>) -> HStore<T>

Converts to this type from the input type.

impl<T> Hash for XvcStore<T>

where T: Hash + Storable,

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

where __H: Hasher,

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<T> Index<&XvcEntity> for XvcStore<T>

where T: Storable,

type Output = T

The returned type after indexing.

fn index( &self, entity: &XvcEntity, ) -> &<XvcStore<T> as Index<&XvcEntity>>::Output

Performs the indexing (container[index]) operation.