Rustbreak

https://docs.rs/rustbreak/2.0.0/rustbreak/
Admin
Rustbreak is a configurable single-file embedded database library for Rust that supports multiple...
Tokens:50,891
Snippets:360
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Handling File Metadata with and_then

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.DeSerResult.html

Shows how to use `and_then` to chain operations that might fail, such as getting file metadata. This example uses `std::path::Path` and handles potential `IOError`.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

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

### Example DeSerializer Implementation (Frobnar)

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/deser/trait.DeSerializer.html

An example implementation of the DeSerializer trait for an imaginary serde compatible encoding scheme named 'Frobnar'.

```APIDOC
## §Example
For an imaginary serde compatible encoding scheme ‘Frobnar’, an example implementation can look like this:

```rust
extern crate rustbreak;
extern crate thiserror;
extern crate serde;
#[macro_use]

use serde::de::Deserialize;
use serde::Serialize;
use std::io::Read;

use rustbreak::deser::DeSerializer;
use rustbreak::error;

#[derive(Clone, Debug, thiserror::Error)]
#[error("A frobnarizer could not splagrle.")]
struct FrobnarError;

fn to_frobnar<T: Serialize>(input: &T) -> Vec<u8> {
    unimplemented!(); // implementation not specified
}

fn from_frobnar<'r, T: Deserialize<'r> + 'r, R: Read>(input: &R) -> Result<T, FrobnarError> {
    unimplemented!(); // implementation not specified
}

#[derive(Debug, Default, Clone)]
struct Frobnar;

impl<T: Serialize> DeSerializer<T> for Frobnar
where
    for<'de> T: Deserialize<'de>,
{
    fn serialize(&self, val: &T) -> rustbreak::DeSerResult<Vec<u8>> {
        Ok(to_frobnar(val))
    }

    fn deserialize<R: Read>(&self, s: R) -> rustbreak::DeSerResult<T> {
        Ok(from_frobnar(&s).map_err(|e| error::DeSerError::Other(e.into()))?) // implementation not specified
    }
}

fn main() {}
```

**Important**: You can only return custom errors if the `other_errors` feature is enabled.
```

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

### Get Metadata with Path and Handle Errors

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.Result.html

Demonstrates using `metadata().and_then(|md| md.modified())` to get file modification times. Handles potential errors like 'NotFound'. Note the platform-specific behavior of '/' on Windows.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

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

### Construct MemoryBackend

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/backend/struct.MemoryBackend.html

Creates a new instance of the MemoryBackend. No specific setup is required beyond calling this function.

```rust
pub fn new() -> Self
```

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

### Handle Rustbreak errors

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/index.html

Example of matching on the result of a database initialization to handle potential errors.

```rust
use rustbreak::{deser::Ron, error::RustbreakError, MemoryDatabase};
let db = match MemoryDatabase::<usize, Ron>::memory(0) {
    Ok(db) => db,
    Err(e) => {
        // Do something with `e` here
        std::process::exit(1);
    }
};
```

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

### Checking Result with Predicates

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.Result.html

Examples of using is_ok_and to check Result values against a predicate.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

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

### Copying Result Contents

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.Result.html

Examples of using copied() on Result<&T, E> and Result<&mut T, E>.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

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

### Cloning Result Contents

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.Result.html

Examples of using cloned() on Result<&T, E> and Result<&mut T, E>.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

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

### Flattening Nested Results

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.Result.html

Examples of flattening nested Result types.

```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());
```

```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

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

### Transposing Result and Option

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.Result.html

Example of transposing a Result of an Option into an Option of a Result.

```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

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

### Checking Result Status

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.Result.html

Examples of checking if a result is Ok or Err.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

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

### Implement DeSerializer for a custom format

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/deser/trait.DeSerializer.html

An example implementation of the DeSerializer trait for an imaginary encoding scheme called Frobnar.

