Struct exonum::storage::proof_map_index::ProofMapIndex

pub struct ProofMapIndex<T, K, V> { /* fields omitted */ }

A Merkelized version of a map that provides proofs of existence or non-existence for the map keys.

ProofMapIndex implements a Merkle Patricia tree, storing values as leaves. ProofMapIndex requires that keys implement the ProofMapKey trait and values implement the StorageValue trait.

The size of the proof map keys must be exactly 32 bytes and the keys must have a uniform distribution. Usually, Hash and PublicKey are used as types of proof map keys.

Methods

impl<T, K, V> ProofMapIndex<T, K, V> where
    T: AsRef<dyn Snapshot>,
    K: ProofMapKey,
    V: StorageValue, 

pub fn new<S: AsRef<str>>(index_name: S, view: T) -> Self

Creates a new index representation based on the name and storage view.

Storage view can be specified as &Snapshot or &mut Fork. In the first case, only immutable methods are available. In the second case, both immutable and mutable methods are available.

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let snapshot = db.snapshot();
let index: ProofMapIndex<_, Hash, u8> = ProofMapIndex::new(name, &snapshot);

let mut fork = db.fork();
let mut mut_index: ProofMapIndex<_, Hash, u8> = ProofMapIndex::new(name, &mut fork);

pub fn new_in_family<S, I>(family_name: S, index_id: &I, view: T) -> Self where
    I: StorageKey,
    I: ?Sized,
    S: AsRef<str>, 

Creates a new index representation based on the name, common prefix of its keys and storage view.

Storage view can be specified as &Snapshot or &mut Fork. In the first case, only immutable methods are available. In the second case, both immutable and mutable methods are available.

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let index_id = vec![01];

let snapshot = db.snapshot();
let index: ProofMapIndex<_, Hash, u8> = ProofMapIndex::new_in_family(
    name,
    &index_id,
    &snapshot,
 );

let mut fork = db.fork();
let mut mut_index: ProofMapIndex<_, Hash, u8> = ProofMapIndex::new_in_family(
    name,
    &index_id,
    &mut fork,
 );

pub fn merkle_root(&self) -> Hash

Returns the root hash of the proof map or default hash value if it is empty. The default hash consists solely of zeroes.

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let mut fork = db.fork();
let mut index = ProofMapIndex::new(name, &mut fork);

let default_hash = index.merkle_root();
assert_eq!(Hash::default(), default_hash);

index.put(&default_hash, 100);
let hash = index.merkle_root();
assert_ne!(hash, default_hash);

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

Returns a value corresponding to the key.

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let mut fork = db.fork();
let mut index = ProofMapIndex::new(name, &mut fork);

let hash = Hash::default();
assert_eq!(None, index.get(&hash));

index.put(&hash, 2);
assert_eq!(Some(2), index.get(&hash));

pub fn contains(&self, key: &K) -> bool

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

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let mut fork = db.fork();
let mut index = ProofMapIndex::new(name, &mut fork);

let hash = Hash::default();
assert!(!index.contains(&hash));

index.put(&hash, 2);
assert!(index.contains(&hash));

pub fn get_proof(&self, key: K) -> MapProof<K, V>

Returns the proof of existence or non-existence for the specified key.

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let snapshot = db.snapshot();
let index: ProofMapIndex<_, Hash, u8> = ProofMapIndex::new("index", &snapshot);

let proof = index.get_proof(Hash::default());

pub fn get_multiproof<KI>(&self, keys: KI) -> MapProof<K, V> where
    KI: IntoIterator<Item = K>, 

Returns the combined proof of existence or non-existence for the multiple specified keys.

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};

let db = MemoryDB::new();
let snapshot = db.snapshot();
let index: ProofMapIndex<_, [u8; 32], u8> = ProofMapIndex::new("index", &snapshot);

let proof = index.get_multiproof(vec![[0; 32], [1; 32]]);

Important traits for ProofMapIndexIter<'a, K, V>

impl<'a, K, V> Iterator for ProofMapIndexIter<'a, K, V> where
    K: ProofMapKey,
    V: StorageValue,  type Item = (K::Output, V);

pub fn iter(&self) -> ProofMapIndexIter<K, V>

Returns an iterator over the entries of the map in ascending order. The iterator element type is (K::Output, V).

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let snapshot = db.snapshot();
let index: ProofMapIndex<_, Hash, u8> = ProofMapIndex::new(name, &snapshot);

for val in index.iter() {
    println!("{:?}", val);
}

Important traits for ProofMapIndexKeys<'a, K>

impl<'a, K> Iterator for ProofMapIndexKeys<'a, K> where
    K: ProofMapKey,  type Item = K::Output;

