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//!
20//! You can think of `BufferMut<T>` as similar to a `Vec<T>`, except that any operation that may
21//! cause a re-allocation, e.g. extend, will ensure the new allocation maintains the buffer's
22//! defined alignment.
23//!
24//! For example, it's possible to incrementally build a `Buffer<T>` with a 4KB alignment.
25//! ```
26//! use vortex_buffer::{Alignment, BufferMut};
27//!
28//! let mut buf = BufferMut::<i32>::empty_aligned(Alignment::new(4096));
29//! buf.extend(0i32..1_000);
30//! assert_eq!(buf.as_ptr().align_offset(4096), 0)
31//! ```
32//!
33//! ## Comparison
34//!
35//! | Implementation                   | Zero-copy | Custom Alignment | Typed    |
36//! | -------------------------------- | --------- | ---------------- | -------- |
37//! | `vortex_buffer::Buffer<T>`       | ✔️        | ✔️               | ✔️       |
38//! | `arrow_buffer::ScalarBuffer<T> ` | ✔️        | ❌️️️               | ✔️       |
39//! | `bytes::Bytes`                   | ✔️        | ❌️️️               | ❌️️️       |
40//! | `Vec<T>`                         | ❌️        | ❌️️               | ✔️       |
41//!
42//! ## Features
43//!
44//! The `arrow` feature can be enabled to provide conversion functions to/from Arrow Rust buffers,
45//! including `arrow_buffer::Buffer`, `arrow_buffer::ScalarBuffer<T>`, and
46//! `arrow_buffer::OffsetBuffer`.
47
48pub use alignment::*;
49pub use buffer::*;
50pub use buffer_mut::*;
51pub use bytes::*;
52pub use r#const::*;
53pub use string::*;
54
55mod alignment;
56#[cfg(feature = "arrow")]
57mod arrow;
58mod buffer;
59mod buffer_mut;
60mod bytes;
61#[cfg(feature = "compio")]
62mod compio;
63mod r#const;
64mod debug;
65mod macros;
66#[cfg(feature = "memmap2")]
67mod memmap2;
68mod string;
69mod trusted_len;
70
71/// An immutable buffer of u8.
72pub type ByteBuffer = Buffer<u8>;
73
74/// A mutable buffer of u8.
75pub type ByteBufferMut = BufferMut<u8>;
76
77/// A const-aligned buffer of u8.
78pub type ConstByteBuffer<const A: usize> = ConstBuffer<u8, A>;