```rust
extern crate rustbreak;
extern crate thiserror;
extern crate serde;
#[macro_use]

use serde::de::Deserialize;
use serde::Serialize;
use std::io::Read;

use rustbreak::deser::DeSerializer;
use rustbreak::error;

#[derive(Clone, Debug, thiserror::Error)]
#[error("A frobnarizer could not splagrle.")]
struct FrobnarError;

fn to_frobnar<T: Serialize>(input: &T) -> Vec<u8> {
    unimplemented!(); // implementation not specified
}

fn from_frobnar<'r, T: Deserialize<'r> + 'r, R: Read>(input: &R) -> Result<T, FrobnarError> {
    unimplemented!(); // implementation not specified
}

#[derive(Debug, Default, Clone)]
struct Frobnar;

impl<T: Serialize> DeSerializer<T> for Frobnar
where
    for<'de> T: Deserialize<'de>,
{
    fn serialize(&self, val: &T) -> rustbreak::DeSerResult<Vec<u8>> {
        Ok(to_frobnar(val))
    }

    fn deserialize<R: Read>(&self, s: R) -> rustbreak::DeSerResult<T> {
        Ok(from_frobnar(&s).map_err(|e| error::DeSerError::Other(e.into()))?)
    }
}

fn main() {}
```

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

### Read from PathDatabase

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.PathDatabase.html

Read lock the database and get read-only access to the Data container. Multiple readers can access concurrently. Panicking poisons the database.

```rust
use rustbreak::{deser::Ron, FileDatabase};

#[derive(Debug, Serialize, Deserialize, Clone)]
struct Data {
    level: u32,
}

let db = FileDatabase::<Data, Ron>::from_file(file, Data { level: 0 })?;

db.write(|db| {
    db.level = 42;
})?;

let value = db.read(|db| db.level)?;
assert_eq!(42, value);
```

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

### Chain fallible operations with and_then

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.BackendResult.html

Use and_then to chain operations that return a Result. The first example demonstrates mapping a value, while the second shows file system metadata access.

```rust
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {
    x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")
}

assert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));
assert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));
assert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));
```

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

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

### Open, Create, and Configure FileBackend

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/backend/struct.FileBackend.html

Opens a FileBackend for a given path, creating it if it doesn't exist. It then calls a closure with the file handle for further configuration or operations.

```rust
pub fn from_path_or_create_and<P, C>(path: P, closure: C) -> BackendResult<Self>
where C: FnOnce(&mut File), P: AsRef<Path>,
```

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

### Initialize and use MemoryDatabase

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/index.html

Demonstrates creating a memory-backed database and performing read/write operations using closures.

```rust
use rustbreak::{deser::Ron, MemoryDatabase};

let db = MemoryDatabase::<HashMap<u32, String>, Ron>::memory(HashMap::new())?;

println!("Writing to Database");
db.write(|db| {
    db.insert(0, String::from("world"));
    db.insert(1, String::from("bar"));
});

db.read(|db| {
    // db.insert("foo".into(), String::from("bar"));
    // The above line will not compile since we are only reading
    println!("Hello: {:?}", db.get(&0));
})?;
```

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

### PathBackend Initialization Methods

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/backend/struct.PathBackend.html

Methods for initializing a PathBackend instance from a file path.

```APIDOC
## PathBackend Initialization

### Description
Methods to open or create a file-based backend for database storage.

### Methods
- **from_path_or_fail(path: PathBuf) -> BackendResult<Self>**
  Opens an existing file. Returns an error if the file does not exist.
- **from_path_or_create(path: PathBuf) -> BackendResult<(Self, bool)>**
  Opens a file or creates it if it does not exist. Returns the instance and a boolean indicating if the file already existed.
- **from_path_or_create_and<C>(path: PathBuf, closure: C) -> BackendResult<Self>**
  Opens or creates a file and executes a closure on the file handle.
```

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

### Open or Create FileBackend from Path

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/backend/struct.FileBackend.html

Opens a FileBackend for a given path. If the file does not exist, it will be created. Returns the backend and a boolean indicating if the file already existed.

```rust
pub fn from_path_or_create<P: AsRef<Path>>( path: P, ) -> BackendResult<(Self, bool)>
```

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

### FileBackend Methods

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/backend/struct.FileBackend.html

Methods for initializing and managing a FileBackend instance.

```APIDOC
## FileBackend Initialization

### Description
Methods to create or open a FileBackend from existing files or file paths.

### Methods
- **from_file(file: File) -> Self**: Use an already open File as the backend.
- **into_inner(self) -> File**: Return the inner File.
- **from_path_or_fail<P: AsRef<Path>>(path: P) -> BackendResult<Self>**: Opens a new FileBackend for a given path. Errors when the file doesn’t yet exist.
- **from_path_or_create<P: AsRef<Path>>(path: P) -> BackendResult<(Self, bool)>**: Opens a new FileBackend for a given path. Creates a file if it doesn’t yet exist. Returns the FileBackend and whether the file already existed.
- **from_path_or_create_and<P, C>(path: P, closure: C) -> BackendResult<Self>**: Opens a new FileBackend for a given path. Creates a file if it doesn’t yet exist, and calls closure with it.
```

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

