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