### Bucket usage example

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates creating buckets, inserting data, and iterating through contents using a cursor.

```rust
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());
```

--------------------------------

### Perform simple put and get operations in jammdb

Source: https://docs.rs/jammdb/0.11.0/jammdb/index.html

Demonstrates opening a database, creating a bucket, inserting key-value pairs within a writable transaction, and retrieving them using a transaction.

```rust
use jammdb::{DB, Data, Error};

fn main() -> Result<(), Error> {
{
    // open a new database file
    let db = DB::open("my-database.db")?;

    // open a writable transaction so we can make changes
    let mut tx = db.tx(true)?;

    // create a bucket to store a map of first names to last names
    let mut names_bucket = tx.create_bucket("names")?;
    names_bucket.put("Kanan", "Jarrus")?;
    names_bucket.put("Ezra", "Bridger")?;

    // commit the changes so they are saved to disk
    tx.commit()?;
}
{
    // open the existing database file
    let db = DB::open("my-database.db")?;
    // open a read-only transaction to get the data
    let mut tx = db.tx(true)?;
    // get the bucket we created in the last transaction
    let names_bucket = tx.get_bucket("names")?;
    // get the key / value pair we inserted into the bucket
    if let Some(data) = names_bucket.get("Kanan") {
        assert_eq!(data.kv().value(), b"Jarrus");
    }
}
    Ok(())
}
```

--------------------------------

### Match Data Variants

Source: https://docs.rs/jammdb/0.11.0/jammdb/enum.Data.html?search=u32+-%3E+bool

Example of how to retrieve and match on Data variants returned from a bucket.

```rust
use jammdb::{DB, Data};

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

if let Some(data) = bucket.get("my-key") {
    match data {
        Data::Bucket(b) => assert_eq!(b.name(), b"my-key"),
        Data::KeyValue(kv) => assert_eq!(kv.key(), b"my-key"),
    }
}
```

--------------------------------

### Get or create a bucket

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves a bucket if it exists, otherwise creates it. Fails if the transaction is read-only.

```rust
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")?;
}
```

--------------------------------

### Get an existing bucket

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves a bucket by name. Fails if the key does not exist or refers to a key-value pair instead of a bucket.

```rust
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")?;
```

--------------------------------

### Initialize Database with OpenOptions

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.OpenOptions.html?search=

Configure and open a new database file using the builder pattern.

```rust
use jammdb::{DB, OpenOptions};

let db = OpenOptions::new()
    .pagesize(4096)
    .num_pages(32)
    .open("my.db")?;

// do whatever you want with the DB
```

--------------------------------

### OpenOptions::new

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.OpenOptions.html?search=

Creates a new instance of OpenOptions with default configuration values.

```APIDOC
## pub fn new() -> Self

### Description
Returns a new OpenOptions instance initialized with default values.

### Signature
`pub fn new() -> Self`
```

--------------------------------

### Open a database

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.DB.html

Opens a database file using the default OpenOptions. Ensure the path is valid and the process has appropriate file system permissions.

```rust
use jammdb::{DB};

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

// do whatever you want with the DB
```

--------------------------------

### OpenOptions::open

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.OpenOptions.html?search=

Opens the database using the configured options.

```APIDOC
## pub fn open<P: AsRef<Path>>(self, path: P) -> Result<DB, Error>

### Description
Opens the database with the current options. If the file does not exist, it initializes a new database. If it exists, it opens the file and attempts to acquire an exclusive lock.

### Parameters
- **path** (P: AsRef<Path>) - The file path to the database.
```

--------------------------------

### DB::open

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.DB.html

Opens a database file at the specified path using default options.

```APIDOC
## fn open<P: AsRef<Path>>(path: P) -> Result<DB, Error>

### Description
Opens a database using the default OpenOptions. This is equivalent to calling OpenOptions::new().open(path).

### Parameters
- **path** (P: AsRef<Path>) - Required - The file path to the database file.
```

--------------------------------

### OpenOptions::num_pages

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.OpenOptions.html?search=

Sets the initial number of pages to allocate for a new database file.