### MemoryBackend Constructor

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/backend/struct.MemoryBackend.html

How to create a new instance of the MemoryBackend.

```APIDOC
## MemoryBackend::new()

### Description
Construct a new Memory Database.

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

### Endpoint
N/A (Constructor)
```

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

### Perform basic database operations

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.MemoryDatabase.html

Demonstrates initializing a FileDatabase, modifying data via mutable borrowing, and verifying the state.

```rust
use rustbreak::{deser::Ron, FileDatabase};

#[derive(Debug, Serialize, Deserialize, Clone)]
struct Data {
    level: u32,
}

let db = FileDatabase::<Data, Ron>::from_file(file, Data { level: 0 })?;

{
    let mut data = db.borrow_data_mut()?;
    data.level = 42;
}

let data = db.borrow_data()?;

assert_eq!(42, data.level);
```

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

### PathDatabase Initialization

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.PathDatabase.html

Methods for creating and loading databases from file paths.

```APIDOC
## load_from_path

### Description
Create new PathDatabase from the file at Path, and load the contents.

## load_from_path_or

### Description
Load PathDatabase at path or initialise with provided data if the file does not exist.

## create_at_path

### Description
Create PathDatabase at path. Initialise with data if the file doesn’t exist. Contents are not loaded.
```

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

### Create FileBackend from Open File

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/backend/struct.FileBackend.html

Use this function to initialize a FileBackend with an already opened File object. Ensure the File is properly managed after use.

```rust
pub fn from_file(file: File) -> Self
```

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

### PathDatabase Loading and Initialization

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/struct.Database.html

Functions for creating and loading PathDatabase instances from file paths, with options for initializing with provided data or a closure.

```APIDOC
## POST /api/path_database/load_from_path

### Description
Creates a new `PathDatabase` from the file at the specified path and loads its contents.

### Method
POST

### Endpoint
/api/path_database/load_from_path

### Parameters
#### Path Parameters
- **path** (PathBuf) - Required - The file path to load the database from.

### Response
#### Success Response (200)
- **Self** (PathDatabase) - The newly created and loaded PathDatabase instance.

#### Response Example
```json
{
  "database": "..."
}
```
```

```APIDOC
## POST /api/path_database/load_from_path_or

### Description
Loads a `PathDatabase` from the specified path. If the file does not exist, it initializes the database with the provided data.

### Method
POST

### Endpoint
/api/path_database/load_from_path_or

### Parameters
#### Path Parameters
- **path** (PathBuf) - Required - The file path to load or initialize the database from.

#### Request Body
- **data** (Data) - Required - The data to initialize the database with if the file does not exist.

### Response
#### Success Response (200)
- **Self** (PathDatabase) - The PathDatabase instance.

#### Response Example
```json
{
  "database": "..."
}
```
```

```APIDOC
## POST /api/path_database/load_from_path_or_else

### Description
Loads a `PathDatabase` from the specified path. If the file does not exist, a closure is called, and the database is initialized with its return value.

### Method
POST

### Endpoint
/api/path_database/load_from_path_or_else

### Parameters
#### Path Parameters
- **path** (PathBuf) - Required - The file path to load or initialize the database from.

#### Request Body
- **closure** (FnOnce() -> Data) - Required - A closure that returns the data to initialize the database with if the file does not exist.

### Response
#### Success Response (200)
- **Self** (PathDatabase) - The PathDatabase instance.

#### Response Example
```json
{
  "database": "..."
}
```
```

```APIDOC
## POST /api/path_database/create_at_path

### Description
Creates a `PathDatabase` at the specified path. If the file does not exist, it is initialized with the provided data. The frontend is always initialized with the provided data.

### Method
POST

### Endpoint
/api/path_database/create_at_path

### Parameters
#### Path Parameters
- **path** (PathBuf) - Required - The path where the database should be created.

#### Request Body
- **data** (Data) - Required - The data to initialize the database with.

### Response
#### Success Response (200)
- **Self** (PathDatabase) - The newly created PathDatabase instance.

#### Response Example
```json
{
  "database": "..."
}
```
```

