heed-traits-0.20.0/.cargo_vcs_info.json0000644000000001510000000000100133210ustar { "git": { "sha1": "9de8469341cafcd5f239317fff85db955103fcd9" }, "path_in_vcs": "heed-traits" }heed-traits-0.20.0/Cargo.toml0000644000000013730000000000100113260ustar # THIS FILE IS AUTOMATICALLY GENERATED BY CARGO # # When uploading crates to the registry Cargo will automatically # "normalize" Cargo.toml files for maximal compatibility # with all versions of Cargo and also rewrite `path` dependencies # to registry (e.g., crates.io) dependencies. # # If you are reading this file be aware that the original Cargo.toml # will likely look very different (and much more reasonable). # See Cargo.toml.orig for the original contents. [package] edition = "2021" name = "heed-traits" version = "0.20.0" authors = ["Kerollmops "] description = "The traits used inside of the fully typed LMDB wrapper, heed" readme = "README.md" license = "MIT" repository = "https://github.com/Kerollmops/heed" [dependencies] heed-traits-0.20.0/Cargo.toml.orig000064400000000000000000000004531046102023000150050ustar 00000000000000[package] name = "heed-traits" version = "0.20.0" authors = ["Kerollmops "] description = "The traits used inside of the fully typed LMDB wrapper, heed" license = "MIT" repository = "https://github.com/Kerollmops/heed" readme = "../README.md" edition = "2021" [dependencies] heed-traits-0.20.0/README.md000064400000000000000000000045161046102023000134010ustar 00000000000000

heed

[![License](https://img.shields.io/badge/license-MIT-green)](#LICENSE) [![Crates.io](https://img.shields.io/crates/v/heed)](https://crates.io/crates/heed) [![Docs](https://docs.rs/heed/badge.svg)](https://docs.rs/heed) [![dependency status](https://deps.rs/repo/github/meilisearch/heed/status.svg)](https://deps.rs/repo/github/meilisearch/heed) [![Build](https://github.com/meilisearch/heed/actions/workflows/rust.yml/badge.svg)](https://github.com/meilisearch/heed/actions/workflows/rust.yml) A Rust-centric [LMDB](https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database) abstraction with minimal overhead. This library enables the storage of various Rust types within LMDB, extending support to include Serde-compatible types. ## Simple Example Usage Here is an example on how to store and read entries into LMDB in a safe and ACID way. For usage examples, see [heed/examples/](heed/examples/). To see more advanced usage techniques go check our [Cookbook](https://docs.rs/heed/latest/heed/cookbook/index.html). ```rust use std::fs; use std::path::Path; use heed::{EnvOpenOptions, Database}; use heed::types::*; fn main() -> Result<(), Box> { let env = unsafe { EnvOpenOptions::new().open("my-first-db")? }; // We open the default unnamed database let mut wtxn = env.write_txn()?; let db: Database> = env.create_database(&mut wtxn, None)?; // We open a write transaction db.put(&mut wtxn, "seven", &7)?; db.put(&mut wtxn, "zero", &0)?; db.put(&mut wtxn, "five", &5)?; db.put(&mut wtxn, "three", &3)?; wtxn.commit()?; // We open a read transaction to check if those values are now available let mut rtxn = env.read_txn()?; let ret = db.get(&rtxn, "zero")?; assert_eq!(ret, Some(0)); let ret = db.get(&rtxn, "five")?; assert_eq!(ret, Some(5)); Ok(()) } ``` ## Building from Source You can use this command to clone the repository: ```bash git clone --recursive https://github.com/meilisearch/heed.git cd heed cargo build ``` However, if you already cloned it and forgot to initialize the submodules, execute the following command: ```bash git submodule update --init ``` heed-traits-0.20.0/src/lib.rs000064400000000000000000000071231046102023000140220ustar 00000000000000#![doc( html_favicon_url = "https://raw.githubusercontent.com/meilisearch/heed/main/assets//heed-pigeon.ico?raw=true" )] #![doc( html_logo_url = "https://raw.githubusercontent.com/meilisearch/heed/main/assets/heed-pigeon-logo.png?raw=true" )] //! Contains the traits used to encode and decode database content. #![warn(missing_docs)] use std::borrow::Cow; use std::cmp::{Ord, Ordering}; use std::error::Error as StdError; /// A boxed `Send + Sync + 'static` error. pub type BoxedError = Box; /// A trait that represents an encoding structure. pub trait BytesEncode<'a> { /// The type to encode. type EItem: ?Sized + 'a; /// Encode the given item as bytes. fn bytes_encode(item: &'a Self::EItem) -> Result, BoxedError>; } /// A trait that represents a decoding structure. pub trait BytesDecode<'a> { /// The type to decode. type DItem: 'a; /// Decode the given bytes as `DItem`. fn bytes_decode(bytes: &'a [u8]) -> Result; } /// Define a custom key comparison function for a database. /// /// The comparison function is called whenever it is necessary to compare a key specified /// by the application with a key currently stored in the database. If no comparison function /// is specified, and no special key flags were specified, the keys are compared lexically, /// with shorter keys collating before longer keys. pub trait Comparator { /// Compares the raw bytes representation of two keys. /// /// # Safety /// /// This function must never crash, this is the reason why it takes raw bytes as parameter, /// to let you define the recovery method you want in case of a decoding error. fn compare(a: &[u8], b: &[u8]) -> Ordering; } /// Define a lexicographic comparator, which is a special case of [`Comparator`]. /// /// Types that implements [`LexicographicComparator`] will automatically have [`Comparator`] /// implemented as well, where the [`Comparator::compare`] is implemented per the definition /// of lexicographic ordering with [`LexicographicComparator::compare_elem`]. /// /// This trait is introduced to support prefix iterators, which implicit assumes that the /// underlying key comparator is lexicographic. pub trait LexicographicComparator: Comparator { /// Compare a single byte; this function is used to implement [`Comparator::compare`] /// by definition of lexicographic ordering. /// /// # Safety /// /// This function must never crash. fn compare_elem(a: u8, b: u8) -> Ordering; /// Advances the given `elem` to its immediate lexicographic successor, if possible. /// Returns `None` if `elem` is already at its maximum value with respect to the /// lexicographic order defined by this comparator. fn successor(elem: u8) -> Option; /// Moves the given `elem` to its immediate lexicographic predecessor, if possible. /// Returns `None` if `elem` is already at its minimum value with respect to the /// lexicographic order defined by this comparator. fn predecessor(elem: u8) -> Option; /// Returns the maximum byte value per the comparator's lexicographic order. fn max_elem() -> u8; /// Returns the minimum byte value per the comparator's lexicographic order. fn min_elem() -> u8; } impl Comparator for C { fn compare(a: &[u8], b: &[u8]) -> Ordering { for idx in 0..std::cmp::min(a.len(), b.len()) { if a[idx] != b[idx] { return C::compare_elem(a[idx], b[idx]); } } Ord::cmp(&a.len(), &b.len()) } }