pub struct Bitmap { /* private fields */ }Expand description
An immutable, LSB-numbered bit sequence over a shared Buffer.
Used as the validity map of every nullable array and as the value buffer of
crate::array::BooleanArray.
The set-bit count is computed lazily and cached in an atomic, so
count_set is O(len / 64) once and O(1) afterwards, while the type
stays Send + Sync with no locks.
Implementations§
Source§impl Bitmap
impl Bitmap
Sourcepub fn try_new(buffer: Buffer, offset: usize, len: usize) -> Result<Self>
pub fn try_new(buffer: Buffer, offset: usize, len: usize) -> Result<Self>
Wraps a byte window as a bitmap.
§Errors
DataError::BufferTooSmall when the buffer cannot cover
offset + len bits.
use astrs_data::{Bitmap, Buffer};
let bits = Bitmap::try_new(Buffer::from_slice(&[0b1010_1010]), 1, 7)?;
assert_eq!(bits.len(), 7);
assert!(bits.value(0));
assert!(Bitmap::try_new(Buffer::from_slice(&[0]), 0, 9).is_err());Sourcepub fn from_buffer(buffer: Buffer) -> Self
pub fn from_buffer(buffer: Buffer) -> Self
Wraps a byte window, using every bit it holds.
use astrs_data::{Bitmap, Buffer};
assert_eq!(Bitmap::from_buffer(Buffer::from_slice(&[0, 0])).len(), 16);Sourcepub const fn bit_offset(&self) -> usize
pub const fn bit_offset(&self) -> usize
Logical bit offset of the first bit inside the backing buffer.
Sourcepub fn get(&self, index: usize) -> Option<bool>
pub fn get(&self, index: usize) -> Option<bool>
Reads bit index, returning None when out of range.
Sourcepub fn value(&self, index: usize) -> bool
pub fn value(&self, index: usize) -> bool
Reads bit index, treating out-of-range indices as false.
This is the hot accessor used by every array’s is_valid.
Sourcepub fn count_set(&self) -> usize
pub fn count_set(&self) -> usize
Number of set (valid) bits. Computed once, then cached.
use astrs_data::Bitmap;
let bits: Bitmap = [true, false, true].into_iter().collect();
assert_eq!(bits.count_set(), 2);
assert_eq!(bits.count_unset(), 1);Sourcepub fn count_unset(&self) -> usize
pub fn count_unset(&self) -> usize
Number of unset (null) bits.
Sourcepub fn slice(&self, offset: usize, len: usize) -> Self
pub fn slice(&self, offset: usize, len: usize) -> Self
A zero-copy sub-range, clamped to the available range (the crate-wide slicing convention).
use astrs_data::Bitmap;
let bits: Bitmap = (0..20).map(|i| i % 3 == 0).collect();
let window = bits.slice(5, 5);
assert_eq!(window.iter().collect::<Vec<_>>(), vec![false, true, false, false, true]);
assert_eq!(bits.slice(18, 99).len(), 2, "slices clamp");Sourcepub fn iter(&self) -> BitmapIter<'_> ⓘ
pub fn iter(&self) -> BitmapIter<'_> ⓘ
Iterates over the bits, low index first.
Sourcepub fn set_indices(&self) -> impl Iterator<Item = usize> + '_
pub fn set_indices(&self) -> impl Iterator<Item = usize> + '_
Iterates over the indices of the set bits.
use astrs_data::Bitmap;
let bits: Bitmap = [false, true, false, true].into_iter().collect();
assert_eq!(bits.set_indices().collect::<Vec<_>>(), vec![1, 3]);Sourcepub fn unset_indices(&self) -> impl Iterator<Item = usize> + '_
pub fn unset_indices(&self) -> impl Iterator<Item = usize> + '_
Iterates over the indices of the unset (null) bits.
Sourcepub fn to_canonical(&self) -> Self
pub fn to_canonical(&self) -> Self
Copies the bits into a fresh, zero-offset, tightly packed bitmap.
Stage 2 needs this before writing a validity buffer into an IPC body: the wire format has no bit-offset field.
use astrs_data::Bitmap;
let bits: Bitmap = (0..20).map(|i| i % 2 == 0).collect();
let window = bits.slice(3, 9);
let packed = window.to_canonical();
assert_eq!(packed.bit_offset(), 0);
assert_eq!(packed.iter().collect::<Vec<_>>(), window.iter().collect::<Vec<_>>());Sourcepub fn and(&self, other: &Self) -> Result<Self>
pub fn and(&self, other: &Self) -> Result<Self>
Bitwise AND of two equal-length bitmaps.
This is how a parent’s validity is pushed into a child’s: a value is valid only when both maps say so. Operand bit offsets may differ.
§Errors
DataError::BitmapLengthMismatch when the lengths differ.
use astrs_data::Bitmap;
let a: Bitmap = [true, true, false, false].into_iter().collect();
let b: Bitmap = [true, false, true, false].into_iter().collect();
assert_eq!(a.and(&b)?.iter().collect::<Vec<_>>(), vec![true, false, false, false]);Sourcepub fn or(&self, other: &Self) -> Result<Self>
pub fn or(&self, other: &Self) -> Result<Self>
Bitwise OR of two equal-length bitmaps.
§Errors
DataError::BitmapLengthMismatch when the lengths differ.
Sourcepub fn xor(&self, other: &Self) -> Result<Self>
pub fn xor(&self, other: &Self) -> Result<Self>
Bitwise XOR of two equal-length bitmaps.
§Errors
DataError::BitmapLengthMismatch when the lengths differ.
Sourcepub fn not(&self) -> Self
pub fn not(&self) -> Self
Bitwise NOT.
use astrs_data::Bitmap;
let bits: Bitmap = [true, false, true].into_iter().collect();
assert_eq!(bits.not().iter().collect::<Vec<_>>(), vec![false, true, false]);Sourcepub fn intersect(
left: Option<&Self>,
right: Option<&Self>,
) -> Result<Option<Self>>
pub fn intersect( left: Option<&Self>, right: Option<&Self>, ) -> Result<Option<Self>>
Combines two optional validity maps the way nested arrays need.
None means “everything valid”, so the result is None only when both
inputs are None.
§Errors
DataError::BitmapLengthMismatch when both are present with
different lengths.
use astrs_data::Bitmap;
let a: Bitmap = [true, false].into_iter().collect();
assert!(Bitmap::intersect(None, None)?.is_none());
assert_eq!(Bitmap::intersect(Some(&a), None)?, Some(a));Sourcepub fn repeat_each(&self, factor: usize) -> Self
pub fn repeat_each(&self, factor: usize) -> Self
Expands the bitmap so each bit is repeated factor times.
FixedSizeList uses this to push a parent’s validity down onto the
child values it covers.
use astrs_data::Bitmap;
let parent: Bitmap = [true, false].into_iter().collect();
let child = parent.repeat_each(3);
assert_eq!(child.iter().collect::<Vec<_>>(), vec![true, true, true, false, false, false]);