```APIDOC
## POST /api/path_database/load_from_path_or_default

### Description
Loads a `PathDatabase` from the specified path. If the file does not exist, it initializes the database with `Data::default()`.

### Method
POST

### Endpoint
/api/path_database/load_from_path_or_default

### Parameters
#### Path Parameters
- **path** (PathBuf) - Required - The file path to load or initialize the database from.

### Response
#### Success Response (200)
- **Self** (PathDatabase) - The PathDatabase instance.

#### Response Example
```json
{
  "database": "..."
}
```
```

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

### Get TypeId for Any Trait

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/backend/struct.MemoryBackend.html

Retrieves the `TypeId` of the current type, as required by the `Any` trait. This is a blanket implementation.

```rust
fn type_id(&self) -> TypeId
```

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

### FileDatabase Initialization

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/struct.Database.html

Methods for creating and initializing FileDatabase instances from paths or existing files.

```APIDOC
## FileDatabase Initialization

### Description
Methods for creating and initializing `FileDatabase` instances from paths or existing files.

### Methods

#### `load_from_path<S>(path: S) -> Result<Self>`

- **Description**: Creates a new `FileDatabase` from the file at the specified `Path` and loads its contents.
- **Parameters**:
  - `path` (S): The path to the file. Must implement `AsRef<Path>`.

#### `load_from_path_or<S>(path: S, data: Data) -> Result<Self>`

- **Description**: Loads a `FileDatabase` at the given `path` or initializes it with the provided `data` if the file does not exist.
- **Parameters**:
  - `path` (S): The path to the file. Must implement `AsRef<Path>`.
  - `data` (Data): The data to initialize the database with if the file is not found.

#### `load_from_path_or_else<S, C>(path: S, closure: C) -> Result<Self>`

- **Description**: Loads a `FileDatabase` at the given `path` or initializes it using the return value of the provided `closure` if the file does not exist.
- **Parameters**:
  - `path` (S): The path to the file. Must implement `AsRef<Path>`.
  - `closure` (C): A closure that returns the initial `Data`.

#### `create_at_path<S>(path: S, data: Data) -> Result<Self>`

- **Description**: Creates a `FileDatabase` at the specified `path`. Initializes with `data` if the file doesn't exist. Contents are not loaded initially, but the frontend is always initialized with `data`.
- **Parameters**:
  - `path` (S): The path to create the file at. Must implement `AsRef<Path>`.
  - `data` (Data): The data to initialize the database with.

#### `from_file(file: File, data: Data) -> Result<Self>`

- **Description**: Creates a new `FileDatabase` from an existing `File` object and initial `data`.
- **Parameters**:
  - `file` (File): An open file handle.
  - `data` (Data): The initial data for the database.

#### `load_from_path_or_default<S>(path: S) -> Result<Self>`

- **Description**: Loads a `FileDatabase` at the given `path` or initializes it with `Data::default()` if the file does not exist. Requires `Data` to implement `Default`.
- **Parameters**:
  - `path` (S): The path to the file. Must implement `AsRef<Path>`.

```

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

### Open FileBackend from Path (Fail if Not Exists)

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/backend/struct.FileBackend.html

Opens a FileBackend for a given path. This function will return an error if the file does not already exist at the specified path.

```rust
pub fn from_path_or_fail<P: AsRef<Path>>(path: P) -> BackendResult<Self>
```

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

### Clone and read database state

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.MemoryDatabase.html

Shows how to use write operations, save changes to the backend, and clone the database for read access.

```rust
use rustbreak::{deser::Ron, FileDatabase};

#[derive(Debug, Serialize, Deserialize, Clone)]
struct Data {
    level: u32,
}

let db = FileDatabase::<Data, Ron>::from_file(file, Data { level: 0 })?;

db.write(|db| {
    db.level = 42;
})?;

db.save()?;

let other_db = db.try_clone()?;

// You can also return from a `.read()`. But don't forget that you cannot return references
// into the structure
let value = other_db.read(|db| db.level)?;
assert_eq!(42, value);
```

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

### Get Default Ron Instance

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/deser/struct.Ron.html

Returns the default value for the Ron type. This is part of the Default trait implementation.

```rust
fn default() -> Ron
```

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

### Borrow Data Mutably from PathDatabase

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.PathDatabase.html

Write lock the database and get mutable access to the underlying Data struct for modifications.

