mod comment

Signed-off-by: Andrew Duffy <andrew@a10y.dev>

Author: a10y

encodings/bytebool/public-api.lock

@@ -78,13 +78,11 @@ impl vortex_bytebool::ByteBoolData
 
 pub fn vortex_bytebool::ByteBoolData::buffer(&self) -> &vortex_array::buffer::BufferHandle
 
-pub fn vortex_bytebool::ByteBoolData::from_vec<V: core::convert::Into<vortex_array::validity::Validity>>(data: alloc::vec::Vec<bool>, validity: V) -> Self
-
 pub fn vortex_bytebool::ByteBoolData::is_empty(&self) -> bool
 
 pub fn vortex_bytebool::ByteBoolData::len(&self) -> usize
 
-pub fn vortex_bytebool::ByteBoolData::new(buffer: vortex_array::buffer::BufferHandle, validity: vortex_array::validity::Validity) -> Self
+pub fn vortex_bytebool::ByteBoolData::new(buffer: vortex_array::buffer::BufferHandle) -> Self
 
 pub fn vortex_bytebool::ByteBoolData::truthy_bytes(&self) -> &[u8]
 
@@ -94,14 +92,6 @@ impl core::clone::Clone for vortex_bytebool::ByteBoolData
 
 pub fn vortex_bytebool::ByteBoolData::clone(&self) -> vortex_bytebool::ByteBoolData
 
-impl core::convert::From<alloc::vec::Vec<bool>> for vortex_bytebool::ByteBoolData
-
-pub fn vortex_bytebool::ByteBoolData::from(value: alloc::vec::Vec<bool>) -> Self
-
-impl core::convert::From<alloc::vec::Vec<core::option::Option<bool>>> for vortex_bytebool::ByteBoolData
-
-pub fn vortex_bytebool::ByteBoolData::from(value: alloc::vec::Vec<core::option::Option<bool>>) -> Self
-
 impl core::fmt::Debug for vortex_bytebool::ByteBoolData
 
 pub fn vortex_bytebool::ByteBoolData::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result

encodings/bytebool/src/lib.rs

@@ -1,6 +1,45 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
+//! A Vortex encoding that mirrors Arrow's [8-bit Boolean canonical extension type][spec].
+//!
+//! Each element is stored as a single byte. The zero byte represents `false` and any
+//! non-zero byte represents `true`, matching the truthy semantics of the Arrow spec. This
+//! trades 8x the storage of the bit-packed `Bool` layout for cheaper per-byte access —
+//! useful when data arrives from a C ABI or other source that already emits byte-wide
+//! booleans. On execution the array materializes into the standard bit-packed
+//! [`BoolArray`][vortex_array::arrays::BoolArray].
+//!
+//! # Examples
+//!
+//! Any non-zero byte in the backing buffer is treated as `true` when the array executes
+//! to a canonical [`BoolArray`][vortex_array::arrays::BoolArray]:
+//!
+//! ```
+//! # use vortex_array::{IntoArray, LEGACY_SESSION, VortexSessionExecute};
+//! # use vortex_array::arrays::BoolArray;
+//! # use vortex_array::arrays::bool::BoolArrayExt;
+//! # use vortex_array::buffer::BufferHandle;
+//! # use vortex_array::validity::Validity;
+//! # use vortex_buffer::ByteBuffer;
+//! # use vortex_bytebool::ByteBool;
+//! # use vortex_error::VortexResult;
+//! # fn main() -> VortexResult<()> {
+//! # let mut ctx = LEGACY_SESSION.create_execution_ctx();
+//! let handle = BufferHandle::new_host(ByteBuffer::from(vec![0u8, 1, 42, 0]));
+//! let array = ByteBool::new(handle, Validity::NonNullable);
+//!
+//! let bits = array.into_array().execute::<BoolArray>(&mut ctx)?.to_bit_buffer();
+//! assert!(!bits.value(0));
+//! assert!(bits.value(1));
+//! assert!(bits.value(2)); // byte 42 is truthy
+//! assert!(!bits.value(3));
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! [spec]: https://arrow.apache.org/docs/format/CanonicalExtensions.html#bit-boolean
+
 pub use array::*;
 
 mod array;