Struct chainmap::ChainMap

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

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

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

Panics if key does not already exist

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

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