```rust
use rustbreak::{deser::Ron, FileDatabase};

#[derive(Debug, Serialize, Deserialize, Clone)]
struct Data {
    level: u32,
}

let db = FileDatabase::<Data, Ron>::from_file(file, Data { level: 0 })?;

db.write(|db| {
    db.level = 42;
})?;

let mut data = db.borrow_data_mut()?;
data.level = 100;

// The change is reflected when reading back
let value = db.read(|db| db.level)?;
assert_eq!(100, value);
```

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

### Database Core Components

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/index.html

Overview of the primary Database structure and its available persistence backends.

```APIDOC
## Database Struct

### Description
The central Database structure for Rustbreak, serving as the primary interface for data management.

## Persistence Backends

### FileDatabase
A database implementation backed by a file.

### MemoryDatabase
A database implementation backed by a byte vector (`Vec<u8>`).

### MmapDatabase
A database implementation backed by an anonymous memory map.

### PathDatabase
A database implementation backed by a file, utilizing atomic saves for data integrity.
```

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

### Write to PathDatabase

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.PathDatabase.html

Write lock the database and get exclusive write access to the Data container. Panicking in the closure poisons the database.

```rust
use rustbreak::{deser::Ron, FileDatabase};

#[derive(Debug, Serialize, Deserialize, Clone)]
struct Data {
    level: u32,
}

let db = FileDatabase::<Data, Ron>::from_file(file, Data { level: 0 })?;

db.write(|db| {
    db.level = 42;
})?;

// You can also return from a ".read()". But don't forget that you cannot return references
// into the structure
let value = db.read(|db| db.level)?;
assert_eq!(42, value);
```

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

### Database Configuration and Conversion

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.PathDatabase.html

Methods for managing database components, cloning, and data migration.

```APIDOC
## with_deser

### Description
Exchanges the DeSerialization strategy with the new one.

## with_backend

### Description
Exchanges the Backend with the new one. Note: A .save should be called to ensure data is persisted to the new backend.

## convert_data

### Description
Converts from one data type to another, useful for data migration.

### Parameters
- **convert** (FnOnce(Data) -> OutputData) - Closure to transform the data type.
```

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

### Perform Database Write and Read Operations

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.MemoryDatabase.html

Demonstrates how to write to and read from a FileDatabase using closures.

```rust
use rustbreak::{deser::Ron, FileDatabase};

#[derive(Debug, Serialize, Deserialize, Clone)]
struct Data {
    level: u32,
}

let db = FileDatabase::<Data, Ron>::from_file(file, Data { level: 0 })?;

db.write(|db| {
    db.level = 42;
})?;

// You can also return from a `.read()`. But don't forget that you cannot return references
// into the structure
let value = db.read(|db| db.level)?;
assert_eq!(42, value);
```

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

### Database::borrow_data_mut

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.MemoryDatabase.html

Write lock the database and get access to the underlying struct. This gives you access to the underlying struct, allowing you to modify it.

```APIDOC
## Database::borrow_data_mut

### Description
Write lock the database and get access to the underlying struct.
This gives you access to the underlying struct, allowing you to modify it.

### Method
`pub fn borrow_data_mut<'a>(&'a self) -> Result<RwLockWriteGuard<'a, Data>>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
Returns a `RwLockWriteGuard` providing mutable access to the `Data`.

#### Response Example
```rust
// No explicit example provided in the source text, but it would involve
// obtaining the guard and then modifying fields of the Data struct.
```
```

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

### Module backend

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/backend/index.html

Details about the backend implementations for Rustbreak.

```APIDOC
## Module backend

rustbreak

### Summary

The persistence backends of the Database. A file is a `Backend` through the `FileBackend`, so is a `Vec<u8>` with a `MemoryBackend`. Implementing your own Backend should be straightforward. Check the `Backend` documentation for details.

### Structs

#### FileBackend

A backend using a file.

#### MemoryBackend

An in memory backend.

#### MmapStorage

A backend that uses an anonymous mmap.

#### PathBackend

A `Backend` using a file given the path.

### Traits

#### Backend

The Backend Trait.
```

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

### Database::borrow_data

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.MemoryDatabase.html

Read lock the database and get access to the underlying struct. This gives you access to the underlying struct, allowing for simple read only operations on it.

```APIDOC
## Database::borrow_data

### Description
Read lock the database and get access to the underlying struct.
This gives you access to the underlying struct, allowing for simple read only operations on it.

