vortex_buffer/
lib.rs

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

vortex_buffer/
lib.rs
