Struct jammdb::Bucket

pub struct Bucket { /* fields omitted */ }

A collection of data

Buckets contain a collection of data, sorted by key. The data can either be key / value pairs, or nested buckets. You can use buckets to get and put data, as well as get and create nested buckets.

You can use a Cursor to iterate over all the data in a bucket.

Buckets have an inner auto-incremented counter that keeps track of how many unique keys have been inserted into the bucket. You can access that using the next_int() function.

Examples

use jammdb::{DB, Data};

let db = DB::open("my.db")?;
let mut tx = db.tx(true)?;

// create a root-level bucket
let bucket = tx.create_bucket("my-bucket")?;

// create nested bucket
bucket.create_bucket("nested-bucket")?;

// insert a key / value pair (using &str)
bucket.put("key", "value");

// insert a key / value pair (using [u8])
bucket.put([1,2,3], [4,5,6]);

for data in bucket.cursor() {
    match &*data {
        Data::Bucket(b) => println!("found a bucket with the name {:?}", b.name()),
        Data::KeyValue(kv) => println!("found a kv pair {:?} {:?}", kv.key(), kv.value()),
    }
}

println!("Bucket next_int {:?}", bucket.next_int());

Implementations

impl Bucket

pub fn put<T: AsRef<[u8]>, S: AsRef<[u8]>>(
    &self,
    key: T,
    value: S
) -> Result<Option<Ref<'_, KVPair>>, Error>

Adds to or replaces key / value data in the bucket. Returns an error if the key currently exists but is a bucket instead of a key / value pair.

Examples

use jammdb::{DB};

let db = DB::open("my.db")?;
let mut tx = db.tx(true)?;

// create a root-level bucket
let bucket = tx.create_bucket("my-bucket")?;

// insert data
bucket.put("123", "456")?;

// update data
bucket.put("123", "789")?;

bucket.create_bucket("nested-bucket")?;

assert!(bucket.put("nested-bucket", "data").is_err());

pub fn cursor(&self) -> Cursor<'_>

Get a cursor to iterate over the bucket.

Examples

use jammdb::{DB, Data};

let db = DB::open("my.db")?;
let mut tx = db.tx(false)?;

let bucket = tx.get_bucket("my-bucket")?;

for data in bucket.cursor() {
    match &*data {
        Data::Bucket(b) => println!("found a bucket with the name {:?}", b.name()),
        Data::KeyValue(kv) => println!("found a kv pair {:?} {:?}", kv.key(), kv.value()),
    }
}

pub fn get_bucket<T: AsRef<[u8]>>(
    &self,
    name: T
) -> Result<BucketRef<'_>, Error>

Gets an already created bucket.

Returns an error if

1. the given key does not exist
2. the key is for key / value data, not a bucket

Examples

use jammdb::{DB};

let db = DB::open("my.db")?;
let mut tx = db.tx(false)?;

// get a root-level bucket
let bucket = tx.get_bucket("my-bucket")?;

// get nested bucket
let mut sub_bucket = bucket.get_bucket("nested-bucket")?;

// get nested bucket
let sub_sub_bucket = sub_bucket.get_bucket("double-nested-bucket")?;

pub fn delete<T: AsRef<[u8]>>(&self, key: T) -> Result<Ref<'_, KVPair>, Error>

Deletes a key / value pair from the bucket

Examples

use jammdb::{DB};

let db = DB::open("my.db")?;
let mut tx = db.tx(false)?;

let bucket = tx.get_bucket("my-bucket")?;
// check if data is there
assert!(bucket.get_kv("some-key").is_some());
// delete the key / value pair
bucket.delete("some-key")?;
// data should no longer exist
assert!(bucket.get_kv("some-key").is_none());

pub fn create_bucket<T: AsRef<[u8]>>(
    &self,
    name: T
) -> Result<BucketRef<'_>, Error>

Creates a new bucket.

Returns an error if

1. the given key already exists
2. It is in a read-only transaction

Examples

use jammdb::{DB};