```APIDOC
## pub fn num_pages(self, num_pages: usize) -> Self

### Description
Sets the number of pages to allocate for a new database file. This setting has no effect when opening an existing database.

### Parameters
- **num_pages** (usize) - The number of pages to allocate. Must be >= 4.
```

--------------------------------

### OpenOptions Methods

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.OpenOptions.html

Methods available on the OpenOptions struct to configure database opening behavior.

```APIDOC
## new()

### Description
Returns a new OpenOptions instance with default values.

## pagesize(pagesize: u64)

### Description
Sets the pagesize for the database. Defaults to the OS pagesize. Panics if pagesize < 1024.

## num_pages(num_pages: usize)

### Description
Sets the number of pages to allocate for a new database file. Defaults to 32. Panics if value < 4.

## strict_mode(strict_mode: bool)

### Description
Enables or disables strict mode, where transactions check for errors before finalizing a write.

## mmap_populate(mmap_populate: bool)

### Description
Enables or disables the MAP_POPULATE flag for the mmap call (Linux only).

## direct_writes(direct_writes: bool)

### Description
Enables or disables the O_DIRECT flag to bypass OS caches when writing (Linux only).

## open<P: AsRef<Path>>(path: P)

### Description
Opens the database with the configured options. Returns a Result containing the DB or an Error.
```

--------------------------------

### Create a new bucket

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new bucket. Fails if the key already exists or the transaction is read-only.

```rust
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")?;
```

--------------------------------

### create_bucket

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Tx.html

Creates a new root-level bucket.

```APIDOC
## pub fn create_bucket<'b, T: ToBytes<'tx>>( &'b self, name: T, ) -> Result<Bucket<'b, 'tx>, Error>

### Description
Creates a new bucket with the given name and returns a reference it.

### Errors
- BucketExists: If the bucket already exists.
- IncompatibleValue: If the key exists but is not a bucket.
- ReadOnlyTx: If called on a read-only transaction.
```

--------------------------------

### create_bucket

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Tx.html?search=std%3A%3Avec

Creates a new bucket with the given name and returns a reference to it.

```APIDOC
### pub fn create_bucket<'b, T: ToBytes<'tx>>( &'b self, name: T, ) -> Result<Bucket<'b, 'tx>, Error>

Creates a new bucket with the given name and returns a reference it.

#### Errors
- BucketExists: Returned if the bucket already exists.
- IncompatibleValue: Returned if the key exists but is not a bucket.
- ReadOnlyTx: Returned if called on a read-only transaction.
```

--------------------------------

### fn to_buckets(self) -> Buckets<'b, 'tx, Self>

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Cursor.html?search=u32+-%3E+bool

Converts the current cursor into a Buckets iterator.

```APIDOC
## fn to_buckets(self) -> Buckets<'b, 'tx, Self>

### Description
Converts the current cursor into a Buckets iterator, allowing iteration over buckets associated with the cursor.

### Signature
`fn to_buckets(self) -> Buckets<'b, 'tx, Self>`
```

--------------------------------

### Perform database transactions

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Tx.html

Demonstrates creating read-only and writable transactions, creating buckets, and verifying data isolation between them.

```rust
use jammdb::{DB, Data};

// create a read-only transaction
let mut tx1 = db.tx(false)?;
// create a writable transcation
let mut tx2 = db.tx(true)?;

// create a new bucket in the writable transaction
tx2.create_bucket("new-bucket")?;

// the read-only transaction will not be able to see the new bucket
assert!(tx1.get_bucket("new-bucket").is_err());

// get a view of an existing bucket from both transactions
let mut b1 = tx1.get_bucket("existing-bucket")?;
let mut b2 = tx2.get_bucket("existing-bucket")?;

// make an edit to the bucket
b2.put("new-key", "new-value")?;

// the read-only transaction will not have this new key
assert_eq!(b1.get("new-key"), None);
// but it will be able to see data that already existed!
assert!(b1.get("existing-key").is_some());
```

--------------------------------

### OpenOptions::pagesize

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.OpenOptions.html?search=

Configures the page size for the database file.

