Merge pull request #857 from rphmeier/hashdb_deprecated_docs

Update deprecated HashDB methods in docs.
This commit is contained in:
Gav Wood 2016-03-31 16:10:02 +02:00
commit d681b96a7b
3 changed files with 78 additions and 78 deletions

View File

@ -26,7 +26,7 @@ pub trait HashDB : AsHashDB {
/// Deprecated. use `get`.
fn lookup(&self, key: &H256) -> Option<&[u8]>; // TODO: rename to get.
/// Look up a given hash into the bytes that hash to it, returning None if the
/// Look up a given hash into the bytes that hash to it, returning None if the
/// hash is not known.
///
/// # Examples
@ -38,7 +38,7 @@ pub trait HashDB : AsHashDB {
/// let mut m = MemoryDB::new();
/// let hello_bytes = "Hello world!".as_bytes();
/// let hash = m.insert(hello_bytes);
/// assert_eq!(m.lookup(&hash).unwrap(), hello_bytes);
/// assert_eq!(m.get(&hash).unwrap(), hello_bytes);
/// }
/// ```
fn get(&self, key: &H256) -> Option<&[u8]> { self.lookup(key) }
@ -56,11 +56,11 @@ pub trait HashDB : AsHashDB {
/// fn main() {
/// let mut m = MemoryDB::new();
/// let hello_bytes = "Hello world!".as_bytes();
/// assert!(!m.exists(&hello_bytes.sha3()));
/// assert!(!m.contains(&hello_bytes.sha3()));
/// let key = m.insert(hello_bytes);
/// assert!(m.exists(&key));
/// m.kill(&key);
/// assert!(!m.exists(&key));
/// assert!(m.contains(&key));
/// m.remove(&key);
/// assert!(!m.contains(&key));
/// }
/// ```
fn contains(&self, key: &H256) -> bool { self.exists(key) }
@ -78,7 +78,7 @@ pub trait HashDB : AsHashDB {
/// fn main() {
/// let mut m = MemoryDB::new();
/// let key = m.insert("Hello world!".as_bytes());
/// assert!(m.exists(&key));
/// assert!(m.contains(&key));
/// }
/// ```
fn insert(&mut self, value: &[u8]) -> H256;
@ -101,12 +101,12 @@ pub trait HashDB : AsHashDB {
/// let mut m = MemoryDB::new();
/// let d = "Hello world!".as_bytes();
/// let key = &d.sha3();
/// m.kill(key); // OK - we now owe an insertion.
/// assert!(!m.exists(key));
/// m.remove(key); // OK - we now owe an insertion.
/// assert!(!m.contains(key));
/// m.insert(d); // OK - now it's "empty" again.
/// assert!(!m.exists(key));
/// assert!(!m.contains(key));
/// m.insert(d); // OK - now we've
/// assert_eq!(m.lookup(key).unwrap(), d);
/// assert_eq!(m.get(key).unwrap(), d);
/// }
/// ```
fn remove(&mut self, key: &H256) { self.kill(key) }

View File

@ -30,8 +30,8 @@ use std::default::Default;
/// Reference-counted memory-based HashDB implementation.
///
/// Use `new()` to create a new database. Insert items with `insert()`, remove items
/// with `kill()`, check for existance with `exists()` and lookup a hash to derive
/// the data with `lookup()`. Clear with `clear()` and purge the portions of the data
/// with `remove()`, check for existence with `containce()` and lookup a hash to derive
/// the data with `get()`. Clear with `clear()` and purge the portions of the data
/// that have no references with `purge()`.
///
/// # Example
@ -44,30 +44,30 @@ use std::default::Default;
/// let d = "Hello world!".as_bytes();
///
/// let k = m.insert(d);
/// assert!(m.exists(&k));
/// assert_eq!(m.lookup(&k).unwrap(), d);
/// assert!(m.contains(&k));
/// assert_eq!(m.get(&k).unwrap(), d);
///
/// m.insert(d);
/// assert!(m.exists(&k));
/// assert!(m.contains(&k));
///
/// m.kill(&k);
/// assert!(m.exists(&k));
/// m.remove(&k);
/// assert!(m.contains(&k));
///
/// m.kill(&k);
/// assert!(!m.exists(&k));
/// m.remove(&k);
/// assert!(!m.contains(&k));
///
/// m.kill(&k);
/// assert!(!m.exists(&k));
/// m.remove(&k);
/// assert!(!m.contains(&k));
///
/// m.insert(d);
/// assert!(!m.exists(&k));
/// assert!(!m.contains(&k));
/// m.insert(d);
/// assert!(m.exists(&k));
/// assert_eq!(m.lookup(&k).unwrap(), d);
/// assert!(m.contains(&k));
/// assert_eq!(m.get(&k).unwrap(), d);
///
/// m.kill(&k);
/// assert!(!m.exists(&k));
/// m.remove(&k);
/// assert!(!m.contains(&k));
/// }
/// ```
#[derive(PartialEq)]
@ -102,9 +102,9 @@ impl MemoryDB {
/// let mut m = MemoryDB::new();
/// let hello_bytes = "Hello world!".as_bytes();
/// let hash = m.insert(hello_bytes);
/// assert!(m.exists(&hash));
/// assert!(m.contains(&hash));
/// m.clear();
/// assert!(!m.exists(&hash));
/// assert!(!m.contains(&hash));
/// }
/// ```
pub fn clear(&mut self) {
@ -240,7 +240,7 @@ fn memorydb_denote() {
let mut m = MemoryDB::new();
let hello_bytes = b"Hello world!";
let hash = m.insert(hello_bytes);
assert_eq!(m.lookup(&hash).unwrap(), b"Hello world!");
assert_eq!(m.get(&hash).unwrap(), b"Hello world!");
for _ in 0..1000 {
let r = H256::random();
@ -250,5 +250,5 @@ fn memorydb_denote() {
assert_eq!(*rc, 0);
}
assert_eq!(m.lookup(&hash).unwrap(), b"Hello world!");
assert_eq!(m.get(&hash).unwrap(), b"Hello world!");
}

View File

@ -34,7 +34,7 @@ use kvdb::{Database, DBTransaction};
/// such operations may be flushed to the disk-backed DB with `commit()` or discarded with
/// `revert()`.
///
/// `lookup()` and `contains()` maintain normal behaviour - all `insert()` and `remove()`
/// `lookup()` and `contains()` maintain normal behaviour - all `insert()` and `remove()`
/// queries have an immediate effect in terms of these functions.
#[derive(Clone)]
pub struct OverlayDB {
@ -91,7 +91,7 @@ impl OverlayDB {
/// Commit all memory operations to the backing database.
///
/// Returns either an error or the number of items changed in the backing database.
///
///
/// Will return an error if the number of `kill()`s ever exceeds the number of
/// `insert()`s for any key. This will leave the database in an undeterminate
/// state. Don't ever let it happen.
@ -144,7 +144,7 @@ impl OverlayDB {
Ok(ret)
}
/// Revert all operations on this object (i.e. `insert()`s and `kill()`s) since the
/// Revert all operations on this object (i.e. `insert()`s and `remove()`s) since the
/// last `commit()`.
///
/// # Example
@ -157,12 +157,12 @@ impl OverlayDB {
/// let foo = m.insert(b"foo"); // insert foo.
/// m.commit().unwrap(); // commit - new operations begin here...
/// let bar = m.insert(b"bar"); // insert bar.
/// m.kill(&foo); // kill foo.
/// assert!(!m.exists(&foo)); // foo is gone.
/// assert!(m.exists(&bar)); // bar is here.
/// m.remove(&foo); // remove foo.
/// assert!(!m.contains(&foo)); // foo is gone.
/// assert!(m.contains(&bar)); // bar is here.
/// m.revert(); // revert the last two operations.
/// assert!(m.exists(&foo)); // foo is here.
/// assert!(!m.exists(&bar)); // bar is gone.
/// assert!(m.contains(&foo)); // foo is here.
/// assert!(!m.contains(&bar)); // bar is gone.
/// }
/// ```
pub fn revert(&mut self) { self.overlay.clear(); }
@ -275,47 +275,47 @@ impl HashDB for OverlayDB {
}
#[test]
fn overlaydb_overlay_insert_and_kill() {
fn overlaydb_overlay_insert_and_remove() {
let mut trie = OverlayDB::new_temp();
let h = trie.insert(b"hello world");
assert_eq!(trie.lookup(&h).unwrap(), b"hello world");
trie.kill(&h);
assert_eq!(trie.lookup(&h), None);
assert_eq!(trie.get(&h).unwrap(), b"hello world");
trie.remove(&h);
assert_eq!(trie.get(&h), None);
}
#[test]
fn overlaydb_backing_insert_revert() {
let mut trie = OverlayDB::new_temp();
let h = trie.insert(b"hello world");
assert_eq!(trie.lookup(&h).unwrap(), b"hello world");
assert_eq!(trie.get(&h).unwrap(), b"hello world");
trie.commit().unwrap();
assert_eq!(trie.lookup(&h).unwrap(), b"hello world");
assert_eq!(trie.get(&h).unwrap(), b"hello world");
trie.revert();
assert_eq!(trie.lookup(&h).unwrap(), b"hello world");
assert_eq!(trie.get(&h).unwrap(), b"hello world");
}
#[test]
fn overlaydb_backing_kill() {
fn overlaydb_backing_remove() {
let mut trie = OverlayDB::new_temp();
let h = trie.insert(b"hello world");
trie.commit().unwrap();
trie.kill(&h);
assert_eq!(trie.lookup(&h), None);
trie.remove(&h);
assert_eq!(trie.get(&h), None);
trie.commit().unwrap();
assert_eq!(trie.lookup(&h), None);
assert_eq!(trie.get(&h), None);
trie.revert();
assert_eq!(trie.lookup(&h), None);
assert_eq!(trie.get(&h), None);
}
#[test]
fn overlaydb_backing_kill_revert() {
fn overlaydb_backing_remove_revert() {
let mut trie = OverlayDB::new_temp();
let h = trie.insert(b"hello world");
trie.commit().unwrap();
trie.kill(&h);
assert_eq!(trie.lookup(&h), None);
trie.remove(&h);
assert_eq!(trie.get(&h), None);
trie.revert();
assert_eq!(trie.lookup(&h).unwrap(), b"hello world");
assert_eq!(trie.get(&h).unwrap(), b"hello world");
}
#[test]
@ -323,9 +323,9 @@ fn overlaydb_negative() {
let mut trie = OverlayDB::new_temp();
let h = trie.insert(b"hello world");
trie.commit().unwrap();
trie.kill(&h);
trie.kill(&h); //bad - sends us into negative refs.
assert_eq!(trie.lookup(&h), None);
trie.remove(&h);
trie.remove(&h); //bad - sends us into negative refs.
assert_eq!(trie.get(&h), None);
assert!(trie.commit().is_err());
}
@ -333,33 +333,33 @@ fn overlaydb_negative() {
fn overlaydb_complex() {
let mut trie = OverlayDB::new_temp();
let hfoo = trie.insert(b"foo");
assert_eq!(trie.lookup(&hfoo).unwrap(), b"foo");
assert_eq!(trie.get(&hfoo).unwrap(), b"foo");
let hbar = trie.insert(b"bar");
assert_eq!(trie.lookup(&hbar).unwrap(), b"bar");
assert_eq!(trie.get(&hbar).unwrap(), b"bar");
trie.commit().unwrap();
assert_eq!(trie.lookup(&hfoo).unwrap(), b"foo");
assert_eq!(trie.lookup(&hbar).unwrap(), b"bar");
assert_eq!(trie.get(&hfoo).unwrap(), b"foo");
assert_eq!(trie.get(&hbar).unwrap(), b"bar");
trie.insert(b"foo"); // two refs
assert_eq!(trie.lookup(&hfoo).unwrap(), b"foo");
assert_eq!(trie.get(&hfoo).unwrap(), b"foo");
trie.commit().unwrap();
assert_eq!(trie.lookup(&hfoo).unwrap(), b"foo");
assert_eq!(trie.lookup(&hbar).unwrap(), b"bar");
trie.kill(&hbar); // zero refs - delete
assert_eq!(trie.lookup(&hbar), None);
trie.kill(&hfoo); // one ref - keep
assert_eq!(trie.lookup(&hfoo).unwrap(), b"foo");
assert_eq!(trie.get(&hfoo).unwrap(), b"foo");
assert_eq!(trie.get(&hbar).unwrap(), b"bar");
trie.remove(&hbar); // zero refs - delete
assert_eq!(trie.get(&hbar), None);
trie.remove(&hfoo); // one ref - keep
assert_eq!(trie.get(&hfoo).unwrap(), b"foo");
trie.commit().unwrap();
assert_eq!(trie.lookup(&hfoo).unwrap(), b"foo");
trie.kill(&hfoo); // zero ref - would delete, but...
assert_eq!(trie.lookup(&hfoo), None);
assert_eq!(trie.get(&hfoo).unwrap(), b"foo");
trie.remove(&hfoo); // zero ref - would delete, but...
assert_eq!(trie.get(&hfoo), None);
trie.insert(b"foo"); // one ref - keep after all.
assert_eq!(trie.lookup(&hfoo).unwrap(), b"foo");
assert_eq!(trie.get(&hfoo).unwrap(), b"foo");
trie.commit().unwrap();
assert_eq!(trie.lookup(&hfoo).unwrap(), b"foo");
trie.kill(&hfoo); // zero ref - delete
assert_eq!(trie.lookup(&hfoo), None);
trie.commit().unwrap(); //
assert_eq!(trie.lookup(&hfoo), None);
assert_eq!(trie.get(&hfoo).unwrap(), b"foo");
trie.remove(&hfoo); // zero ref - delete
assert_eq!(trie.get(&hfoo), None);
trie.commit().unwrap(); //
assert_eq!(trie.get(&hfoo), None);
}
#[test]