### Method
`pub fn borrow_data<'a>(&'a self) -> Result<RwLockReadGuard<'a, Data>>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use rustbreak::{deser::Ron, FileDatabase};

#[derive(Debug, Serialize, Deserialize, Clone)]
struct Data {
    level: u32,
}

let db = FileDatabase::<Data, Ron>::from_file(file, Data { level: 0 })?;

db.write(|db| {
    db.level = 42;
})?;

let data = db.borrow_data()?;

assert_eq!(42, data.level);
```

### Response
#### Success Response (200)
Returns a `RwLockReadGuard` providing read-only access to the `Data`.

#### Response Example
```rust
// Example response is implicit in the Request Example's return value
```
```

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

### Define Ron Struct for Rusty Object Notation

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/deser/struct.Ron.html

Use this struct to enable RON serialization and deserialization. It requires no specific setup beyond its definition.

```rust
pub struct Ron;
```

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

### Database::read

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.MemoryDatabase.html

Read lock the database and get read access to the Data container. This gives you a read-only lock on the database. You can have as many readers in parallel as you wish.

```APIDOC
## Database::read

### Description
Read lock the database and get read access to the `Data` container.
This gives you a read-only lock on the database. You can have as many readers in parallel as you wish.

### Method
`pub fn read<T, R>(&self, task: T) -> Result<R>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Errors
May return:
  * `error::RustbreakError::Backend`

### Panics
If you panic in the closure, the database is poisoned. This means that any subsequent writes/reads will fail with an `error::RustbreakError::Poison`. You can only recover from this by re-creating the Database Object.
```

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

### Load FileDatabase from Path or Default

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.FileDatabase.html

Loads a FileDatabase from a specified file path. If the file does not exist, it initializes with default data.

```APIDOC
## POST /websites/rs_rustbreak_2_0_0_rustbreak/load_from_path_or_default

### Description
Load `FileDatabase` at `path` or initialise with `Data::default()`.
Create new `FileDatabase` from the file at `Path`, and load the contents. If the file does not exist, initialise with `Data::default`.

### Method
POST

### Endpoint
/websites/rs_rustbreak_2_0_0_rustbreak/load_from_path_or_default

### Parameters
#### Query Parameters
- **path** (string) - Required - The path to the file database.

### Request Body
This endpoint does not require a request body.

### Response
#### Success Response (200)
- **FileDatabase** (object) - The loaded or initialized FileDatabase instance.

#### Response Example
```json
{
  "database_content": "..."
}
```
```

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

### Database Management

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/struct.Database.html

Methods for creating a database from its components and converting it back.

```APIDOC
## Database Management

### Description
Methods for creating a database from its components and converting it back.

### Methods

#### `from_parts(data: Data, backend: Back, deser: DeSer) -> Self`

- **Description**: Creates a database instance from its constituent parts: the data, the backend, and the deserializer.
- **Parameters**:
  - `data` (Data): The initial data for the database.
  - `backend` (Back): The backend storage implementation.
  - `deser` (DeSer): The deserializer implementation.

#### `into_inner(self) -> Result<(Data, Back, DeSer)>`

- **Description**: Consumes the database instance and returns its constituent parts: the data, the backend, and the deserializer.

```

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

### Inspect Error Value in Rust

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.BackendResult.html

Use `inspect_err` to perform a side effect when a `Result` is `Err`, such as logging the error. This example demonstrates inspecting an `io::Error` during file reading.

```rust
use std::{fs, io};

fn read() -> io::Result<String> {
    fs::read_to_string("address.txt")
        .inspect_err(|e| eprintln!("failed to read file: {e}"))
}
```

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

### Get References to Result Values

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.DeSerResult.html

Use `as_ref` to obtain a `Result<&T, &E>` from a `&Result<T, E>`, allowing inspection of values without consuming the original Result. `as_mut` provides mutable references.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

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

### Database Construction and Conversion

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.MemoryDatabase.html

Methods for creating and transforming database instances.

```APIDOC
## POST /database/from_parts

### Description
Creates a new database instance from its constituent parts: data, backend, and deserializer.

### Method
POST

### Endpoint
/database/from_parts

### Request Body
- **data** (Data) - Required - The initial data for the database.
- **backend** (Back) - Required - The backend storage for the database.
- **deser** (DeSer) - Required - The deserialization strategy for the database.

### Response
#### Success Response (200)
- **Database** (Self) - The newly created database instance.

#### Response Example
```json
{
  "database_instance": "..."
}
```
```