let db = DB::open("my.db")?;
let mut tx = db.tx(true)?;

// create a root-level bucket
let bucket = tx.create_bucket("my-bucket")?;

// create nested bucket
let mut sub_bucket = bucket.create_bucket("nested-bucket")?;

// create nested bucket
let mut sub_sub_bucket = sub_bucket.create_bucket("double-nested-bucket")?;

pub fn get_or_create_bucket<T: AsRef<[u8]>>(
    &self,
    name: T
) -> Result<BucketRef<'_>, Error>

Creates a new bucket if it doesn't exist

Returns an error if

1. It is in a read-only transaction

Examples

use jammdb::{DB};

let db = DB::open("my.db")?;
{
    let mut tx = db.tx(true)?;
    // create a root-level bucket
    let bucket = tx.get_or_create_bucket("my-bucket")?;
    tx.commit()?;
}
{
    let mut tx = db.tx(true)?;
    // get the existing a root-level bucket
    let bucket = tx.get_or_create_bucket("my-bucket")?;
}

pub fn delete_bucket<T: AsRef<[u8]>>(&self, name: T) -> Result<(), Error>

Deletes an bucket.

Returns an error if

1. the given key does not exist
2. the key is for key / value data, not a bucket
3. It is in a read-only transaction

Examples

use jammdb::{DB};

let db = DB::open("my.db")?;
let mut tx = db.tx(true)?;

// get a root-level bucket
let bucket = tx.get_bucket("my-bucket")?;

// delete nested bucket
bucket.delete_bucket("nested-bucket")?;

pub fn next_int(&self) -> u64

Returns the next integer for the bucket. The integer is automatically incremented each time a new key is added to the bucket. You can it as a unique key for the bucket, since it will increment each time you add something new. It will not increment if you put a key that already exists

Examples

use jammdb::{DB};

let db = DB::open("my.db")?;
let mut tx = db.tx(true)?;

// create a root-level bucket
let bucket = tx.create_bucket("my-bucket")?;
// starts at 0
assert_eq!(bucket.next_int(), 0);

let next_int = bucket.next_int();
bucket.put(next_int.to_be_bytes(), [0]);
// auto-incremented after inserting a key / value pair
assert_eq!(bucket.next_int(), 1);

bucket.put(0_u64.to_be_bytes(), [0, 0]);
// not incremented after updating a key / value pair
assert_eq!(bucket.next_int(), 1);

bucket.create_bucket("nested-bucket")?;
// auto-incremented after creating a nested bucket
assert_eq!(bucket.next_int(), 2);

pub fn get<T: AsRef<[u8]>>(&self, key: T) -> Option<Ref<'_, Data>>

Gets Data from a bucket.

Returns None if the key does not exist. Otherwise returns Some(Data) representing either a key / value pair or a nested-bucket.

Examples

use jammdb::{DB, Data};

let db = DB::open("my.db")?;
let mut tx = db.tx(false)?;

let bucket = tx.get_bucket("my-bucket")?;

match bucket.get("some-key") {
    Some(data) => {
        match &*data {
            Data::Bucket(b) => println!("found a bucket with the name {:?}", b.name()),
            Data::KeyValue(kv) => println!("found a kv pair {:?} {:?}", kv.key(), kv.value()),
        }
    },
    None => println!("Key does not exist"),
}

pub fn get_kv<T: AsRef<[u8]>>(&self, key: T) -> Option<Ref<'_, KVPair>>

Gets a key / value pair from a bucket.

Returns None if the key does not exist, or if the key is for a nested bucket.

Examples

use jammdb::{DB, Data};

let db = DB::open("my.db")?;
let mut tx = db.tx(false)?;

let bucket = tx.get_bucket("my-bucket")?;
bucket.create_bucket("sub-bucket")?;
bucket.put("some-key", "some-value")?;

if let Some(kv) = bucket.get_kv("some-key") {
    assert_eq!(kv.value(), b"some-value");
}
assert!(bucket.get("sub-bucket").is_some());
assert!(bucket.get_kv("sub-bucket").is_none());