Crate vsdb

Source
Expand description

§vsdb

Crates.io Docs.rs License Rust

A std-collection-like database.

This is a simplified version of the original vsdb, retaining only the most practical and stable parts. This crate provides high-level APIs.

To view the change log check here.

§Installation

Add this to your Cargo.toml:

[dependencies]
vsdb = "4.0.1"

§Highlights

  • Most APIs are similar to the corresponding data structures in the standard library:
    • Use Vecx just like Vec.
    • Use Mapx just like HashMap.
    • Use MapxOrd just like BTreeMap.

§Features

  • parity_backend: (Default) Use parity-db as the backend database. Pure Rust implementation.
  • rocks_backend: Use rocksdb as the backend database. C++ implementation.
  • msgpack_codec: (Default) Use rmp-serde as the codec for faster performance.
  • json_codec: Use serde_json as the codec for better compatibility.
  • compress: (Default) Enable compression in the backend database.

§Usage

§Vecx

Vecx is a vector-like data structure that stores values in a contiguous sequence.

use vsdb::Vecx;

let mut vec = Vecx::new();

// Push some values
vec.push(&10);
vec.push(&20);
vec.push(&30);

// Get a value
assert_eq!(vec.get(1), Some(20));

// Iterate over the values
for value in vec.iter() {
    println!("{}", value);
}

// Pop a value
assert_eq!(vec.pop(), Some(30));
assert_eq!(vec.len(), 2);

§Mapx

Mapx is a hash map-like data structure that stores key-value pairs.

use vsdb::Mapx;

let mut map = Mapx::new();

// Insert some key-value pairs
map.insert(&"key1", &"value1");
map.insert(&"key2", &"value2");

// Get a value
assert_eq!(map.get(&"key1"), Some("value1".to_string()));

// Check if a key exists
assert!(map.contains_key(&"key2"));

// Iterate over the key-value pairs
for (key, value) in map.iter() {
    println!("{}: {}", key, value);
}

// Remove a key-value pair
map.remove(&"key1");
assert_eq!(map.len(), 1);

§MapxOrd

MapxOrd is a B-tree map-like data structure that stores key-value pairs in a sorted order.

use vsdb::MapxOrd;

let mut map = MapxOrd::new();

// Insert some key-value pairs
map.insert(&3, &"three");
map.insert(&1, &"one");
map.insert(&2, &"two");

// Get a value
assert_eq!(map.get(&1), Some("one".to_string()));

// Iterate over the key-value pairs in sorted order
for (key, value) in map.iter() {
    println!("{}: {}", key, value);
}

// Get the first and last key-value pairs
assert_eq!(map.first(), Some((1, "one".to_string())));
assert_eq!(map.last(), Some((3, "three".to_string())));

§Important Notes

  • The serialized result of a vsdb instance cannot be used as the basis for distributed consensus. The serialized result only contains meta-information (like storage paths) which may differ across environments. The correct approach is to read the required data and then process the actual content.
  • The instance len is not absolutely reliable and should be regarded as a hint.

§License

This project is licensed under the GPL-3.0 license.

Re-exports§

pub use basic::mapx::Mapx;
pub use basic::mapx_ord::MapxOrd;
pub use basic::mapx_ord_rawkey::MapxOrdRawKey;
pub use basic::mapx_ord_rawvalue::MapxOrdRawValue;
pub use basic::orphan::Orphan;
pub use basic::vecx::Vecx;
pub use basic::vecx_raw::VecxRaw;
pub use common::ende::KeyDe;
pub use common::ende::KeyEn;
pub use common::ende::KeyEnDe;
pub use common::ende::KeyEnDeOrdered;
pub use common::ende::ValueDe;
pub use common::ende::ValueEn;
pub use common::ende::ValueEnDe;
pub use dagmap::DagMapId;
pub use dagmap::raw::DagMapRaw;
pub use dagmap::rawkey::DagMapRawKey;
pub use vsdb_core;

Modules§

basic
Contains basic data structures with typed keys and values.
basic_multi_key
Contains basic data structures with multiple keys.
common
Contains common utilities and traits for encoding and decoding.
dagmap
Contains data structures for directed acyclic graphs (DAGs).

Macros§

parse_int
A macro to parse a byte slice into a specified integer type.
parse_prefix
A macro to parse a byte slice into a Pre type.

Structs§

MapxRaw
A raw, disk-based, key-value map.

Constants§

GB
A constant representing 1 gigabyte in bytes.
KB
A constant representing 1 kilobyte in bytes.
MB
A constant representing 1 megabyte in bytes.
NULL
A constant representing a null or empty byte slice.

Functions§

vsdb_flush
Flushes all data to disk.
vsdb_get_base_dir
Returns the base directory path for VSDB.
vsdb_get_custom_dir
Returns the custom directory path for VSDB.
vsdb_set_base_dir
Sets the base directory path for VSDB manually.

Type Aliases§

RawBytes
A type alias for a vector of bytes, commonly used for raw data.
RawKey
A type alias for a raw key, represented as a vector of bytes.
RawValue
A type alias for a raw value, represented as a vector of bytes.