Skip to main content

astrs_data/array/
boolean.rs

1//! [`BooleanArray`] — the bit-packed `Bool` column.
2//!
3//! Unlike every other fixed-width type, `Bool` stores one *bit* per value, so
4//! its values buffer is a [`Bitmap`] rather than a [`crate::ScalarBuffer`].
5//! Both buffers — values and validity — use the same LSB-first numbering, and
6//! both slice by bit offset, so slicing a boolean column stays free.
7//!
8//! ```
9//! use astrs_data::array::{Array, BooleanArray};
10//!
11//! let flags = BooleanArray::from_opt_iter([Some(true), None, Some(false)]);
12//! assert_eq!(flags.len(), 3);
13//! assert_eq!(flags.null_count(), 1);
14//! assert_eq!(flags.get(0), Some(true));
15//! assert_eq!(flags.get(1), None);
16//! assert_eq!(flags.true_count(), 1);
17//! ```
18
19use std::any::Any;
20use std::fmt;
21use std::sync::Arc;
22
23use crate::array::iter::{ArrayAccessor, ArrayIter};
24use crate::array::{
25    Array, ArrayRef, BOOL_TYPE, check_validity, clamp_window, debug_array, validity_eq,
26};
27use crate::buffer::{Bitmap, BitmapBuilder};
28use crate::datatype::DataType;
29use crate::error::{DataError, Result};
30use crate::sealed::Sealed;
31
32/// A bit-packed column of booleans with an optional validity bitmap.
33#[derive(Clone)]
34pub struct BooleanArray {
35    /// One bit per value. Its length *is* the array's length.
36    values: Bitmap,
37    /// Validity, or `None` when every slot is valid.
38    validity: Option<Bitmap>,
39}
40
41impl BooleanArray {
42    /// Builds an array from a values bitmap and an optional validity bitmap.
43    ///
44    /// # Errors
45    ///
46    /// [`DataError::ValidityLengthMismatch`] when the two bitmaps disagree on
47    /// length.
48    ///
49    /// ```
50    /// use astrs_data::array::{Array, BooleanArray};
51    /// use astrs_data::Bitmap;
52    ///
53    /// let values: Bitmap = [true, false, true].into_iter().collect();
54    /// let validity: Bitmap = [true, true, false].into_iter().collect();
55    /// let flags = BooleanArray::new(values, Some(validity))?;
56    /// assert_eq!(flags.null_count(), 1);
57    /// # Ok::<(), astrs_data::DataError>(())
58    /// ```
59    pub fn new(values: Bitmap, validity: Option<Bitmap>) -> Result<Self> {
60        check_validity(validity.as_ref(), values.len())?;
61        Ok(Self { values, validity })
62    }
63
64    /// Builds an array with no nulls.
65    #[must_use]
66    pub fn from_values(values: impl IntoIterator<Item = bool>) -> Self {
67        Self {
68            values: values.into_iter().collect(),
69            validity: None,
70        }
71    }
72
73    /// Builds an array from optional values, null slots holding `false`.
74    #[must_use]
75    pub fn from_opt_iter(values: impl IntoIterator<Item = Option<bool>>) -> Self {
76        let iter = values.into_iter();
77        let (lower, _) = iter.size_hint();
78        let mut slots = BitmapBuilder::with_capacity(lower);
79        let mut validity = BitmapBuilder::with_capacity(lower);
80        let mut any_null = false;
81        for value in iter {
82            slots.append(value.unwrap_or(false));
83            validity.append(value.is_some());
84            any_null |= value.is_none();
85        }
86        Self {
87            values: slots.finish(),
88            validity: any_null.then(|| validity.finish()),
89        }
90    }
91
92    /// An all-null array of `len` slots.
93    #[must_use]
94    pub fn new_null(len: usize) -> Self {
95        Self {
96            values: Bitmap::new_unset(len),
97            validity: Some(Bitmap::new_unset(len)),
98        }
99    }
100
101    /// The values bitmap, including the placeholder in every null slot.
102    #[inline]
103    #[must_use]
104    pub const fn values(&self) -> &Bitmap {
105        &self.values
106    }
107
108    /// The raw slot value at `index`, ignoring validity.
109    ///
110    /// Returns `None` only when `index` is out of range.
111    #[inline]
112    #[must_use]
113    pub fn value(&self, index: usize) -> Option<bool> {
114        self.values.get(index)
115    }
116
117    /// The logical value at `index`: `None` when the slot is null or out of
118    /// range.
119    #[inline]
120    #[must_use]
121    pub fn get(&self, index: usize) -> Option<bool> {
122        if self.is_valid_index(index) {
123            self.values.get(index)
124        } else {
125            None
126        }
127    }
128
129    /// Number of non-null slots holding `true`.
130    ///
131    /// ```
132    /// use astrs_data::array::BooleanArray;
133    ///
134    /// let flags = BooleanArray::from_opt_iter([Some(true), None, Some(true), Some(false)]);
135    /// assert_eq!(flags.true_count(), 2);
136    /// assert_eq!(flags.false_count(), 1);
137    /// ```
138    #[must_use]
139    pub fn true_count(&self) -> usize {
140        match &self.validity {
141            None => self.values.count_set(),
142            Some(validity) => match self.values.and(validity) {
143                Ok(both) => both.count_set(),
144                // Unreachable: the constructor guarantees equal lengths.
145                Err(_) => 0,
146            },
147        }
148    }
149
150    /// Number of non-null slots holding `false`.
151    #[must_use]
152    pub fn false_count(&self) -> usize {
153        self.len() - self.null_count() - self.true_count()
154    }
155
156    /// Iterates over the logical values, `None` for nulls.
157    #[inline]
158    pub fn iter(&self) -> ArrayIter<&Self> {
159        ArrayIter::new(self)
160    }
161
162    /// A zero-copy sub-range, clamped to the array (the crate-wide slicing
163    /// convention).
164    #[must_use]
165    pub fn slice(&self, offset: usize, len: usize) -> Self {
166        let (offset, len) = clamp_window(self.len(), offset, len);
167        Self {
168            values: self.values.slice(offset, len),
169            validity: self.validity.as_ref().map(|bits| bits.slice(offset, len)),
170        }
171    }
172
173    /// Checked [`BooleanArray::slice`].
174    ///
175    /// # Errors
176    ///
177    /// [`DataError::SliceOutOfBounds`] when the window leaves the array.
178    pub fn try_slice(&self, offset: usize, len: usize) -> Result<Self> {
179        if offset.saturating_add(len) > self.len() {
180            return Err(DataError::SliceOutOfBounds {
181                offset,
182                len,
183                available: self.len(),
184            });
185        }
186        Ok(self.slice(offset, len))
187    }
188
189    /// Returns a copy with a different validity bitmap.
190    ///
191    /// # Errors
192    ///
193    /// [`DataError::ValidityLengthMismatch`] when the bitmap length is wrong.
194    pub fn with_validity(&self, validity: Option<Bitmap>) -> Result<Self> {
195        Self::new(self.values.clone(), validity)
196    }
197
198    /// Whether `index` is inside the array and not null.
199    #[inline]
200    fn is_valid_index(&self, index: usize) -> bool {
201        index < self.values.len() && self.validity.as_ref().is_none_or(|bits| bits.value(index))
202    }
203}
204
205impl Sealed for BooleanArray {}
206
207impl Array for BooleanArray {
208    fn as_any(&self) -> &dyn Any {
209        self
210    }
211
212    fn data_type(&self) -> &DataType {
213        &BOOL_TYPE
214    }
215
216    fn len(&self) -> usize {
217        self.values.len()
218    }
219
220    fn validity(&self) -> Option<&Bitmap> {
221        self.validity.as_ref()
222    }
223
224    fn slice(&self, offset: usize, len: usize) -> ArrayRef {
225        Arc::new(Self::slice(self, offset, len))
226    }
227
228    fn buffer_memory_size(&self) -> usize {
229        self.values.buffer().backing_len()
230            + self
231                .validity
232                .as_ref()
233                .map_or(0, |bits| bits.buffer().backing_len())
234    }
235
236    fn equals(&self, other: &dyn Array) -> bool {
237        let Some(other) = other.as_any().downcast_ref::<Self>() else {
238            return false;
239        };
240        if self.len() != other.len()
241            || !validity_eq(self.validity.as_ref(), other.validity.as_ref(), self.len())
242        {
243            return false;
244        }
245        (0..self.len()).all(|index| self.get(index) == other.get(index))
246    }
247}
248
249impl ArrayAccessor for &BooleanArray {
250    type Item = bool;
251
252    #[inline]
253    fn accessor_len(&self) -> usize {
254        self.values.len()
255    }
256
257    #[inline]
258    fn accessor_get(&self, index: usize) -> Option<bool> {
259        BooleanArray::get(self, index)
260    }
261}
262
263impl PartialEq for BooleanArray {
264    #[inline]
265    fn eq(&self, other: &Self) -> bool {
266        self.equals(other)
267    }
268}
269
270impl Eq for BooleanArray {}
271
272impl FromIterator<bool> for BooleanArray {
273    fn from_iter<I: IntoIterator<Item = bool>>(iter: I) -> Self {
274        Self::from_values(iter)
275    }
276}
277
278impl FromIterator<Option<bool>> for BooleanArray {
279    fn from_iter<I: IntoIterator<Item = Option<bool>>>(iter: I) -> Self {
280        Self::from_opt_iter(iter)
281    }
282}
283
284impl<const N: usize> From<[bool; N]> for BooleanArray {
285    fn from(values: [bool; N]) -> Self {
286        Self::from_values(values)
287    }
288}
289
290impl<'a> IntoIterator for &'a BooleanArray {
291    type Item = Option<bool>;
292    type IntoIter = ArrayIter<&'a BooleanArray>;
293
294    fn into_iter(self) -> Self::IntoIter {
295        self.iter()
296    }
297}
298
299impl fmt::Debug for BooleanArray {
300    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
301        debug_array(
302            f,
303            "BooleanArray",
304            &BOOL_TYPE,
305            self.len(),
306            self.null_count(),
307            self.iter(),
308        )
309    }
310}
311
312#[cfg(test)]
313mod tests {
314    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
315
316    use super::*;
317
318    #[test]
319    fn empty_array() {
320        let flags = BooleanArray::from_values([] as [bool; 0]);
321        assert!(flags.is_empty());
322        assert_eq!(flags.null_count(), 0);
323        assert_eq!(flags.true_count(), 0);
324        assert_eq!(flags.false_count(), 0);
325        assert_eq!(flags.get(0), None);
326        assert_eq!(flags.iter().count(), 0);
327        assert_eq!(flags.data_type(), &DataType::Bool);
328    }
329
330    #[test]
331    fn no_null_array() {
332        let flags = BooleanArray::from_values([true, false, true, true]);
333        assert_eq!(flags.len(), 4);
334        assert_eq!(flags.null_count(), 0);
335        assert!(flags.validity().is_none());
336        assert_eq!(flags.true_count(), 3);
337        assert_eq!(flags.false_count(), 1);
338        assert_eq!(flags.get(1), Some(false));
339        assert_eq!(flags.value(1), Some(false));
340        assert_eq!(flags.get(9), None);
341    }
342
343    #[test]
344    fn all_null_array() {
345        let flags = BooleanArray::new_null(5);
346        assert_eq!(flags.len(), 5);
347        assert_eq!(flags.null_count(), 5);
348        assert_eq!(flags.true_count(), 0);
349        assert_eq!(flags.false_count(), 0);
350        for index in 0..5 {
351            assert!(flags.is_null(index));
352            assert_eq!(flags.get(index), None);
353            assert_eq!(flags.value(index), Some(false));
354        }
355    }
356
357    #[test]
358    fn mixed_nulls_and_counts() {
359        let flags = BooleanArray::from_opt_iter([Some(true), None, Some(false), Some(true), None]);
360        assert_eq!(flags.len(), 5);
361        assert_eq!(flags.null_count(), 2);
362        assert_eq!(flags.true_count(), 2);
363        assert_eq!(flags.false_count(), 1);
364        assert_eq!(
365            flags.iter().collect::<Vec<_>>(),
366            vec![Some(true), None, Some(false), Some(true), None]
367        );
368    }
369
370    #[test]
371    fn true_count_ignores_values_under_nulls() {
372        // The null slot carries a `true` bit that must not be counted.
373        let values: Bitmap = [true, true, true].into_iter().collect();
374        let validity: Bitmap = [true, false, true].into_iter().collect();
375        let flags = BooleanArray::new(values, Some(validity)).unwrap();
376        assert_eq!(flags.true_count(), 2);
377        assert_eq!(flags.false_count(), 0);
378        assert_eq!(flags.null_count(), 1);
379    }
380
381    #[test]
382    fn from_opt_iter_without_nulls_skips_the_bitmap() {
383        let flags = BooleanArray::from_opt_iter([Some(true), Some(false)]);
384        assert!(flags.validity().is_none());
385    }
386
387    #[test]
388    fn slicing_handles_bit_offsets() {
389        let source: Vec<Option<bool>> = (0..40)
390            .map(|i| (i % 5 != 0).then_some(i % 2 == 0))
391            .collect();
392        let flags = BooleanArray::from_opt_iter(source.clone());
393        for offset in [0usize, 1, 7, 8, 9, 30] {
394            let window = flags.slice(offset, 5);
395            assert_eq!(window.len(), 5.min(40 - offset));
396            for index in 0..window.len() {
397                assert_eq!(window.get(index), source[offset + index], "offset {offset}");
398            }
399        }
400        assert_eq!(flags.slice(38, 99).len(), 2);
401        assert_eq!(flags.slice(99, 1).len(), 0);
402    }
403
404    #[test]
405    fn try_slice_reports_out_of_range() {
406        let flags = BooleanArray::from_values([true, false, true]);
407        assert_eq!(flags.try_slice(1, 2).unwrap().len(), 2);
408        assert_eq!(
409            flags.try_slice(2, 2).unwrap_err(),
410            DataError::SliceOutOfBounds {
411                offset: 2,
412                len: 2,
413                available: 3
414            }
415        );
416    }
417
418    #[test]
419    fn validity_length_is_checked() {
420        let values: Bitmap = [true, false].into_iter().collect();
421        assert!(BooleanArray::new(values.clone(), None).is_ok());
422        assert!(BooleanArray::new(values.clone(), Some(Bitmap::new_set(2))).is_ok());
423        assert_eq!(
424            BooleanArray::new(values, Some(Bitmap::new_set(3))).unwrap_err(),
425            DataError::ValidityLengthMismatch {
426                array_len: 2,
427                validity_len: 3
428            }
429        );
430    }
431
432    #[test]
433    fn equality_ignores_null_slot_contents() {
434        let a = BooleanArray::from_opt_iter([Some(true), None, Some(false)]);
435        let b = BooleanArray::new(
436            [true, true, false].into_iter().collect(),
437            Some([true, false, true].into_iter().collect()),
438        )
439        .unwrap();
440        assert_eq!(a, b);
441        assert_ne!(a, BooleanArray::from_values([true, true, false]));
442        assert_ne!(a, BooleanArray::from_opt_iter([Some(true), None]));
443    }
444
445    #[test]
446    fn sliced_arrays_compare_by_logical_content() {
447        let full =
448            BooleanArray::from_opt_iter([Some(false), Some(true), None, Some(false), Some(true)]);
449        let window = full.slice(1, 3);
450        assert_eq!(
451            window,
452            BooleanArray::from_opt_iter([Some(true), None, Some(false)])
453        );
454    }
455
456    #[test]
457    fn with_validity_replaces_the_bitmap() {
458        let flags = BooleanArray::from_values([true, true]);
459        let masked = flags
460            .with_validity(Some([true, false].into_iter().collect()))
461            .unwrap();
462        assert_eq!(masked.null_count(), 1);
463        assert_eq!(masked.true_count(), 1);
464        assert!(flags.with_validity(Some(Bitmap::new_set(9))).is_err());
465    }
466
467    #[test]
468    fn conversions_and_collect() {
469        let from_array: BooleanArray = [true, false].into();
470        assert_eq!(from_array.len(), 2);
471        let collected: BooleanArray = (0..4).map(|i| i % 2 == 0).collect();
472        assert_eq!(collected.true_count(), 2);
473        let opt_collected: BooleanArray = [Some(true), None].into_iter().collect();
474        assert_eq!(opt_collected.null_count(), 1);
475        assert_eq!((&collected).into_iter().count(), 4);
476    }
477
478    #[test]
479    fn debug_output_is_readable() {
480        let flags = BooleanArray::from_opt_iter([Some(true), None]);
481        let rendered = format!("{flags:?}");
482        assert!(rendered.contains("Bool"), "{rendered}");
483        assert!(rendered.contains("nulls=1"), "{rendered}");
484        assert!(rendered.contains("true"), "{rendered}");
485    }
486
487    #[test]
488    fn buffer_memory_size_counts_both_bitmaps() {
489        let flags = BooleanArray::from_values([true; 1000]);
490        assert!(flags.buffer_memory_size() >= 125);
491        let masked = flags.with_validity(Some(Bitmap::new_set(1000))).unwrap();
492        assert!(masked.buffer_memory_size() > flags.buffer_memory_size());
493    }
494
495    #[test]
496    fn large_boolean_column() {
497        let flags = BooleanArray::from_values((0..10_000).map(|i| i % 7 == 0));
498        assert_eq!(flags.len(), 10_000);
499        assert_eq!(flags.true_count(), 10_000_usize.div_ceil(7));
500        let window = flags.slice(3, 9_000);
501        assert_eq!(window.len(), 9_000);
502        assert_eq!(window.get(4), flags.get(7));
503    }
504}