vortex_bytebool/lib.rs
1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! A Vortex encoding that mirrors Arrow's [8-bit Boolean canonical extension type][spec].
5//!
6//! Each element is stored as a single byte. The zero byte represents `false` and any
7//! non-zero byte represents `true`, matching the truthy semantics of the Arrow spec. This
8//! trades 8x the storage of the bit-packed `Bool` layout for cheaper per-byte access —
9//! useful when data arrives from a C ABI or other source that already emits byte-wide
10//! booleans. On execution the array materializes into the standard bit-packed
11//! [`BoolArray`][vortex_array::arrays::BoolArray].
12//!
13//! # Examples
14//!
15//! Any non-zero byte in the backing buffer is treated as `true` when the array executes
16//! to a canonical [`BoolArray`][vortex_array::arrays::BoolArray]:
17//!
18//! ```
19//! # use vortex_array::{IntoArray, LEGACY_SESSION, VortexSessionExecute};
20//! # use vortex_array::arrays::BoolArray;
21//! # use vortex_array::arrays::bool::BoolArrayExt;
22//! # use vortex_array::buffer::BufferHandle;
23//! # use vortex_array::validity::Validity;
24//! # use vortex_buffer::ByteBuffer;
25//! # use vortex_bytebool::ByteBool;
26//! # use vortex_error::VortexResult;
27//! # fn main() -> VortexResult<()> {
28//! # let mut ctx = LEGACY_SESSION.create_execution_ctx();
29//! let handle = BufferHandle::new_host(ByteBuffer::from(vec![0u8, 1, 42, 0]));
30//! let array = ByteBool::new(handle, Validity::NonNullable);
31//!
32//! let bits = array.into_array().execute::<BoolArray>(&mut ctx)?.to_bit_buffer();
33//! assert!(!bits.value(0));
34//! assert!(bits.value(1));
35//! assert!(bits.value(2)); // byte 42 is truthy
36//! assert!(!bits.value(3));
37//! # Ok(())
38//! # }
39//! ```
40//!
41//! [spec]: https://arrow.apache.org/docs/format/CanonicalExtensions.html#bit-boolean
42
43pub use array::*;
44
45mod array;
46mod compute;
47mod kernel;
48mod rules;
49mod slice;