vortex-buffer 0.66.0

A byte buffer implementation for Vortex
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright the Vortex contributors

#![deny(missing_docs)]
// cudarc HostSlice has len and is_empty methods that duplicate BufferMut methods.
#![allow(clippy::same_name_method)]

//! A library for working with custom aligned buffers of sized values.
//!
//! The `vortex-buffer` crate is built around `bytes::Bytes` and therefore supports zero-copy
//! cloning and slicing, but differs in that it can define and maintain a custom alignment.
//!
//! * `Buffer<T>` and `BufferMut<T>` provide immutable and mutable wrappers around `bytes::Bytes`
//!   and `bytes::BytesMut` respectively.
//! * `ByteBuffer` and `ByteBufferMut` are type aliases for `u8` buffers.
//! * `BufferString` is a wrapper around a `ByteBuffer` that enforces utf-8 encoding.
//! * `ConstBuffer<T, const A: usize>` provides similar functionality to `Buffer<T>` except with a
//!   compile-time alignment of `A`.
//! * `buffer!` and `buffer_mut!` macros with the same syntax as the builtin `vec!` macro for
//!   inline construction of buffers.
//! * `BitBuffer` and `BitBufferMut` provide packed bitsets that can be used to store boolean values.
//!
//! You can think of `BufferMut<T>` as similar to a `Vec<T>`, except that any operation that may
//! cause a re-allocation, e.g. extend, will ensure the new allocation maintains the buffer's
//! defined alignment.
//!
//! For example, it's possible to incrementally build a `Buffer<T>` with a 4KB alignment.
//! ```
//! use vortex_buffer::{Alignment, BufferMut};
//!
//! let mut buf = BufferMut::<i32>::empty_aligned(Alignment::new(4096));
//! buf.extend(0i32..1_000);
//! assert_eq!(buf.as_ptr().align_offset(4096), 0)
//! ```
//!
//! ## Comparison
//!
//! | Implementation                   | Zero-copy | Custom Alignment | Typed    |
//! | -------------------------------- | --------- | ---------------- | -------- |
//! | `vortex_buffer::Buffer<T>`       | ✔️        | ✔️               | ✔️       |
//! | `arrow_buffer::ScalarBuffer<T> ` | ✔️        | ❌️️️               | ✔️       |
//! | `bytes::Bytes`                   | ✔️        | ❌️️️               | ❌️️️       |
//! | `Vec<T>`                         | ❌️        | ❌️️               | ✔️       |
//!
//! ## Features
//!
//! The `arrow` feature can be enabled to provide conversion functions to/from Arrow Rust buffers,
//! including `arrow_buffer::Buffer`, `arrow_buffer::ScalarBuffer<T>`, and
//! `arrow_buffer::OffsetBuffer`.

pub use alignment::*;
pub use bit::*;
pub use buffer::*;
pub use buffer_mut::*;
pub use bytes::*;
pub use r#const::*;
pub use string::*;
mod alignment;
#[cfg(feature = "arrow")]
mod arrow;
mod bit;
mod buffer;
mod buffer_mut;
mod bytes;
mod r#const;
mod debug;
mod macros;
#[cfg(feature = "memmap2")]
mod memmap2;
#[cfg(feature = "serde")]
mod serde;
mod string;
/// Trusted-length iterator trait and adapters for safe pre-allocation.
pub mod trusted_len;

/// An immutable buffer of u8.
pub type ByteBuffer = Buffer<u8>;

/// A mutable buffer of u8.
pub type ByteBufferMut = BufferMut<u8>;

/// A const-aligned buffer of u8.
pub type ConstByteBuffer<const A: usize> = ConstBuffer<u8, A>;