1use 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#[derive(Clone)]
34pub struct BooleanArray {
35 values: Bitmap,
37 validity: Option<Bitmap>,
39}
40
41impl BooleanArray {
42 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 #[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 #[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 #[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 #[inline]
103 #[must_use]
104 pub const fn values(&self) -> &Bitmap {
105 &self.values
106 }
107
108 #[inline]
112 #[must_use]
113 pub fn value(&self, index: usize) -> Option<bool> {
114 self.values.get(index)
115 }
116
117 #[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 #[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 Err(_) => 0,
146 },
147 }
148 }
149
150 #[must_use]
152 pub fn false_count(&self) -> usize {
153 self.len() - self.null_count() - self.true_count()
154 }
155
156 #[inline]
158 pub fn iter(&self) -> ArrayIter<&Self> {
159 ArrayIter::new(self)
160 }
161
162 #[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 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 pub fn with_validity(&self, validity: Option<Bitmap>) -> Result<Self> {
195 Self::new(self.values.clone(), validity)
196 }
197
198 #[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 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}