Struct ChainMap

Source

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

Expand description

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§

Source §

impl<K, V> ChainMap<K, V>
where K: Eq + Hash + Clone, V: Clone,

Source

pub fn new() -> Self

Create a new empty root

Source

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

Create a new root and initialize with given map

Source

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

Create a new binding in the toplevel

§Panics

Panics if toplevel map is locked

Source

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.

Source

pub fn unlock(&mut self)

Release write protection

Source

pub fn readonly(self) -> Self

Resulting layer cannot modify any value lower in the map

Source

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

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

Source

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

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

Source

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

Source

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.

Source

pub fn extend(&self) -> Self

Source

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);

Source

pub fn fork(&mut self) -> Self

Source

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);

Source

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).