Struct DBRawIteratorWithThreadMode

Source

pub struct DBRawIteratorWithThreadMode<'a, D: DBAccess> { /* private fields */ }

Expand description

A low-level iterator over a database or column family, created by DB::raw_iterator and other raw_iterator_* methods.

This iterator replicates RocksDB’s API. It should provide better performance and more features than DBIteratorWithThreadMode, which is a standard Rust std::iter::Iterator.

use rust_rocksdb::{DB, Options};

let tempdir = tempfile::Builder::new()
    .prefix("_path_for_rocksdb_storage4")
    .tempdir()
    .expect("Failed to create temporary path for the _path_for_rocksdb_storage4.");
let path = tempdir.path();
{
    let db = DB::open_default(path).unwrap();
    let mut iter = db.raw_iterator();

    // Forwards iteration
    iter.seek_to_first();
    while iter.valid() {
        println!("Saw {:?} {:?}", iter.key(), iter.value());
        iter.next();
    }

    // Reverse iteration
    iter.seek_to_last();
    while iter.valid() {
        println!("Saw {:?} {:?}", iter.key(), iter.value());
        iter.prev();
    }

    // Seeking
    iter.seek(b"my key");
    while iter.valid() {
        println!("Saw {:?} {:?}", iter.key(), iter.value());
        iter.next();
    }

    // Reverse iteration from key
    // Note, use seek_for_prev when reversing because if this key doesn't exist,
    // this will make the iterator start from the previous key rather than the next.
    iter.seek_for_prev(b"my key");
    while iter.valid() {
        println!("Saw {:?} {:?}", iter.key(), iter.value());
        iter.prev();
    }
}
let _ = DB::destroy(&Options::default(), path);

Implementations§

Source §

impl<'a, D: DBAccess> DBRawIteratorWithThreadMode<'a, D>

Source

pub fn valid(&self) -> bool

Returns true if the iterator is valid. An iterator is invalidated when it reaches the end of its defined range, or when it encounters an error.

To check whether the iterator encountered an error after valid has returned false, use the status method. status will never return an error when valid is true.

Source

pub fn status(&self) -> Result<(), Error>

Returns an error Result if the iterator has encountered an error during operation. When an error is encountered, the iterator is invalidated and valid will return false when called.

Performing a seek will discard the current status.

Source

pub fn refresh(&mut self) -> Result<(), Error>

Refreshes the iterator to represent the latest state of the DB. The iterator is invalidated after this call and must be re-sought before use.

If the iterator was created with a snapshot, the refreshed iterator will no longer use that snapshot and will instead read the latest DB state. The snapshot itself is not released; it remains valid and will be released when the owning crate::SnapshotWithThreadMode is dropped.

Source

pub fn seek_to_first(&mut self)

Seeks to the first key in the database.

§Examples

use rust_rocksdb::{DB, Options};

let tempdir = tempfile::Builder::new()
    .prefix("_path_for_rocksdb_storage5")
    .tempdir()
    .expect("Failed to create temporary path for the _path_for_rocksdb_storage5.");
let path = tempdir.path();
{
    let db = DB::open_default(path).unwrap();
    let mut iter = db.raw_iterator();

    // Iterate all keys from the start in lexicographic order
    iter.seek_to_first();

    while iter.valid() {
        println!("{:?} {:?}", iter.key(), iter.value());
        iter.next();
    }

    // Read just the first key
    iter.seek_to_first();

    if iter.valid() {
        println!("{:?} {:?}", iter.key(), iter.value());
    } else {
        // There are no keys in the database
    }
}
let _ = DB::destroy(&Options::default(), path);

Source

pub fn seek_to_last(&mut self)

Seeks to the last key in the database.

§Examples

use rust_rocksdb::{DB, Options};

let tempdir = tempfile::Builder::new()
    .prefix("_path_for_rocksdb_storage6")
    .tempdir()
    .expect("Failed to create temporary path for the _path_for_rocksdb_storage6.");
let path = tempdir.path();
{
    let db = DB::open_default(path).unwrap();
    let mut iter = db.raw_iterator();

    // Iterate all keys from the end in reverse lexicographic order
    iter.seek_to_last();

    while iter.valid() {
        println!("{:?} {:?}", iter.key(), iter.value());
        iter.prev();
    }

    // Read just the last key
    iter.seek_to_last();

    if iter.valid() {
        println!("{:?} {:?}", iter.key(), iter.value());
    } else {
        // There are no keys in the database
    }
}
let _ = DB::destroy(&Options::default(), path);

Source

pub fn seek<K: AsRef<[u8]>>(&mut self, key: K)

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.

§Examples

use rust_rocksdb::{DB, Options};

let tempdir = tempfile::Builder::new()
    .prefix("_path_for_rocksdb_storage7")
    .tempdir()
    .expect("Failed to create temporary path for the _path_for_rocksdb_storage7.");
let path = tempdir.path();
{
    let db = DB::open_default(path).unwrap();
    let mut iter = db.raw_iterator();

    // Read the first key that starts with 'a'
    iter.seek(b"a");

    if iter.valid() {
        println!("{:?} {:?}", iter.key(), iter.value());
    } else {
        // There are no keys in the database
    }
}
let _ = DB::destroy(&Options::default(), path);

Source

pub fn seek_for_prev<K: AsRef<[u8]>>(&mut self, key: K)

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.

§Examples

use rust_rocksdb::{DB, Options};

let tempdir = tempfile::Builder::new()
    .prefix("_path_for_rocksdb_storage8")
    .tempdir()
    .expect("Failed to create temporary path for the _path_for_rocksdb_storage8.");
let path = tempdir.path();
{
    let db = DB::open_default(path).unwrap();
    let mut iter = db.raw_iterator();

    // Read the last key that starts with 'a'
    iter.seek_for_prev(b"b");

    if iter.valid() {
        println!("{:?} {:?}", iter.key(), iter.value());
    } else {
        // There are no keys in the database
    }
}
let _ = DB::destroy(&Options::default(), path);

Source

pub fn next(&mut self)

Seeks to the next key.

Source

pub fn prev(&mut self)

Seeks to the previous key.

Source

pub fn key(&self) -> Option<&[u8]>

Returns a slice of the current key.

Source

pub fn value(&self) -> Option<&[u8]>

Returns a slice of the current value.

Source

pub fn item(&self) -> Option<(&[u8], &[u8])>

Returns pair with slice of the current key and current value.

Source

pub unsafe fn timestamp(&self) -> &[u8] ⓘ

Returns the timestamp of the current entry.

§Safety

The iterator must be valid (i.e., valid() returns true). Calling this method when the iterator is invalid is undefined behavior, as RocksDB may return an invalid pointer.

Additionally, the column family must have been configured with user defined timestamps. Calling this method on iteration of a column family without user defined timestamps configured will result in assertion failures in debug builds and undefined behaviour in release builds.

Uses rocksdb_iter_timestamp_slice which returns a rocksdb_slice_t by value, avoiding the overhead of output parameters compared to rocksdb_iter_timestamp.