Struct provenance::ProvenanceMap

pub struct ProvenanceMap<Value> { /* fields omitted */ }

A provenance map is a map-like data structure that know which keys belong to which map.

Keys are generated upon inserting an element into the map.

use provenance::ProvenanceMap;
let mut map = ProvenanceMap::<i32>::new().unwrap();
let key = map.insert(5);

This is achieved by "tagging" keys with the generic type parameter of the map. So a map of type ProvenanceMap<i32> will create keys of type Key<i32>. The key does not actually contain a value of their generic type parameter. It is only used to track what map the key came from, i.e. it's provenance.

use provenance::ProvenanceMap;
let mut map_1 = ProvenanceMap::<i32>::new().unwrap();
let key = map_1.insert(5);
let map_2 = ProvenanceMap::<bool>::new().unwrap();

// Using a key from another map is a type error.
map_2.get(key);

However, if it were possible to create multiple maps with the same type, e.g. ProvenanceMap<String> the type of the key wouldn't be enough to track what map a key came from. Therefore, it is only possible to create a single map per concrete type given for the Value type parameter.

use provenance::ProvenanceMap;

// Creating a map once is OK
let mut map = ProvenanceMap::<String>::new();
assert!(map.is_some());

// Creating another map with the same signature is not OK
let mut map = ProvenanceMap::<String>::new();
assert!(map.is_none());

Implementations

impl<Value: 'static> ProvenanceMap<Value>

pub fn new() -> Option<ProvenanceMap<Value>>

Create a new map if one with the given signature have not already been created. If one has, None is returned.

use provenance::ProvenanceMap;

// Creating a map once is OK
let map = ProvenanceMap::<String>::new();
assert!(map.is_some());

// Creating another map with the same signature is not OK
let map = ProvenanceMap::<String>::new();
assert!(map.is_none());

pub fn insert(&mut self, value: Value) -> Key<Value>

Insert a value into the map. A key is generated for the value and returned. This key can be used to access the value later.

use provenance::ProvenanceMap;
let mut map = ProvenanceMap::<i32>::new().unwrap();

let key = map.insert(5);
assert_eq!(&5, map.get(key));

Multiple equivalent values may be inserted into the map. Each will get a unique key.

use provenance::ProvenanceMap;
let mut map = ProvenanceMap::<i32>::new().unwrap();

let key1 = map.insert(5);
let key2 = map.insert(5);
assert_ne!(key1, key2);

pub fn get(&self, key: Key<Value>) -> &Value

Use a key to retrieve an immutable reference to a stored value.

use provenance::ProvenanceMap;
let mut map = ProvenanceMap::<i32>::new().unwrap();

let key = map.insert(15);
assert_eq!(&15, map.get(key));

pub fn get_mut(&mut self, key: Key<Value>) -> &mut Value

Use a key to retrieve an mutable reference to a stored value.

use provenance::ProvenanceMap;
let mut map = ProvenanceMap::<i32>::new().unwrap();

let key = map.insert(15);
assert_eq!(&mut 15, map.get_mut(key));

pub fn keys(&self) -> impl Iterator<Item = Key<Value>>

Get an iterator over all keys in the map.

use provenance::ProvenanceMap;
let mut map = ProvenanceMap::<i32>::new().unwrap();

map.insert(1);
map.insert(2);
map.insert(3);

assert_eq!(3, map.keys().count());

pub fn iter(&self) -> impl Iterator<Item = &Value>

Get an iterator over immutable references to each value in the map.

use provenance::ProvenanceMap;
let mut map = ProvenanceMap::<i32>::new().unwrap();

map.insert(1);
map.insert(2);
map.insert(3);

assert_eq!(6, map.iter().sum());

pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut Value>

Get an iterator over mutable references to each value in the map.

use provenance::ProvenanceMap;
let mut map = ProvenanceMap::<i32>::new().unwrap();

map.insert(1);
map.insert(2);
map.insert(3);

// Add one to every value
map.iter_mut().for_each(|val| *val += 1);

assert_eq!(9, map.iter().sum());

pub fn find<P: Fn(&Value) -> bool>(&self, predicate: P) -> Option<&Value>

Search the map in insertion order for the first value that satisfy the given predicate. If such value is found, an immutable reference to it is returned,

use provenance::ProvenanceMap;
let mut map = ProvenanceMap::<i32>::new().unwrap();

map.insert(1);
map.insert(2);
map.insert(3);

assert_eq!(Some(&2), map.find(|&val| val == 2));

otherwise None is returned.

use provenance::ProvenanceMap;
let mut map = ProvenanceMap::<i32>::new().unwrap();

map.insert(1);
map.insert(2);
map.insert(3);

assert_eq!(None, map.find(|&val| val == 53));

pub fn find_mut<P: Fn(&Value) -> bool>(
    &mut self,
    predicate: P
) -> Option<&mut Value>

Search the map in insertion order for the first value that satisfy the given predicate. If such value is found, a mutable reference to it is returned,

use provenance::ProvenanceMap;
let mut map = ProvenanceMap::<i32>::new().unwrap();

map.insert(1);
map.insert(2);
map.insert(3);

assert_eq!(Some(&mut 2), map.find_mut(|&val| val == 2));

otherwise None is returned.

use provenance::ProvenanceMap;
let mut map = ProvenanceMap::<i32>::new().unwrap();

map.insert(1);
map.insert(2);
map.insert(3);

assert_eq!(None, map.find_mut(|&val| val == 53));