```APIDOC
## pub fn pagesize(self, pagesize: u64) -> Self

### Description
Sets the page size for the database. By default, the OS page size is used. Note that opening an existing database with an incorrect page size will cause a panic.

### Parameters
- **pagesize** (u64) - The size in bytes. Must be >= 1024.
```

--------------------------------

### OpenOptions::direct_writes

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.OpenOptions.html?search=std%3A%3Avec

Configures the O_DIRECT flag for file writes on Linux.

```APIDOC
## pub fn direct_writes(self, direct_writes: bool) -> Self

### Description
Enables or disables the O_DIRECT flag, hinting to Linux to bypass OS caches when writing. This is a no-op on non-Linux platforms.
```

--------------------------------

### get_or_create_bucket

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Tx.html

Retrieves an existing bucket or creates it if it does not exist.

```APIDOC
## pub fn get_or_create_bucket<'b, T: ToBytes<'tx>>( &'b self, name: T, ) -> Result<Bucket<'b, 'tx>, Error>

### Description
Creates an existing root-level bucket with the given name if it does not already exist. Gets the existing bucket if it does exist.

### Errors
- IncompatibleValue: If the key exists but is not a bucket.
- ReadOnlyTx: If called on a read-only transaction.
```

--------------------------------

### OpenOptions::mmap_populate

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.OpenOptions.html?search=std%3A%3Avec

Configures the MAP_POPULATE flag for memory mapping on Linux.

```APIDOC
## pub fn mmap_populate(self, mmap_populate: bool) -> Self

### Description
Enables or disables the MAP_POPULATE flag for the mmap call, causing Linux to eagerly load pages into memory. This is a no-op on non-Linux platforms.
```

--------------------------------

### fn to_buckets(self) -> Buckets<'b, 'tx, Self>

Source: https://docs.rs/jammdb/0.11.0/jammdb/trait.ToBuckets.html?search=std%3A%3Avec

Converts the implementing type into a Buckets structure.

```APIDOC
## fn to_buckets(self) -> Buckets<'b, 'tx, Self>

### Description
Converts the current iterator instance into a `Buckets` object, allowing for bucket-level access within the database transaction.

### Signature
`fn to_buckets(self) -> Buckets<'b, 'tx, Self>`

### Returns
- **Buckets<'b, 'tx, Self>** - A structure representing the buckets derived from the iterator.
```

--------------------------------

### Store serialized structs in jammdb

Source: https://docs.rs/jammdb/0.11.0/jammdb/index.html

Shows how to use serde and rmp-serde to serialize Rust structs into MessagePack format for storage in a bucket.

```rust
use jammdb::{DB, Data, Error};
use serde::{Deserialize, Serialize};
// use rmps crate to serialize structs using the MessagePack format
use rmp_serde::{Deserializer, Serializer};

#[derive(Debug, PartialEq, Deserialize, Serialize)]
struct User {
    username: String,
    password: String,
}

fn main() -> Result<(), Error> {
    let user = User{
        username: "my-user".to_string(),
        password: "my-password".to_string(),
    };
{
    // open a new database file and start a writable transaction
    let db = DB::open("my-database.db")?;
    let mut tx = db.tx(true)?;

    // create a bucket to store users
    let mut users_bucket = tx.create_bucket("users")?;

    // serialize struct to bytes and store in bucket
    let user_bytes = rmp_serde::to_vec(&user).unwrap();
    users_bucket.put("user1", user_bytes)?;

    // commit the changes so they are saved to disk
    tx.commit()?;
}
{
    // open the existing database file
    let db = DB::open("my-database.db")?;
    // open a read-only transaction to get the data
    let mut tx = db.tx(true)?;
    // get the bucket we created in the last transaction
    let users_bucket = tx.get_bucket("users")?;
    // get the key / value pair we inserted into the bucket
    if let Some(data) = users_bucket.get(b"user1") {
        // deserialize into a user struct
        let db_user: User = rmp_serde::from_slice(data.kv().value()).unwrap();
        assert_eq!(db_user, user);
    }
}
    Ok(())
}
```

--------------------------------

### Accessing Key-Value Pairs

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.KVPair.html

Demonstrates how to retrieve a key-value pair from a bucket and access its contents as byte slices.