```APIDOC
## POST /database/into_inner

### Description
Consumes the database instance and returns its constituent parts: data, backend, and deserializer.

### Method
POST

### Endpoint
/database/into_inner

### Response
#### Success Response (200)
- **Result** (Result<(Data, Back, DeSer)>) - A tuple containing the data, backend, and deserializer.

#### Response Example
```json
{
  "data": { ... },
  "backend": { ... },
  "deser": { ... }
}
```
```

```APIDOC
## POST /database/convert_data

### Description
Converts the data within the database from one type to another using a provided conversion function. This is useful for data migration.

### Method
POST

### Endpoint
/database/convert_data

### Request Body
- **convert** (FnOnce(Data) -> OutputData) - Required - A function that takes the current data and returns the converted data.

### Response
#### Success Response (200)
- **Result** (Result<Database<OutputData, Back, DeSer>>) - A new database instance with the converted data type.

#### Response Example
```json
{
  "converted_database": "..."
}
```
```

```APIDOC
## POST /database/memory

### Description
Creates a new in-memory database instance with the provided initial data.

### Method
POST

### Endpoint
/database/memory

### Request Body
- **data** (Data) - Required - The initial data for the in-memory database.

### Response
#### Success Response (200)
- **Result** (Result<Self>) - The newly created in-memory database instance.

#### Response Example
```json
{
  "memory_database": "..."
}
```
```

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

### Database::write

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.MemoryDatabase.html

Write lock the database and get write access to the Data container. This gives you an exclusive lock on the memory object. Trying to open the database in writing will block if it is currently being written to.

```APIDOC
## Database::write

### Description
Write lock the database and get write access to the `Data` container.
This gives you an exclusive lock on the memory object. Trying to open the database in writing will block if it is currently being written to.

### Method
`pub fn write<T, R>(&self, task: T) -> Result<R>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Panics
If you panic in the closure, the database is poisoned. This means that any subsequent writes/reads will fail with an `error::RustbreakError::Poison`. You can only recover from this by re-creating the Database Object.
If you do not have full control over the code being written, and cannot incur the cost of having a single operation panicking then use `Database::write_safe`.

### Request Example
```rust
use rustbreak::{deser::Ron, FileDatabase};

#[derive(Debug, Serialize, Deserialize, Clone)]
struct Data {
    level: u32,
}

let db = FileDatabase::<Data, Ron>::from_file(file, Data { level: 0 })?;

db.write(|db| {
    db.level = 42;
})?;

// You can also return from a `.read()`. But don't forget that you cannot return references
// into the structure
let value = db.read(|db| db.level)?;
assert_eq!(42, value);
```

### Response
#### Success Response (200)
Returns the result of the closure `R`.

#### Response Example
```rust
// Example response is implicit in the Request Example's return value
```
```

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

### Database::write_safe

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.MemoryDatabase.html

Write lock the database and get write access to the Data container in a safe way. This gives you an exclusive lock on the memory object. Trying to open the database in writing will block if it is currently being written to.

```APIDOC
## Database::write_safe

### Description
Write lock the database and get write access to the `Data` container in a safe way.
This gives you an exclusive lock on the memory object. Trying to open the database in writing will block if it is currently being written to.
This differs to `Database::write` in that a clone of the internal data is made, which is then passed to the closure. Only if the closure doesn’t panic is the internal model updated.
Depending on the size of the database this can be very costly. This is a tradeoff to make for panic safety.
You should read the documentation about this: `UnwindSafe`

### Method
`pub fn write_safe<T>(&self, task: T) -> Result<()>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Panics
When the closure panics, it is caught and a `error::RustbreakError::WritePanic` will be returned.

### Request Example
```rust
use rustbreak::{
    deser::Ron,
    error::RustbreakError,
    FileDatabase,
};

#[derive(Debug, Serialize, Deserialize, Clone)]
struct Data {
    level: u32,
}

let db = FileDatabase::<Data, Ron>::from_file(file, Data { level: 0 })?;

let result = db
    .write_safe(|db| {
        db.level = 42;
        panic!("We panic inside the write code.");
    })
    .expect_err("This should have been caught");

match result {
    RustbreakError::WritePanic => {
        // We can now handle this, in this example we will just ignore it
    }
    e => {
        println!("{:#?}", e);
        // You should always have generic error catching here.
        // This future-proofs your code, and makes your code more robust.
        // In this example this is unreachable though, and to assert that we have this
        // macro here
        unreachable!();
    }
}

