Struct sled::Tree

pub struct Tree { /* fields omitted */ }

A flash-sympathetic persistent lock-free B+ tree

Methods

impl Tree

pub fn start_default<P: AsRef<Path>>(path: P) -> Result<Tree, ()>

Load existing or create a new Tree with a default configuration.

pub fn start(config: Config) -> Result<Tree, ()>

Load existing or create a new Tree.

pub fn clear(&self) -> Result<(), ()>

Clears the Tree, removing all values.

Note that this is NOT atomic.

pub fn flush(&self) -> Result<(), ()>

Flushes any pending IO buffers to disk to ensure durability.

pub fn get<K: AsRef<[u8]>>(&self, key: K) -> Result<Option<PinnedValue>, ()>

Retrieve a value from the Tree if it exists.

pub fn get_lt<K: AsRef<[u8]>>(     &self,     key: K ) -> Result<Option<(Vec<u8>, PinnedValue)>, ()>

Retrieve a value from the Tree for the key before the given key, if one exists.

Examples

use sled::{ConfigBuilder, Error};
let config = ConfigBuilder::new().temporary(true).build();

let tree = sled::Tree::start(config).unwrap();

for i in 0..10 {
    tree.set(vec![i], vec![i]).expect("should write successfully");
}

assert!(tree.get_lt(vec![]).unwrap().is_none());
assert!(tree.get_lt(vec![0]).unwrap().is_none());
assert!(tree.get_lt(vec![1]).unwrap().unwrap().1 == vec![0]);
assert!(tree.get_lt(vec![9]).unwrap().unwrap().1 == vec![8]);
assert!(tree.get_lt(vec![10]).unwrap().unwrap().1 == vec![9]);
assert!(tree.get_lt(vec![255]).unwrap().unwrap().1 == vec![9]);

pub fn contains_key<K: AsRef<[u8]>>(&self, key: K) -> Result<bool, ()>

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

pub fn get_gt<K: AsRef<[u8]>>(     &self,     key: K ) -> Result<Option<(Vec<u8>, PinnedValue)>, ()>

Retrieve a value from the Tree for the key after the given key, if one exists.

Examples

use sled::{ConfigBuilder, Error};
let config = ConfigBuilder::new().temporary(true).build();

let tree = sled::Tree::start(config).unwrap();

for i in 0..10 {
    tree.set(vec![i], vec![i]).expect("should write successfully");
}

assert!(tree.get_gt(vec![]).unwrap().unwrap().1 == vec![0]);
assert!(tree.get_gt(vec![0]).unwrap().unwrap().1 == vec![1]);
assert!(tree.get_gt(vec![1]).unwrap().unwrap().1 == vec![2]);
assert!(tree.get_gt(vec![8]).unwrap().unwrap().1 == vec![9]);
assert!(tree.get_gt(vec![9]).unwrap().is_none());

pub fn cas<K: AsRef<[u8]>>(     &self,     key: K,     old: Option<&[u8]>,     new: Option<Vec<u8>> ) -> Result<(), Option<PinnedValue>>

Compare and swap. Capable of unique creation, conditional modification, or deletion. If old is None, this will only set the value if it doesn't exist yet. If new is None, will delete the value if old is correct. If both old and new are Some, will modify the value if old is correct. If Tree is read-only, will do nothing.

Examples

use sled::{ConfigBuilder, Error};
let config = ConfigBuilder::new().temporary(true).build();
let t = sled::Tree::start(config).unwrap();

// unique creation
assert_eq!(t.cas(&[1], None, Some(vec![1])), Ok(()));
// assert_eq!(t.cas(&[1], None, Some(vec![1])), Err(Error::CasFailed(Some(vec![1]))));

// conditional modification
assert_eq!(t.cas(&[1], Some(&*vec![1]), Some(vec![2])), Ok(()));
// assert_eq!(t.cas(&[1], Some(vec![1]), Some(vec![2])), Err(Error::CasFailed(Some(vec![2]))));

// conditional deletion
assert_eq!(t.cas(&[1], Some(&[2]), None), Ok(()));
assert_eq!(t.get(&[1]), Ok(None));

pub fn set<K: AsRef<[u8]>>(     &self,     key: K,     value: Vec<u8> ) -> Result<Option<PinnedValue>, ()>

Set a key to a new value, returning the old value if it was set.

pub fn merge<K: AsRef<[u8]>>(&self, key: K, value: Vec<u8>) -> Result<(), ()>

Merge a new value into the total state for a key.

Examples

fn concatenate_merge(
  _key: &[u8],               // the key being merged
  old_value: Option<&[u8]>,  // the previous value, if one existed
  merged_bytes: &[u8]        // the new bytes being merged in
) -> Option<Vec<u8>> {       // set the new value, return None to delete
  let mut ret = old_value
    .map(|ov| ov.to_vec())
    .unwrap_or_else(|| vec![]);

  ret.extend_from_slice(merged_bytes);

  Some(ret)
}

