Struct ChainMap

pub struct ChainMap<K, V>
where
    K: Eq + Hash + Clone,
    V: Clone,
{ /* private fields */ }

A structure for managing a tree of HashMaps

General layout inspired by A Persistent Singly-Linked Stack, adapted and extended with Mutexes and HashMaps

Implementations

impl<K, V> ChainMap<K, V>

where K: Eq + Hash + Clone, V: Clone,

pub fn new() -> Self

Create a new empty root

pub fn new_with(h: HashMap<K, V>) -> Self

Create a new root and initialize with given map

pub fn insert(&mut self, key: K, val: V)

Create a new binding in the toplevel

Panics

Panics if toplevel map is locked

pub fn lock(&mut self)

Protect map against modifications

Does not extend to maps below, all keys whose value must not change should be re-inserted in the toplevel.

pub fn unlock(&mut self)

Release write protection

pub fn locked(self) -> Self

pub fn unlocked(self) -> Self

pub fn is_unlocked(&self) -> bool

pub fn is_locked(&self) -> bool

pub fn readonly(self) -> Self

Resulting layer cannot modify any value lower in the map

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

Retrieve value associated with the first appearance of key in the chain

pub fn local_get(&self, key: &K) -> Option<V>

Check associated value only in topmost maps: stops at the first non-fallthrough level

pub fn update(&mut self, key: &K, newval: V)

Replace old value with new

Panics

• if key does not already exist
• if first layer with key is locked
• if key is only found after a write-protected layer

pub fn update_or(&mut self, key: &K, newval: V)

Replace old value with new, create binding in topmost map if key does not exist or if first layer with key is locked or if key is only accessible after a write-protected layer.

pub fn extend(&self) -> Self

pub fn extend_with(&self, h: HashMap<K, V>) -> Self

Create a new scope, initialized with or without bindings.

The new scope can get and update values from the parent scope, but inserts are only visible to the new scope and its children.

Examples

let mut root = ChainMap::new_with(map![0 => 'a', 1 => 'b']);
let mut layer = root.extend_with(map![2 => 'c']);
root.insert(3, 'd');
root.update(&0, 'e');
layer.update(&1, 'f');
layer.update(&2, 'g');

┌────────┐   ┌────────┐
│  root  └───┘ layer  │
│          ⇇          │
│ 0 -> e ┌───┐ 2 -> g │
│ 1 -> f │   └────────┘
│ 3 -> d │
└────────┘

check_that!(root[0] is 'e');
check_that!(layer[0] is 'e');

check_that!(root[1] is 'f');
check_that!(layer[1] is 'f');

check_that!(root[2] is None);
check_that!(layer[2] is 'g');

check_that!(root[3] is 'd');
check_that!(layer[3] is 'd');

check_that!(local_get? root has 0,1,3 and not 2);
check_that!(local_get? layer has 2 and not 0,1,3);

pub fn fork(&mut self) -> Self

pub fn fork_with(&mut self, h: HashMap<K, V>) -> Self

fork and fork_with are the same as extend and extend_with, but later bindings made to self are not visible to the other branches.

Updates, however, are visible.

Examples

let mut root = ChainMap::new_with(map![0 => 'a']);
let layer = root.fork_with(map![1 => 'b']);
root.insert(2, 'c');
root.update(&0, 'd');

┌─────────┐   ┌─────────┐
│ ex-root └───┘ layer   │
│           ⇇           │
│ 0 -> d  ┌───┐ 1 -> b  │
└──┐   ┌──┘   └─────────┘
   │ ⇈ │ <- fallthrough
┌──┘   └──┐
│  root   │
│         │
│ 2 -> c  │
└─────────┘

check_that!(root[0] is 'd');
check_that!(layer[0] is 'd');

check_that!(root[1] is None);
check_that!(layer[1] is 'b');

check_that!(root[2] is 'c');
check_that!(layer[2] is None);

check_that!(local_get? root has 0,2 and not 1);
check_that!(local_get? layer has 1 and not 0,2);

pub fn collect(&self) -> HashMap<K, V>

Gather all keys in a single HashMap.

Only keys accessible through a direct path are considered: if we let map = chain.collect() then for all k valid keys, map.get(&k) == chain.get(&k).

Trait Implementations

impl<K, V> Clone for ChainMap<K, V>

where K: Clone + Hash + Eq, V: Clone,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.