```rust
use jammdb::{DB, Data};

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

// put a key / value pair into the bucket
bucket.put("my-key", "my-value")?;
if let Some(data) = bucket.get("my-key") {
    if let Data::KeyValue(kv) = data {
        let key: &[u8] = kv.key();
        let value: &[u8] = kv.value();
        assert_eq!(key, b"my-key");
        assert_eq!(value, b"my-value");
    }
}
```

--------------------------------

### fn to_buckets(self) -> Buckets<'b, 'tx, Self>

Source: https://docs.rs/jammdb/0.11.0/jammdb/trait.ToBuckets.html?search=u32+-%3E+bool

Converts the current iterator into a Buckets structure.

```APIDOC
## fn to_buckets(self) -> Buckets<'b, 'tx, Self>

### Description
Converts the iterator into a Buckets structure for managing database buckets.

### Signature
`fn to_buckets(self) -> Buckets<'b, 'tx, Self>`

### Requirements
- This trait is not dyn compatible.
```

--------------------------------

### buckets

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Tx.html

Iterates over all root-level buckets.

```APIDOC
## pub fn buckets<'b>( &'b self, ) -> impl Iterator<Item = (BucketName<'b, 'tx>, Bucket<'b, 'tx>)>

### Description
Returns an iterator over the root level buckets.
```

--------------------------------

### OpenOptions Struct Definition

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.OpenOptions.html?search=

The internal structure definition for OpenOptions.

```rust
pub struct OpenOptions { /* private fields */ }
```

--------------------------------

### current

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Cursor.html

Returns the data at the cursor’s current position.

```APIDOC
## pub fn current<'a>(&'a self) -> Option<Data<'b, 'tx>>

### Description
Returns the data at the cursor’s current position. This is useful for retrieving data after performing a seek operation.

### Returns
- **Option<Data<'b, 'tx>>** - The data at the current position, or None if the cursor is out of bounds.
```

--------------------------------

### Using next_int for unique key generation

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how next_int increments when adding new keys or nested buckets, but stays constant when updating existing keys.

```rust
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);
```

--------------------------------

### Accessing Nested Buckets with BucketName

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.BucketName.html

Demonstrates how to retrieve a nested bucket and access its name using the BucketName type.

```rust
use jammdb::{DB, Data};

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

bucket.create_bucket("my-nested-bucket")?;
if let Some(data) = bucket.get("my-nested-bucket") {
    if let Data::Bucket(b) = data {
        let name: &[u8] = b.name();
        assert_eq!(name, b"my-nested-bucket");
        let nested_bucket = bucket.get_bucket(&b).unwrap();
    }
}
```

--------------------------------

### Iterate over a bucket with a cursor

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides a cursor to traverse the contents of a bucket.

```rust
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()),
    }
}
```

--------------------------------

### to_buckets

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Cursor.html

Converts the current cursor into a Buckets iterator.

```APIDOC
## fn to_buckets(self) -> Buckets<'b, 'tx, Self>

### Description
Converts the cursor into a `Buckets` iterator, allowing iteration over the buckets associated with the cursor's transaction.
```

--------------------------------

### OpenOptions::default()

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.OpenOptions.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the default value for the OpenOptions structure.

```APIDOC
## fn default() -> Self

### Description
Returns the default value for the OpenOptions type.

### Returns
- **Self** - The default instance of OpenOptions.
```

--------------------------------

### Tx API Methods

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Tx.html?search=u32+-%3E+bool

Methods available on the JammDB Tx struct for managing buckets and committing transactions.