pub fn keys(&self) -> ProofMapIndexKeys<K>

Returns an iterator over the keys of the map in ascending order. The iterator element type is K::Output.

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let snapshot = db.snapshot();
let index: ProofMapIndex<_, Hash, u8> = ProofMapIndex::new(name, &snapshot);

for key in index.keys() {
    println!("{:?}", key);
}

Important traits for ProofMapIndexValues<'a, V>

impl<'a, V> Iterator for ProofMapIndexValues<'a, V> where
    V: StorageValue,  type Item = V;

pub fn values(&self) -> ProofMapIndexValues<V>

Returns an iterator over the values of the map in ascending order of keys. The iterator element type is V.

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let snapshot = db.snapshot();
let index: ProofMapIndex<_, Hash, u8> = ProofMapIndex::new(name, &snapshot);

for val in index.values() {
    println!("{}", val);
}

Important traits for ProofMapIndexIter<'a, K, V>

impl<'a, K, V> Iterator for ProofMapIndexIter<'a, K, V> where
    K: ProofMapKey,
    V: StorageValue,  type Item = (K::Output, V);

pub fn iter_from(&self, from: &K) -> ProofMapIndexIter<K, V>

Returns an iterator over the entries of the map in ascending order starting from the specified key. The iterator element type is (K::Output, V).

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let snapshot = db.snapshot();
let index: ProofMapIndex<_, Hash, u8> = ProofMapIndex::new(name, &snapshot);

let hash = Hash::default();
for val in index.iter_from(&hash) {
    println!("{:?}", val);
}

Important traits for ProofMapIndexKeys<'a, K>

impl<'a, K> Iterator for ProofMapIndexKeys<'a, K> where
    K: ProofMapKey,  type Item = K::Output;

pub fn keys_from(&self, from: &K) -> ProofMapIndexKeys<K>

Returns an iterator over the keys of the map in ascending order starting from the specified key. The iterator element type is K::Output.

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let snapshot = db.snapshot();
let index: ProofMapIndex<_, Hash, u8> = ProofMapIndex::new(name, &snapshot);

let hash = Hash::default();
for key in index.keys_from(&hash) {
    println!("{:?}", key);
}

Important traits for ProofMapIndexValues<'a, V>

impl<'a, V> Iterator for ProofMapIndexValues<'a, V> where
    V: StorageValue,  type Item = V;

pub fn values_from(&self, from: &K) -> ProofMapIndexValues<V>

Returns an iterator over the values of the map in ascending order of keys starting from the specified key. The iterator element type is V.

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let snapshot = db.snapshot();
let index: ProofMapIndex<_, Hash, u8> = ProofMapIndex::new(name, &snapshot);

let hash = Hash::default();
for val in index.values_from(&hash) {
    println!("{}", val);
}

impl<'a, K, V> ProofMapIndex<&'a mut Fork, K, V> where
    K: ProofMapKey,
    V: StorageValue, 

pub fn put(&mut self, key: &K, value: V)

Inserts the key-value pair into the proof map.

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let mut fork = db.fork();
let mut index = ProofMapIndex::new(name, &mut fork);

let hash = Hash::default();
index.put(&hash, 2);
assert!(index.contains(&hash));

pub fn remove(&mut self, key: &K)

Removes a key from the proof map.

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let mut fork = db.fork();
let mut index = ProofMapIndex::new(name, &mut fork);

let hash = Hash::default();
index.put(&hash, 2);
assert!(index.contains(&hash));

index.remove(&hash);
assert!(!index.contains(&hash));

pub fn clear(&mut self)

Clears the proof map, removing all entries.

Notes

Currently, this method is not optimized to delete a large set of data. During the execution of this method, the amount of allocated memory is linearly dependent on the number of elements in the index.

Examples

use exonum::storage::{MemoryDB, Database, ProofMapIndex};
use exonum::crypto::Hash;

let db = MemoryDB::new();
let name = "name";
let mut fork = db.fork();
let mut index = ProofMapIndex::new(name, &mut fork);

let hash = Hash::default();
index.put(&hash, 2);
assert!(index.contains(&hash));

index.clear();
assert!(!index.contains(&hash));

Trait Implementations

impl<'a, T, K, V> IntoIterator for &'a ProofMapIndex<T, K, V> where
    T: AsRef<dyn Snapshot>,
    K: ProofMapKey,
    V: StorageValue, 

type Item = (K::Output, V)

The type of the elements being iterated over.

type IntoIter = ProofMapIndexIter<'a, K, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, K, V> Debug for ProofMapIndex<T, K, V> where
    T: AsRef<dyn Snapshot>,
    K: ProofMapKey,
    V: StorageValue + Debug, 

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.