// We read it back out again, it has not changed
let value = db.read(|db| db.level)?;
assert_eq!(0, value);
```

### Response
#### Success Response (200)
Returns `Ok(())` if the write operation was successful.

#### Response Example
```rust
// Success is indicated by the absence of an error.
```
```

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

### MmapStorage::with_size()

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/backend/struct.MmapStorage.html

Creates a new MmapStorage instance with a specified initial size.

```APIDOC
## pub fn with_size(len: usize) -> BackendResult<Self>

### Description
Creates new storage with a custom size.

### Method
`pub fn with_size(len: usize)`

### Parameters
#### Path Parameters
- **len** (usize) - Required - The desired initial size of the storage in bytes.

### Returns
A `BackendResult` containing a new `MmapStorage` instance or an error.
```

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

### Into Conversion

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/struct.Database.html

Provides a simple conversion from one type to another using the `From` trait.

```APIDOC
## Into Conversion

### Description
Calls `U::from(self)`. This conversion is determined by the implementation of `From<T> for U`.

### Method
Implicit (via `into()` method)

### Endpoint
N/A (In-memory conversion)

### Parameters
None

### Request Body
None

### Response
N/A (In-memory conversion)

### Response Example
N/A
```

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

### Inspect Ok Value Before Mapping in Rust

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.BackendResult.html

The `inspect` method allows you to perform a side effect, like printing, on the contained value if the `Result` is `Ok`, before further processing. This example parses a string to a u8 and prints the original value.

```rust
let x: u8 = "4"
    .parse::<u8>()
    .inspect(|x| println!("original: {x}"))
    .map(|x| x.pow(3))
    .expect("failed to parse number");
```

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

### Collect Results into a Vector with Checked Subtraction (Underflow)

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.Result.html

This example shows how `collect()` handles errors during iteration. When an `Err` is encountered (due to underflow in this case), the collection stops immediately, and the `Err` is returned. Subsequent elements are not processed.

```rust
let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| 
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));
```

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

### Collect Results into a Vector with Checked Addition

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.Result.html

Use `collect()` on an iterator of `Result`s to gather successful values into a `Vec`. If any element results in an `Err`, the collection stops and returns that `Err`. This example demonstrates checked addition and error handling for overflow.

```rust
let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| 
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));
```

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

### into_ok

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.DeSerResult.html

Returns the contained `Ok` value, but never panics. This is an unstable, nightly-only API.

```APIDOC
## GET /api/into_ok

### Description
Returns the contained `Ok` value, but never panics. Unlike `unwrap`, this method is known to never panic on the result types it is implemented for.

### Method
GET

### Endpoint
/api/into_ok

### Request Example
```json
{
  "example": "fn only_good_news() -> Result<String, !> {\n    Ok(\"this is fine\".into())\n}\n\nlet s: String = only_good_news().into_ok();\nprintln!(\"{s}\");"
}
```

### Response
#### Success Response (200)
- **value** (T) - The contained Ok value.

#### Response Example
```json
{
  "example": "this is fine"
}
```
```

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

### Convert Result<&mut T, &mut E> from Result<T, E> in Rust

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/error/type.BackendResult.html

The `as_deref_mut` method converts a mutable `Result<T, E>` to a `Result<&mut <T as DerefMut>::Target, &mut E>`, allowing mutable borrowing of the inner value. This example modifies a string within the `Ok` variant.

```rust
let mut s = "HELLO".to_string();
let mut x: Result<String, u32> = Ok("hello".to_string());
let y: Result<&mut str, &mut u32> = Ok(&mut s);
assert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);

let mut i = 42;
let mut x: Result<String, u32> = Err(42);
let y: Result<&mut str, &mut u32> = Err(&mut i);
assert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);
```

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

### Database Configuration and Migration

Source: https://docs.rs/rustbreak/2.0.0/rustbreak/type.FileDatabase.html

Methods for managing database components and converting data types.

```APIDOC
## with_deser(deser: T)

### Description
Exchanges the DeSerialization strategy with the new one.

## with_backend(backend: T)

### Description
Exchanges the Backend with the new one. The new backend does not necessarily have the latest data saved to it, so a .save should be called.

## convert_data(convert: C)

### Description
Converts from one data type to another. This method is useful to migrate from one datatype to another.
```
Tokens:
Raw