```APIDOC
## pub fn get_bucket<'b, T: ToBytes<'tx>>(&'b self, name: T) -> Result<Bucket<'b, 'tx>, Error>

### Description
Returns a reference to the root level bucket with the given name.

## pub fn create_bucket<'b, T: ToBytes<'tx>>(&'b self, name: T) -> Result<Bucket<'b, 'tx>, Error>

### Description
Creates a new bucket with the given name and returns a reference to it.

## pub fn get_or_create_bucket<'b, T: ToBytes<'tx>>(&'b self, name: T) -> Result<Bucket<'b, 'tx>, Error>

### Description
Creates a root-level bucket with the given name if it does not exist, or returns the existing bucket.

## pub fn delete_bucket<T: ToBytes<'tx>>(&self, key: T) -> Result<(), Error>

### Description
Deletes an existing root-level bucket with the given name.

## pub fn buckets<'b>(&'b self) -> impl Iterator<Item = (BucketName<'b, 'tx>, Bucket<'b, 'tx>)> 

### Description
Returns an iterator over the root level buckets.

## pub fn commit(self) -> Result<(), Error>

### Description
Writes the changes made in the writeable transaction to the underlying file.
```

--------------------------------

### Put key-value data into a bucket

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Adds or replaces key-value pairs in a bucket. Returns an error if the key exists as a bucket instead of a key-value pair.

```rust
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());
```

--------------------------------

### seek

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Cursor.html

Moves the cursor to the specified key. If the key does not exist, the cursor is positioned where the key would have been. Returns true if the key exists, false otherwise.

```APIDOC
## pub fn seek<T: AsRef<[u8]>>(&mut self, key: T) -> bool

### Description
Moves the cursor to the given key. If the key does not exist, the cursor stops “just before” where the key would be.

### Parameters
- **key** (T: AsRef<[u8]>) - Required - The key to seek to.

### Returns
- **bool** - Returns true if the key exists in the bucket, false otherwise.
```

--------------------------------

### seek

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Cursor.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Moves the cursor to the specified key. If the key does not exist, the cursor is positioned where the key would be inserted.

```APIDOC
## pub fn seek<T: AsRef<[u8]>>(&mut self, key: T) -> bool

### Description
Moves the cursor to the given key. If the key does not exist, the cursor stops "just before" where the key would be.

### Parameters
- **key** (T: AsRef<[u8]>) - Required - The key to seek to.

### Returns
- **bool** - Returns true if the key exists in the bucket, false otherwise.
```

--------------------------------

### get_bucket

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Tx.html

Retrieves a reference to a root-level bucket by name.

```APIDOC
## pub fn get_bucket<'b, T: ToBytes<'tx>>( &'b self, name: T, ) -> Result<Bucket<'b, 'tx>, Error>

### Description
Returns a reference to the root level bucket with the given name.

### Errors
- BucketMissing: If the bucket does not exist.
- IncompatibleValue: If the key exists but is not a bucket.
```

--------------------------------

### BucketName Definition

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.BucketName.html

The internal structure definition for BucketName.

```rust
pub struct BucketName<'b, 'tx> { /* private fields */ }
```

--------------------------------

### Define DB struct

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.DB.html?search=

The internal structure definition for the database handle.

```rust
pub struct DB { /* private fields */ }
```

--------------------------------

### DB::tx

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.DB.html

Creates a new transaction for the database.

```APIDOC
## fn tx(&self, writable: bool) -> Result<Tx<'_>, Error>

### Description
Creates a Tx (transaction) instance. The transaction can be configured as read-only or writable via the parameter.

### Parameters
- **writable** (bool) - Required - If true, the transaction allows write operations; if false, it is read-only.
```

--------------------------------

### Define Tx struct

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Tx.html

The definition of the Tx struct.

```rust
pub struct Tx<'tx> { /* private fields */ }
```

--------------------------------

### next_int

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=

Returns the next integer for the bucket, which is automatically incremented when a new key is added or a nested bucket is created.

```APIDOC
## pub fn next_int(&self) -> u64

### Description
Returns the next integer for the bucket. The integer is automatically incremented each time a new key is added to the bucket or a nested bucket is created. It can be used as a unique key for the bucket.
```

--------------------------------

### Data::kv

Source: https://docs.rs/jammdb/0.11.0/jammdb/enum.Data.html?search=u32+-%3E+bool

Asserts that the Data is a KVPair and returns the inner data.

```APIDOC
## pub fn kv(&self) -> &KVPair<'_, '_>

### Description
Returns the inner `KVPair` data. 

### Panics
Panics if the `Data` variant is a `Bucket`.
```

--------------------------------

### OpenOptions::strict_mode

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.OpenOptions.html?search=

