Struct gnudbm::RwHandle

pub struct RwHandle { /* fields omitted */ }

A read/write reference to a gdbm database.

Methods

impl RwHandle

fn store<K, V: ?Sized>(&mut self, key: K, value: &V) -> GdbmResult<()> where
    K: AsRef<[u8]>,
    V: Serialize, 

Inserts a key value pair into the database, replacing any existing value for that key.

Returns an Error if the store fails. The only reason this might happen is if there is a problem writing to disk, which is likely not recoverable.

let key = "my key";
let value = "my value";
db.store(key, value).unwrap();

fn store_checked<K, V: ?Sized>(&mut self, key: K, value: &V) -> GdbmResult<()> where
    K: AsRef<[u8]>,
    V: Serialize, 

Inserts a key value pair into the database, failing of the key already exists.

Returns an Error if the store fails, including if it fails because the key already exists.

Examples

let key = "my key";
let value = "my value";
db.store_checked(key, value).unwrap();

// second store will fail
assert!(db.store_checked(key, value).is_err());

fn fetch<K>(&self, key: K) -> GdbmResult<Entry> where
    K: AsRef<[u8]>, 

Attempts to fetch an item from the database.

Returns an Entry if key exists in the database. Returns an Error if the key does not exist, or if an error occurs while reading the database.

let key = "my key";
let value = "my value";
db.store(key.as_bytes(), &value).unwrap();

let entry = db.fetch(key.as_bytes()).unwrap();
let as_str: &str = entry.deserialize().unwrap();

assert_eq!(as_str, value);

fn remove<K>(&self, key: K) -> GdbmResult<bool> where
    K: AsRef<[u8]>, 

Removes an entry from the database. Returns true if an entry was removed, and false if no entry was present. Returns an Error if there is a problem with the database file.

fn count(&self) -> GdbmResult<usize>

Counts the number of items in this database. This is not cached.

Returns the total number of items in the database, or an Error if there was a problem reading the database.

Examples

for i in 0..100 {
    let key = format!("key {}", i);
    let value = format!("value {}", i);
    db.store(key.as_bytes(), &value).unwrap();
}

assert_eq!(db.count().unwrap(), 100);

fn iter<'a>(&'a self) -> Iter<'a>

Returns an iterator over the keys and values in this database. The iterator's element type is (Key, Entry).

Examples

assert_eq!(db.count().unwrap(), db.iter().count());

fn contains_key(&self, key: &[u8]) -> GdbmResult<bool>

Checks the database for the existence of key.

Returns an Error if there was a problem reading the database file, otherwise returns a true if the key is present in the database.

Examples

let key = "my key";
let value = "my value";
db.store_checked(key.as_bytes(), &value).unwrap();

assert!(db.contains_key(key.as_bytes()).unwrap());
assert!(!db.contains_key("missing key".as_bytes()).unwrap());

fn sync(&self)

Synchronizes the changes in the database with the file on disk.

fn reorganize(&mut self) -> GdbmResult<()>

Reorganizes the database file, potentially reducing its size on disk.

Note

This is expensive, and should be used rarely. From the gdbm docs:

If you have had a lot of deletions and would like to shrink the space used by the gdbm file, this function will reorganize the database. This results, in particular, in shortening the length of a gdbm file by removing the space occupied by deleted records.

fn set_cache_size(&mut self, size: usize) -> GdbmResult<()>

Set the size of the internal bucket cache.

Note

This option may only be set once on each database handle. Subsequent calls may fail silently.

fn get_cache_size(&self) -> GdbmResult<usize>

Returns the size of the internal bucket cache.

fn set_sync_mode(&mut self, mode: bool) -> GdbmResult<()>

Sets whether the database is in sync mode; if this is true, changes to the database are written to disk as they occur.

fn get_sync_mode(&self) -> GdbmResult<bool>

Returns true if the database is in sync mode.

fn set_max_mmap_size(&mut self, size: usize) -> GdbmResult<()>

Sets the maximum size of a memory mapped region. This will be rounded to the nearest page boundary.

Note

By default, this is equal to usize::max_value().

fn get_max_mmap_size(&self) -> GdbmResult<usize>

Returns the current maximum size of a memory mapped region.

fn set_mmap_enabled(&mut self, mode: bool) -> GdbmResult<()>

Set whether or not the database should use memory mapping.

fn get_mmap_enabled(&self) -> GdbmResult<bool>

Returns whether or not the database should use memory mapping.

fn get_block_size(&self) -> GdbmResult<usize>

Returns the block size, in bytes. Block size is set when the database is first created, and cannot be changed.

Trait Implementations

impl Debug for RwHandle

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

Formats the value using the given formatter.