let config = sled::ConfigBuilder::new()
  .temporary(true)
  .merge_operator(concatenate_merge)
  .build();

let tree = sled::Tree::start(config).unwrap();

let k = b"k1";

tree.set(k, vec![0]);
tree.merge(k, vec![1]);
tree.merge(k, vec![2]);
// assert_eq!(tree.get(k).unwrap().unwrap(), vec![0, 1, 2]);

// sets replace previously merged data,
// bypassing the merge function.
tree.set(k, vec![3]);
// assert_eq!(tree.get(k), Ok(Some(vec![3])));

// merges on non-present values will add them
tree.del(k);
tree.merge(k, vec![4]);
// assert_eq!(tree.get(k).unwrap().unwrap(), vec![4]);

pub fn del<K: AsRef<[u8]>>(&self, key: K) -> Result<Option<PinnedValue>, ()>

Delete a value, returning the last result if it existed.

Examples

let config = sled::ConfigBuilder::new().temporary(true).build();
let t = sled::Tree::start(config).unwrap();
t.set(&[1], vec![1]);
assert_eq!(t.del(&*vec![1]).unwrap().unwrap(), vec![1]);
assert_eq!(t.del(&*vec![1]), Ok(None));

Important traits for Iter<'a>

impl<'a> Iterator for Iter<'a> type Item = Result<(Vec<u8>, PinnedValue), ()>;

pub fn iter(&self) -> Iter

Iterate over the tuples of keys and values in this tree.

Examples

let config = sled::ConfigBuilder::new().temporary(true).build();
let t = sled::Tree::start(config).unwrap();
t.set(&[1], vec![10]);
t.set(&[2], vec![20]);
t.set(&[3], vec![30]);
let mut iter = t.iter();
// assert_eq!(iter.next(), Some(Ok((vec![1], vec![10]))));
// assert_eq!(iter.next(), Some(Ok((vec![2], vec![20]))));
// assert_eq!(iter.next(), Some(Ok((vec![3], vec![30]))));
// assert_eq!(iter.next(), None);

Important traits for Iter<'a>

impl<'a> Iterator for Iter<'a> type Item = Result<(Vec<u8>, PinnedValue), ()>;

pub fn scan<K: AsRef<[u8]>>(&self, key: K) -> Iter

Iterate over tuples of keys and values, starting at the provided key.

Examples

let config = sled::ConfigBuilder::new().temporary(true).build();
let t = sled::Tree::start(config).unwrap();
t.set(&[1], vec![10]);
t.set(&[2], vec![20]);
t.set(&[3], vec![30]);
let mut iter = t.scan(&*vec![2]);
// assert_eq!(iter.next(), Some(Ok((vec![2], vec![20]))));
// assert_eq!(iter.next(), Some(Ok((vec![3], vec![30]))));
// assert_eq!(iter.next(), None);

Important traits for Keys<'a>

impl<'a> Iterator for Keys<'a> type Item = Result<Vec<u8>, ()>;

pub fn keys<K: AsRef<[u8]>>(&self, key: K) -> Keys

Iterate over keys, starting at the provided key.

Examples

let config = sled::ConfigBuilder::new().temporary(true).build();
let t = sled::Tree::start(config).unwrap();
t.set(&[1], vec![10]);
t.set(&[2], vec![20]);
t.set(&[3], vec![30]);
let mut iter = t.scan(&*vec![2]);
// assert_eq!(iter.next(), Some(Ok(vec![2])));
// assert_eq!(iter.next(), Some(Ok(vec![3])));
// assert_eq!(iter.next(), None);

Important traits for Values<'a>

impl<'a> Iterator for Values<'a> type Item = Result<PinnedValue, ()>;

pub fn values<K: AsRef<[u8]>>(&self, key: K) -> Values

Iterate over values, starting at the provided key.

Examples

let config = sled::ConfigBuilder::new().temporary(true).build();
let t = sled::Tree::start(config).unwrap();
t.set(&[1], vec![10]);
t.set(&[2], vec![20]);
t.set(&[3], vec![30]);
let mut iter = t.scan(&*vec![2]);
// assert_eq!(iter.next(), Some(Ok(vec![20])));
// assert_eq!(iter.next(), Some(Ok(vec![30])));
// assert_eq!(iter.next(), None);

pub fn len(&self) -> usize

Returns the number of elements in this tree.

Beware: performs a full O(n) scan under the hood.

pub fn is_empty(&self) -> bool

Returns true if the Tree contains no elements.

Trait Implementations

impl Clone for Tree

fn clone(&self) -> Tree

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Sync for Tree

impl<'a> IntoIterator for &'a Tree

type Item = Result<(Vec<u8>, PinnedValue), ()>

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

Important traits for Iter<'a>

impl<'a> Iterator for Iter<'a> type Item = Result<(Vec<u8>, PinnedValue), ()>;

fn into_iter(self) -> Iter<'a>

Creates an iterator from a value.

impl Send for Tree

impl Debug for Tree

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

Formats the value using the given formatter.