Enables or disables strict mode for transaction error checking.

```APIDOC
## pub fn strict_mode(self, strict_mode: bool) -> Self

### Description
Enables or disables 'Strict Mode', where each transaction checks the database for errors before finalizing a write. Default is false.
```

--------------------------------

### range

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=

Returns an iterator over a specified range of keys in the bucket.

```APIDOC
## pub fn range<'a, R>(&'a self, r: R) -> Range<'a, 'b, 'tx, R>

### Description
Returns an iterator over a range of keys defined by the provided range bounds.
```

--------------------------------

### BucketName::name

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.BucketName.html

Returns the name of the bucket as a byte slice.

```APIDOC
## pub fn name(&self) -> &[u8]

### Description
Returns the name of the bucket as a byte slice.

### Signature
`pub fn name(&self) -> &[u8]`
```

--------------------------------

### to_kv_pairs

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Cursor.html

Converts the current cursor into a KVPairs iterator.

```APIDOC
## fn to_kv_pairs(self) -> KVPairs<Self>

### Description
Converts the cursor into a `KVPairs` iterator, allowing iteration over the key-value pairs associated with the cursor.
```

--------------------------------

### Cursor Definition

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Cursor.html

The internal structure definition for the Cursor.

```rust
pub struct Cursor<'b, 'tx> { /* private fields */ }
```

--------------------------------

### DB::pagesize

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.DB.html

Retrieves the page size of the database.

```APIDOC
## fn pagesize(&self) -> u64

### Description
Returns the configured page size of the database in bytes.
```

--------------------------------

### Define KVPairs struct

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.KVPairs.html

The definition of the KVPairs struct.

```rust
pub struct KVPairs<I> { /* private fields */ }
```

--------------------------------

### Bucket struct definition

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The internal structure definition for the Bucket type.

```rust
pub struct Bucket<'b, 'tx: 'b> { /* private fields */ }
```

--------------------------------

### Delete a bucket

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Deletes a bucket. Fails if the key does not exist, is not a bucket, or the transaction is read-only.

```rust
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")?;
```

--------------------------------

### KVPair Definition

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.KVPair.html

The definition of the KVPair struct.

```rust
pub struct KVPair<'b, 'tx> { /* private fields */ }
```

--------------------------------

### to_buckets

Source: https://docs.rs/jammdb/0.11.0/jammdb/trait.ToBuckets.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The to_buckets method is a required method of the ToBuckets trait that consumes the iterator and returns a Buckets instance.

```APIDOC
## fn to_buckets(self) -> Buckets<'b, 'tx, Self>

### Description
Converts the current iterator into a `Buckets` structure for further database operations.

### Signature
`fn to_buckets(self) -> Buckets<'b, 'tx, Self>`

### Returns
- **Buckets<'b, 'tx, Self>** - A structure representing the buckets derived from the iterator.
```

--------------------------------

### commit

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Tx.html

Commits transaction changes to disk.

```APIDOC
## pub fn commit(self) -> Result<(), Error>

### Description
Writes the changes made in the writeable transaction to the underlying file.

### Errors
- IOError: If there are any IO errors while writing to disk.
- ReadOnlyTx: If called on a read-only transaction.
```

--------------------------------

### range

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html

Returns a range iterator for the bucket based on provided bounds.

```APIDOC
## pub fn range<'a, R>(&'a self, r: R) -> Range<'a, 'b, 'tx, R>

### Description
Returns a range iterator over the key / value pairs in this bucket within the specified bounds.
```

--------------------------------

### kv_pairs

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns an iterator over the key-value pairs stored in the bucket.

```APIDOC
## pub fn kv_pairs<'a>(&'a self) -> impl Iterator<Item = KVPair<'b, 'tx>>

### Description
Returns an iterator over the key / value pairs in this bucket.
```

--------------------------------

### buckets

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=

Returns an iterator over the sub-buckets contained within this bucket.

```APIDOC
## pub fn buckets<'a>(&'a self) -> impl Iterator<Item = (BucketName<'b, 'tx>, Bucket<'b, 'tx>)>

### Description
Returns an iterator over the sub-buckets in this bucket.
```

