Docs for raw iterator

master
Karl Hobley 8 years ago
parent 05c01f4e9e
commit 3bdc7e4bc4
  1. 160
      src/db.rs

@ -103,28 +103,38 @@ pub struct Snapshot<'a> {
/// An iterator over a database or column family, with specifiable /// An iterator over a database or column family, with specifiable
/// ranges and direction. /// ranges and direction.
/// ///
/// This iterator is different to the standard ``DBIterator`` as it aims Into
/// replicate the underlying iterator API within RocksDB itself. This should
/// give access to more performance and flexibility but departs from the
/// widely recognised Rust idioms.
///
/// ``` /// ```
/// use rocksdb::{DB, Direction, IteratorMode}; /// use rocksdb::DB;
/// ///
/// let mut db = DB::open_default("path/for/rocksdb/storage2").unwrap(); /// let mut db = DB::open_default("path/for/rocksdb/storage2").unwrap();
/// let mut iter = db.iterator(IteratorMode::Start); // Always iterates forward /// let mut iter = db.raw_iterator();
/// for (key, value) in iter { ///
/// println!("Saw {:?} {:?}", key, value); /// // Forwards iteration
/// iter.seek_to_first();
/// while iter.next() {
/// println!("Saw {:?} {:?}", iter.key(), iter.value());
/// } /// }
/// iter = db.iterator(IteratorMode::End); // Always iterates backward ///
/// for (key, value) in iter { /// // Reverse iteration
/// println!("Saw {:?} {:?}", key, value); /// iter.seek_to_last();
/// while iter.prev() {
/// println!("Saw {:?} {:?}", iter.key(), iter.value());
/// } /// }
/// iter = db.iterator(IteratorMode::From(b"my key", Direction::Forward)); // From a key in Direction::{forward,reverse} ///
/// for (key, value) in iter { /// // Seeking
/// println!("Saw {:?} {:?}", key, value); /// iter = iter.seek(b"my key");
/// while iter.next() {
/// println!("Saw {:?} {:?}", iter.key(), iter.value());
/// } /// }
/// ///
/// // You can seek with an existing Iterator instance, too /// iter = iter.seek_for_prev(b"my key");
/// iter = db.iterator(IteratorMode::Start); /// while iter.prev() {
/// iter.set_mode(IteratorMode::From(b"another key", Direction::Reverse)); /// println!("Saw {:?} {:?}", iter.key(), iter.value());
/// for (key, value) in iter {
/// println!("Saw {:?} {:?}", key, value);
/// } /// }
/// ``` /// ```
pub struct DBRawIterator { pub struct DBRawIterator {
@ -241,30 +251,131 @@ impl DBRawIterator {
} }
} }
/// Returns true if the iterator is valid.
pub fn valid(&self) -> bool { pub fn valid(&self) -> bool {
unsafe { ffi::rocksdb_iter_valid(self.inner) != 0 } unsafe { ffi::rocksdb_iter_valid(self.inner) != 0 }
} }
/// Seeks to the first key in the database.
///
/// You must call ``.next()`` before reading the key.
///
/// # Examples
///
/// ```rust,no_run
/// // Iterate all keys from the start in lexicographic order
///
/// iterator.seek_to_first();
///
/// while iterator.next() {
/// println!("{:?} {:?}", iterator.key(), iterator.value());
/// }
/// ```
///
/// ```rust,no_run
/// // Read just the first key
///
/// iterator.seek_to_first();
///
/// let is_valid = iterator.next();
/// if is_valid {
/// println!("{:?} {:?}", iterator.key(), iterator.value());
/// } else {
/// // There are no keys in the database
/// }
/// ```
pub fn seek_to_first(&mut self) { pub fn seek_to_first(&mut self) {
unsafe { ffi::rocksdb_iter_seek_to_first(self.inner); } unsafe { ffi::rocksdb_iter_seek_to_first(self.inner); }
self.just_seeked = true; self.just_seeked = true;
} }
/// Seeks to the last key in the database.
///
/// You must call ``.prev()`` before reading the key.
///
/// # Examples
///
/// ```rust,no_run
/// // Iterate all keys from the end in reverse lexicographic order
///
/// iterator.seek_to_last();
///
/// while iterator.prev() {
/// println!("{:?} {:?}", iterator.key(), iterator.value());;
/// }
/// ```
///
/// ```rust,no_run
/// // Read just the last key
///
/// iterator.seek_to_last();
///
/// let is_valid = iterator.prev();
/// if is_valid {
/// println!("{:?} {:?}", iterator.key(), iterator.value());
/// } else {
/// // There are no keys in the database
/// }
/// ```
pub fn seek_to_last(&mut self) { pub fn seek_to_last(&mut self) {
unsafe { ffi::rocksdb_iter_seek_to_last(self.inner); } unsafe { ffi::rocksdb_iter_seek_to_last(self.inner); }
self.just_seeked = true; self.just_seeked = true;
} }
/// Seeks to the specified key or the first key that lexicographically follows it.
///
/// This method will attempt to seek to the specified key. If that key does not exist, it will
/// find and seek to the key that lexicographically follows it instead.
///
/// Like the other seek methods, you must call ``.next()`` or ``.prev()`` before reading a key.
///
/// # Examples
///
/// ```rust,no_run
/// // Read the first key that starts with 'a'
///
/// iterator.seek(b"a");
///
/// let is_valid = iterator.next();
/// if is_valid {
/// println!("{:?} {:?}", iterator.key(), iterator.value());
/// } else {
/// // There are no keys in the database
/// }
/// ```
pub fn seek(&mut self, key: &[u8]) { pub fn seek(&mut self, key: &[u8]) {
unsafe { ffi::rocksdb_iter_seek(self.inner, key.as_ptr() as *const c_char, key.len() as size_t); } unsafe { ffi::rocksdb_iter_seek(self.inner, key.as_ptr() as *const c_char, key.len() as size_t); }
self.just_seeked = true; self.just_seeked = true;
} }
/// Seeks to the specified key, or the first key that lexicographically precedes it.
///
/// Like ``.seek()`` this method will attempt to seek to the specified key.
/// The difference with ``.seek()`` is that if the specified key do not exist, this method will
/// seek to key that lexicographically precedes it instead.
///
/// Like the other seek methods, you must call ``.next()`` or ``.prev()`` before reading a key.
/// # Examples
///
/// ```rust,no_run
/// // Read the last key that starts with 'a'
///
/// iterator.seek_for_prev(b"b");
///
/// let is_valid = iterator.prev();
/// if is_valid {
/// println!("{:?} {:?}", iterator.key(), iterator.value());
/// } else {
/// // There are no keys in the database
/// }
pub fn seek_for_prev(&mut self, key: &[u8]) { pub fn seek_for_prev(&mut self, key: &[u8]) {
unsafe { ffi::rocksdb_iter_seek_for_prev(self.inner, key.as_ptr() as *const c_char, key.len() as size_t); } unsafe { ffi::rocksdb_iter_seek_for_prev(self.inner, key.as_ptr() as *const c_char, key.len() as size_t); }
self.just_seeked = true; self.just_seeked = true;
} }
/// Seeks to the next key.
///
/// Returns true if the iterator is valid after this operation.
pub fn next(&mut self) -> bool { pub fn next(&mut self) -> bool {
// Initial call to next() after seeking should not move the iterator // Initial call to next() after seeking should not move the iterator
// as the iterator would be positioned on the first element // as the iterator would be positioned on the first element
@ -279,6 +390,9 @@ impl DBRawIterator {
self.valid() self.valid()
} }
/// Seeks to the previous key.
///
/// Returns true if the iterator is valid after this operation.
pub fn prev(&mut self) -> bool { pub fn prev(&mut self) -> bool {
// Initial call to prev() after seeking should not move the iterator // Initial call to prev() after seeking should not move the iterator
// as the iterator would be positioned on the first element // as the iterator would be positioned on the first element
@ -292,6 +406,13 @@ impl DBRawIterator {
self.valid() self.valid()
} }
/// Returns a slice to the internal buffer storing the current key.
///
/// This may be slightly more performant to use than the standard ``.key()`` method
/// as it does not copy the key. However, you must be careful to not use the buffer
/// if the iterator's seek position is ever moved by any of the seek commands or the
/// ``.next()`` and ``.previous()`` methods as the underlying buffer may be reused
/// for something else or freed entirely.
pub unsafe fn key_inner<'a>(&'a self) -> Option<&'a [u8]> { pub unsafe fn key_inner<'a>(&'a self) -> Option<&'a [u8]> {
if self.valid() { if self.valid() {
let mut key_len: size_t = 0; let mut key_len: size_t = 0;
@ -304,12 +425,20 @@ impl DBRawIterator {
} }
} }
/// Returns a copy of the current key.
pub fn key(&self) -> Option<Vec<u8>> { pub fn key(&self) -> Option<Vec<u8>> {
unsafe { unsafe {
self.key_inner().map(|key| key.to_vec()) self.key_inner().map(|key| key.to_vec())
} }
} }
/// Returns a slice to the internal buffer storing the current value.
///
/// This may be slightly more performant to use than the standard ``.value()`` method
/// as it does not copy the value. However, you must be careful to not use the buffer
/// if the iterator's seek position is ever moved by any of the seek commands or the
/// ``.next()`` and ``.previous()`` methods as the underlying buffer may be reused
/// for something else or freed entirely.
pub unsafe fn value_inner<'a>(&'a self) -> Option<&'a [u8]> { pub unsafe fn value_inner<'a>(&'a self) -> Option<&'a [u8]> {
if self.valid() { if self.valid() {
let mut val_len: size_t = 0; let mut val_len: size_t = 0;
@ -322,6 +451,7 @@ impl DBRawIterator {
} }
} }
/// Returns a copy of the current value.
pub fn value(&self) -> Option<Vec<u8>> { pub fn value(&self) -> Option<Vec<u8>> {
unsafe { unsafe {
self.value_inner().map(|value| value.to_vec()) self.value_inner().map(|value| value.to_vec())

Loading…
Cancel
Save