vortex_buffer/
lib.rs

1#![deny(missing_docs)]
2#![feature(min_specialization)]
3#![feature(trusted_len)]
4
5//! A library for working with custom aligned buffers of sized values.
6//!
7//! The `vortex-buffer` crate is built around `bytes::Bytes` and therefore supports zero-copy
8//! cloning and slicing, but differs in that it can define and maintain a custom alignment.
9//!
10//! * `Buffer<T>` and `BufferMut<T>` provide immutable and mutable wrappers around `bytes::Bytes`
11//!   and `bytes::BytesMut` respectively.
12//! * `ByteBuffer` and `ByteBufferMut` are type aliases for `u8` buffers.
13//! * `BufferString` is a wrapper around a `ByteBuffer` that enforces utf-8 encoding.
14//! * `ConstBuffer<T, const A: usize>` provides similar functionality to `Buffer<T>` except with a
15//!   compile-time alignment of `A`.
16//! * `buffer!` and `buffer_mut!` macros with the same syntax as the builtin `vec!` macro for
17//!   inline construction of buffers.
18//!
19//! You can think of `BufferMut<T>` as similar to a `Vec<T>`, except that any operation that may
20//! cause a re-allocation, e.g. extend, will ensure the new allocation maintains the buffer's
21//! defined alignment.
22//!
23//! For example, it's possible to incrementally build a `Buffer<T>` with a 4KB alignment.
24//! ```
25//! use vortex_buffer::{Alignment, BufferMut};
26//!
27//! let mut buf = BufferMut::<i32>::empty_aligned(Alignment::new(4096));
28//! buf.extend(0i32..1_000);
29//! assert_eq!(buf.as_ptr().align_offset(4096), 0)
30//! ```
31//!
32//! ## Comparison
33//!
34//! | Implementation                   | Zero-copy | Custom Alignment | Typed    |
35//! | -------------------------------- | --------- | ---------------- | -------- |
36//! | `vortex_buffer::Buffer<T>`       | ✔️        | ✔️               | ✔️       |
37//! | `arrow_buffer::ScalarBuffer<T> ` | ✔️        | ❌️️️               | ✔️       |
38//! | `bytes::Bytes`                   | ✔️        | ❌️️️               | ❌️️️       |
39//! | `Vec<T>`                         | ❌️        | ❌️️               | ✔️       |
40//!
41//! ## Features
42//!
43//! The `arrow` feature can be enabled to provide conversion functions to/from Arrow Rust buffers,
44//! including `arrow_buffer::Buffer`, `arrow_buffer::ScalarBuffer<T>`, and
45//! `arrow_buffer::OffsetBuffer`.
46
47pub use alignment::*;
48pub use buffer::*;
49pub use buffer_mut::*;
50pub use bytes::*;
51pub use r#const::*;
52pub use string::*;
53
54mod alignment;
55#[cfg(feature = "arrow")]
56mod arrow;
57mod buffer;
58mod buffer_mut;
59mod bytes;
60#[cfg(feature = "compio")]
61mod compio;
62mod r#const;
63mod debug;
64mod macros;
65#[cfg(feature = "memmap2")]
66mod memmap2;
67mod spec_extend;
68mod string;
69
70/// An immutable buffer of u8.
71pub type ByteBuffer = Buffer<u8>;
72
73/// A mutable buffer of u8.
74pub type ByteBufferMut = BufferMut<u8>;
75
76/// A const-aligned buffer of u8.
77pub type ConstByteBuffer<const A: usize> = ConstBuffer<u8, A>;