--------------------------------

### fn to_bytes(self) -> Bytes<'a>

Source: https://docs.rs/jammdb/0.11.0/jammdb/trait.ToBytes.html?search=u32+-%3E+bool

The to_bytes method is the required function of the ToBytes trait. It consumes the implementing type and returns a Bytes object.

```APIDOC
## fn to_bytes(self) -> Bytes<'a>

### Description
Converts the implementing type into a `Bytes` object.

### Signature
`fn to_bytes(self) -> Bytes<'a>`

### Parameters
- **self** - The instance of the type implementing the trait.

### Returns
- **Bytes<'a>** - A `Bytes` representation of the input data.
```

--------------------------------

### Define Buckets struct

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Buckets.html

The definition of the Buckets struct, which manages iteration over sub-buckets.

```rust
pub struct Buckets<'b, 'tx, I> { /* private fields */ }
```

--------------------------------

### delete_bucket

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Tx.html

Deletes a root-level bucket by name.

```APIDOC
## pub fn delete_bucket<T: ToBytes<'tx>>(&self, key: T) -> Result<(), Error>

### Description
Deletes an existing root-level bucket with the given name.

### Errors
- BucketMissing: If the bucket does not exist.
- IncompatibleValue: If the key exists but is not a bucket.
- ReadOnlyTx: If called on a read-only transaction.
```

--------------------------------

### ToBuckets Trait Definition

Source: https://docs.rs/jammdb/0.11.0/jammdb/trait.ToBuckets.html

The trait definition for ToBuckets, requiring an iterator of Data items.

```rust
pub trait ToBuckets<'b, 'tx: 'b>: Iterator<Item = Data<'b, 'tx>> + Sized {
    // Required method
    fn to_buckets(self) -> Buckets<'b, 'tx, Self> ⓘ;
}
```

--------------------------------

### Delete key-value pairs from a bucket

Source: https://docs.rs/jammdb/0.11.0/jammdb/struct.Bucket.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Removes a specific key-value pair from the bucket.

```rust
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());
```

--------------------------------

### Data::is_kv

Source: https://docs.rs/jammdb/0.11.0/jammdb/enum.Data.html?search=u32+-%3E+bool

Checks if the Data variant is a KVPair.

```APIDOC
## pub fn is_kv(&self) -> bool

### Description
Checks if the `Data` instance is a `KVPair` variant.

### Returns
- **bool** - Returns true if the variant is `KVPair`, false otherwise.
```

--------------------------------

### Define Data Enum

Source: https://docs.rs/jammdb/0.11.0/jammdb/enum.Data.html?search=u32+-%3E+bool

The structure of the Data enum with its two variants.

```rust
pub enum Data<'b, 'tx> {
    Bucket(BucketName<'b, 'tx>),
    KeyValue(KVPair<'b, 'tx>),
}
```

--------------------------------

### ToBytes Trait Definition

Source: https://docs.rs/jammdb/0.11.0/jammdb/trait.ToBytes.html

The core trait definition requiring the implementation of the to_bytes method.

```rust
pub trait ToBytes<'a> {
    // Required method
    fn to_bytes(self) -> Bytes<'a>;
}
```

--------------------------------

### ToKVPairs Trait Definition

Source: https://docs.rs/jammdb/0.11.0/jammdb/trait.ToKVPairs.html

The trait definition requiring an implementation of to_kv_pairs for types that iterate over Data.

```rust
pub trait ToKVPairs<'b, 'tx>: Iterator<Item = Data<'b, 'tx>> + Sized {
    // Required method
    fn to_kv_pairs(self) -> KVPairs<Self> ⓘ;
}
```

--------------------------------

### Error Enum Definition

Source: https://docs.rs/jammdb/0.11.0/jammdb/enum.Error.html?search=u32+-%3E+bool

The primary enum structure defining all possible error types in jammdb.

```rust
pub enum Error {
    BucketExists,
    BucketMissing,
    KeyValueMissing,
    IncompatibleValue,
    ReadOnlyTx,
    Io(Error),
    Sync(&'static str),
    InvalidDB(String),
    Alloc(LayoutError),
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.