1use crate::array::print_long_array;
19use crate::builder::BooleanBuilder;
20use crate::iterator::BooleanIter;
21use crate::{Array, ArrayAccessor, ArrayRef, Scalar};
22use arrow_buffer::{BooleanBuffer, Buffer, MutableBuffer, NullBuffer, bit_util};
23use arrow_data::{ArrayData, ArrayDataBuilder};
24use arrow_schema::DataType;
25use std::any::Any;
26use std::sync::Arc;
27
28#[derive(Clone)]
68pub struct BooleanArray {
69 values: BooleanBuffer,
70 nulls: Option<NullBuffer>,
71}
72
73impl std::fmt::Debug for BooleanArray {
74 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
75 write!(f, "BooleanArray\n[\n")?;
76 print_long_array(self, f, |array, index, f| {
77 std::fmt::Debug::fmt(&array.value(index), f)
78 })?;
79 write!(f, "]")
80 }
81}
82
83impl BooleanArray {
84 pub fn new(values: BooleanBuffer, nulls: Option<NullBuffer>) -> Self {
90 if let Some(n) = nulls.as_ref() {
91 assert_eq!(values.len(), n.len());
92 }
93 Self { values, nulls }
94 }
95
96 pub fn new_null(len: usize) -> Self {
98 Self {
99 values: BooleanBuffer::new_unset(len),
100 nulls: Some(NullBuffer::new_null(len)),
101 }
102 }
103
104 pub fn new_scalar(value: bool) -> Scalar<Self> {
106 let values = match value {
107 true => BooleanBuffer::new_set(1),
108 false => BooleanBuffer::new_unset(1),
109 };
110 Scalar::new(Self::new(values, None))
111 }
112
113 pub fn new_from_packed(buffer: impl Into<Buffer>, offset: usize, len: usize) -> Self {
119 BooleanBuffer::new(buffer.into(), offset, len).into()
120 }
121
122 pub fn new_from_u8(value: &[u8]) -> Self {
128 BooleanBuffer::new(Buffer::from(value), 0, value.len() * 8).into()
129 }
130
131 pub fn len(&self) -> usize {
133 self.values.len()
134 }
135
136 pub fn is_empty(&self) -> bool {
138 self.values.is_empty()
139 }
140
141 pub fn slice(&self, offset: usize, length: usize) -> Self {
143 Self {
144 values: self.values.slice(offset, length),
145 nulls: self.nulls.as_ref().map(|n| n.slice(offset, length)),
146 }
147 }
148
149 pub fn builder(capacity: usize) -> BooleanBuilder {
151 BooleanBuilder::with_capacity(capacity)
152 }
153
154 pub fn values(&self) -> &BooleanBuffer {
156 &self.values
157 }
158
159 pub fn true_count(&self) -> usize {
161 match self.nulls() {
162 Some(nulls) => {
163 let null_chunks = nulls.inner().bit_chunks().iter_padded();
164 let value_chunks = self.values().bit_chunks().iter_padded();
165 null_chunks
166 .zip(value_chunks)
167 .map(|(a, b)| (a & b).count_ones() as usize)
168 .sum()
169 }
170 None => self.values().count_set_bits(),
171 }
172 }
173
174 pub fn false_count(&self) -> usize {
176 self.len() - self.null_count() - self.true_count()
177 }
178
179 pub unsafe fn value_unchecked(&self, i: usize) -> bool {
187 unsafe { self.values.value_unchecked(i) }
188 }
189
190 pub fn value(&self, i: usize) -> bool {
198 assert!(
199 i < self.len(),
200 "Trying to access an element at index {} from a BooleanArray of length {}",
201 i,
202 self.len()
203 );
204 unsafe { self.value_unchecked(i) }
207 }
208
209 pub fn take_iter<'a>(
211 &'a self,
212 indexes: impl Iterator<Item = Option<usize>> + 'a,
213 ) -> impl Iterator<Item = Option<bool>> + 'a {
214 indexes.map(|opt_index| opt_index.map(|index| self.value(index)))
215 }
216
217 pub unsafe fn take_iter_unchecked<'a>(
222 &'a self,
223 indexes: impl Iterator<Item = Option<usize>> + 'a,
224 ) -> impl Iterator<Item = Option<bool>> + 'a {
225 indexes.map(|opt_index| opt_index.map(|index| unsafe { self.value_unchecked(index) }))
226 }
227
228 pub fn from_unary<T: ArrayAccessor, F>(left: T, mut op: F) -> Self
239 where
240 F: FnMut(T::Item) -> bool,
241 {
242 let nulls = left.logical_nulls();
243 let values = BooleanBuffer::collect_bool(left.len(), |i| unsafe {
244 op(left.value_unchecked(i))
246 });
247 Self::new(values, nulls)
248 }
249
250 pub fn from_binary<T: ArrayAccessor, S: ArrayAccessor, F>(left: T, right: S, mut op: F) -> Self
267 where
268 F: FnMut(T::Item, S::Item) -> bool,
269 {
270 assert_eq!(left.len(), right.len());
271
272 let nulls = NullBuffer::union(
273 left.logical_nulls().as_ref(),
274 right.logical_nulls().as_ref(),
275 );
276 let values = BooleanBuffer::collect_bool(left.len(), |i| unsafe {
277 op(left.value_unchecked(i), right.value_unchecked(i))
279 });
280 Self::new(values, nulls)
281 }
282
283 pub fn into_parts(self) -> (BooleanBuffer, Option<NullBuffer>) {
285 (self.values, self.nulls)
286 }
287}
288
289impl Array for BooleanArray {
290 fn as_any(&self) -> &dyn Any {
291 self
292 }
293
294 fn to_data(&self) -> ArrayData {
295 self.clone().into()
296 }
297
298 fn into_data(self) -> ArrayData {
299 self.into()
300 }
301
302 fn data_type(&self) -> &DataType {
303 &DataType::Boolean
304 }
305
306 fn slice(&self, offset: usize, length: usize) -> ArrayRef {
307 Arc::new(self.slice(offset, length))
308 }
309
310 fn len(&self) -> usize {
311 self.values.len()
312 }
313
314 fn is_empty(&self) -> bool {
315 self.values.is_empty()
316 }
317
318 fn shrink_to_fit(&mut self) {
319 self.values.shrink_to_fit();
320 if let Some(nulls) = &mut self.nulls {
321 nulls.shrink_to_fit();
322 }
323 }
324
325 fn offset(&self) -> usize {
326 self.values.offset()
327 }
328
329 fn nulls(&self) -> Option<&NullBuffer> {
330 self.nulls.as_ref()
331 }
332
333 fn logical_null_count(&self) -> usize {
334 self.null_count()
335 }
336
337 fn get_buffer_memory_size(&self) -> usize {
338 let mut sum = self.values.inner().capacity();
339 if let Some(x) = &self.nulls {
340 sum += x.buffer().capacity()
341 }
342 sum
343 }
344
345 fn get_array_memory_size(&self) -> usize {
346 std::mem::size_of::<Self>() + self.get_buffer_memory_size()
347 }
348}
349
350impl ArrayAccessor for &BooleanArray {
351 type Item = bool;
352
353 fn value(&self, index: usize) -> Self::Item {
354 BooleanArray::value(self, index)
355 }
356
357 unsafe fn value_unchecked(&self, index: usize) -> Self::Item {
358 unsafe { BooleanArray::value_unchecked(self, index) }
359 }
360}
361
362impl From<Vec<bool>> for BooleanArray {
363 fn from(data: Vec<bool>) -> Self {
364 let mut mut_buf = MutableBuffer::new_null(data.len());
365 {
366 let mut_slice = mut_buf.as_slice_mut();
367 for (i, b) in data.iter().enumerate() {
368 if *b {
369 bit_util::set_bit(mut_slice, i);
370 }
371 }
372 }
373 let array_data = ArrayData::builder(DataType::Boolean)
374 .len(data.len())
375 .add_buffer(mut_buf.into());
376
377 let array_data = unsafe { array_data.build_unchecked() };
378 BooleanArray::from(array_data)
379 }
380}
381
382impl From<Vec<Option<bool>>> for BooleanArray {
383 fn from(data: Vec<Option<bool>>) -> Self {
384 data.iter().collect()
385 }
386}
387
388impl From<ArrayData> for BooleanArray {
389 fn from(data: ArrayData) -> Self {
390 assert_eq!(
391 data.data_type(),
392 &DataType::Boolean,
393 "BooleanArray expected ArrayData with type {} got {}",
394 DataType::Boolean,
395 data.data_type()
396 );
397 assert_eq!(
398 data.buffers().len(),
399 1,
400 "BooleanArray data should contain a single buffer only (values buffer)"
401 );
402 let values = BooleanBuffer::new(data.buffers()[0].clone(), data.offset(), data.len());
403
404 Self {
405 values,
406 nulls: data.nulls().cloned(),
407 }
408 }
409}
410
411impl From<BooleanArray> for ArrayData {
412 fn from(array: BooleanArray) -> Self {
413 let builder = ArrayDataBuilder::new(DataType::Boolean)
414 .len(array.values.len())
415 .offset(array.values.offset())
416 .nulls(array.nulls)
417 .buffers(vec![array.values.into_inner()]);
418
419 unsafe { builder.build_unchecked() }
420 }
421}
422
423impl<'a> IntoIterator for &'a BooleanArray {
424 type Item = Option<bool>;
425 type IntoIter = BooleanIter<'a>;
426
427 fn into_iter(self) -> Self::IntoIter {
428 BooleanIter::<'a>::new(self)
429 }
430}
431
432impl<'a> BooleanArray {
433 pub fn iter(&'a self) -> BooleanIter<'a> {
435 BooleanIter::<'a>::new(self)
436 }
437}
438
439#[derive(Debug)]
448struct BooleanAdapter {
449 pub native: Option<bool>,
451}
452
453impl From<bool> for BooleanAdapter {
454 fn from(value: bool) -> Self {
455 BooleanAdapter {
456 native: Some(value),
457 }
458 }
459}
460
461impl From<&bool> for BooleanAdapter {
462 fn from(value: &bool) -> Self {
463 BooleanAdapter {
464 native: Some(*value),
465 }
466 }
467}
468
469impl From<Option<bool>> for BooleanAdapter {
470 fn from(value: Option<bool>) -> Self {
471 BooleanAdapter { native: value }
472 }
473}
474
475impl From<&Option<bool>> for BooleanAdapter {
476 fn from(value: &Option<bool>) -> Self {
477 BooleanAdapter { native: *value }
478 }
479}
480
481impl<Ptr: Into<BooleanAdapter>> FromIterator<Ptr> for BooleanArray {
482 fn from_iter<I: IntoIterator<Item = Ptr>>(iter: I) -> Self {
483 let iter = iter.into_iter();
484 let capacity = match iter.size_hint() {
485 (lower, Some(upper)) if lower == upper => lower,
486 _ => 0,
487 };
488 let mut builder = BooleanBuilder::with_capacity(capacity);
489 builder.extend(iter.map(|item| item.into().native));
490 builder.finish()
491 }
492}
493
494impl BooleanArray {
495 #[inline]
507 #[allow(
508 private_bounds,
509 reason = "We will expose BooleanAdapter if there is a need"
510 )]
511 pub unsafe fn from_trusted_len_iter<I, P>(iter: I) -> Self
512 where
513 P: Into<BooleanAdapter>,
514 I: ExactSizeIterator<Item = P>,
515 {
516 let data_len = iter.len();
517
518 let num_bytes = bit_util::ceil(data_len, 8);
519 let mut null_builder = MutableBuffer::from_len_zeroed(num_bytes);
520 let mut val_builder = MutableBuffer::from_len_zeroed(num_bytes);
521
522 let data = val_builder.as_slice_mut();
523
524 let null_slice = null_builder.as_slice_mut();
525 iter.enumerate().for_each(|(i, item)| {
526 if let Some(a) = item.into().native {
527 unsafe {
528 bit_util::set_bit_raw(null_slice.as_mut_ptr(), i);
531 if a {
532 bit_util::set_bit_raw(data.as_mut_ptr(), i);
533 }
534 }
535 }
536 });
537
538 let data = unsafe {
539 ArrayData::new_unchecked(
540 DataType::Boolean,
541 data_len,
542 None,
543 Some(null_builder.into()),
544 0,
545 vec![val_builder.into()],
546 vec![],
547 )
548 };
549 BooleanArray::from(data)
550 }
551}
552
553impl From<BooleanBuffer> for BooleanArray {
554 fn from(values: BooleanBuffer) -> Self {
555 Self {
556 values,
557 nulls: None,
558 }
559 }
560}
561
562#[cfg(test)]
563mod tests {
564 use super::*;
565 use arrow_buffer::Buffer;
566 use rand::{Rng, rng};
567
568 #[test]
569 fn test_boolean_fmt_debug() {
570 let arr = BooleanArray::from(vec![true, false, false]);
571 assert_eq!(
572 "BooleanArray\n[\n true,\n false,\n false,\n]",
573 format!("{arr:?}")
574 );
575 }
576
577 #[test]
578 fn test_boolean_with_null_fmt_debug() {
579 let mut builder = BooleanArray::builder(3);
580 builder.append_value(true);
581 builder.append_null();
582 builder.append_value(false);
583 let arr = builder.finish();
584 assert_eq!(
585 "BooleanArray\n[\n true,\n null,\n false,\n]",
586 format!("{arr:?}")
587 );
588 }
589
590 #[test]
591 fn test_boolean_array_from_vec() {
592 let buf = Buffer::from([10_u8]);
593 let arr = BooleanArray::from(vec![false, true, false, true]);
594 assert_eq!(&buf, arr.values().inner());
595 assert_eq!(4, arr.len());
596 assert_eq!(0, arr.offset());
597 assert_eq!(0, arr.null_count());
598 for i in 0..4 {
599 assert!(!arr.is_null(i));
600 assert!(arr.is_valid(i));
601 assert_eq!(i == 1 || i == 3, arr.value(i), "failed at {i}")
602 }
603 }
604
605 #[test]
606 fn test_boolean_array_from_vec_option() {
607 let buf = Buffer::from([10_u8]);
608 let arr = BooleanArray::from(vec![Some(false), Some(true), None, Some(true)]);
609 assert_eq!(&buf, arr.values().inner());
610 assert_eq!(4, arr.len());
611 assert_eq!(0, arr.offset());
612 assert_eq!(1, arr.null_count());
613 for i in 0..4 {
614 if i == 2 {
615 assert!(arr.is_null(i));
616 assert!(!arr.is_valid(i));
617 } else {
618 assert!(!arr.is_null(i));
619 assert!(arr.is_valid(i));
620 assert_eq!(i == 1 || i == 3, arr.value(i), "failed at {i}")
621 }
622 }
623 }
624
625 #[test]
626 fn test_boolean_array_from_packed() {
627 let v = [1_u8, 2_u8, 3_u8];
628 let arr = BooleanArray::new_from_packed(v, 0, 24);
629 assert_eq!(24, arr.len());
630 assert_eq!(0, arr.offset());
631 assert_eq!(0, arr.null_count());
632 assert!(arr.nulls.is_none());
633 for i in 0..24 {
634 assert!(!arr.is_null(i));
635 assert!(arr.is_valid(i));
636 assert_eq!(
637 i == 0 || i == 9 || i == 16 || i == 17,
638 arr.value(i),
639 "failed t {i}"
640 )
641 }
642 }
643
644 #[test]
645 fn test_boolean_array_from_slice_u8() {
646 let v: Vec<u8> = vec![1, 2, 3];
647 let slice = &v[..];
648 let arr = BooleanArray::new_from_u8(slice);
649 assert_eq!(24, arr.len());
650 assert_eq!(0, arr.offset());
651 assert_eq!(0, arr.null_count());
652 assert!(arr.nulls().is_none());
653 for i in 0..24 {
654 assert!(!arr.is_null(i));
655 assert!(arr.is_valid(i));
656 assert_eq!(
657 i == 0 || i == 9 || i == 16 || i == 17,
658 arr.value(i),
659 "failed t {i}"
660 )
661 }
662 }
663
664 #[test]
665 fn test_boolean_array_from_iter() {
666 let v = vec![Some(false), Some(true), Some(false), Some(true)];
667 let arr = v.into_iter().collect::<BooleanArray>();
668 assert_eq!(4, arr.len());
669 assert_eq!(0, arr.offset());
670 assert_eq!(0, arr.null_count());
671 assert!(arr.nulls().is_none());
672 for i in 0..3 {
673 assert!(!arr.is_null(i));
674 assert!(arr.is_valid(i));
675 assert_eq!(i == 1 || i == 3, arr.value(i), "failed at {i}")
676 }
677 }
678
679 #[test]
680 fn test_boolean_array_from_non_nullable_iter() {
681 let v = vec![true, false, true];
682 let arr = v.into_iter().collect::<BooleanArray>();
683 assert_eq!(3, arr.len());
684 assert_eq!(0, arr.offset());
685 assert_eq!(0, arr.null_count());
686 assert!(arr.nulls().is_none());
687
688 assert!(arr.value(0));
689 assert!(!arr.value(1));
690 assert!(arr.value(2));
691 }
692
693 #[test]
694 fn test_boolean_array_from_nullable_iter() {
695 let v = vec![Some(true), None, Some(false), None];
696 let arr = v.into_iter().collect::<BooleanArray>();
697 assert_eq!(4, arr.len());
698 assert_eq!(0, arr.offset());
699 assert_eq!(2, arr.null_count());
700 assert!(arr.nulls().is_some());
701
702 assert!(arr.is_valid(0));
703 assert!(arr.is_null(1));
704 assert!(arr.is_valid(2));
705 assert!(arr.is_null(3));
706
707 assert!(arr.value(0));
708 assert!(!arr.value(2));
709 }
710
711 #[test]
712 fn test_boolean_array_from_nullable_trusted_len_iter() {
713 let v = vec![Some(true), None, Some(false), None];
715 let expected = v.clone().into_iter().collect::<BooleanArray>();
716 let actual = unsafe {
717 BooleanArray::from_trusted_len_iter(v.into_iter())
719 };
720 assert_eq!(expected, actual);
721 }
722
723 #[test]
724 fn test_boolean_array_from_iter_with_larger_upper_bound() {
725 let iterator = vec![Some(true), None, Some(false), None]
728 .into_iter()
729 .filter(Option::is_some);
730 let arr = iterator.collect::<BooleanArray>();
731 assert_eq!(2, arr.len());
732 }
733
734 #[test]
735 fn test_boolean_array_builder() {
736 let buf = Buffer::from([27_u8]);
739 let buf2 = buf.clone();
740 let data = ArrayData::builder(DataType::Boolean)
741 .len(5)
742 .offset(2)
743 .add_buffer(buf)
744 .build()
745 .unwrap();
746 let arr = BooleanArray::from(data);
747 assert_eq!(&buf2, arr.values().inner());
748 assert_eq!(5, arr.len());
749 assert_eq!(2, arr.offset());
750 assert_eq!(0, arr.null_count());
751 for i in 0..3 {
752 assert_eq!(i != 0, arr.value(i), "failed at {i}");
753 }
754 }
755
756 #[test]
757 #[should_panic(
758 expected = "Trying to access an element at index 4 from a BooleanArray of length 3"
759 )]
760 fn test_fixed_size_binary_array_get_value_index_out_of_bound() {
761 let v = vec![Some(true), None, Some(false)];
762 let array = v.into_iter().collect::<BooleanArray>();
763
764 array.value(4);
765 }
766
767 #[test]
768 #[should_panic(expected = "BooleanArray data should contain a single buffer only \
769 (values buffer)")]
770 #[cfg(not(feature = "force_validate"))]
773 fn test_boolean_array_invalid_buffer_len() {
774 let data = unsafe {
775 ArrayData::builder(DataType::Boolean)
776 .len(5)
777 .build_unchecked()
778 };
779 drop(BooleanArray::from(data));
780 }
781
782 #[test]
783 #[should_panic(expected = "BooleanArray expected ArrayData with type Boolean got Int32")]
784 fn test_from_array_data_validation() {
785 let _ = BooleanArray::from(ArrayData::new_empty(&DataType::Int32));
786 }
787
788 #[test]
789 #[cfg_attr(miri, ignore)] fn test_true_false_count() {
791 let mut rng = rng();
792
793 for _ in 0..10 {
794 let d: Vec<_> = (0..2000).map(|_| rng.random_bool(0.5)).collect();
796 let b = BooleanArray::from(d.clone());
797
798 let expected_true = d.iter().filter(|x| **x).count();
799 assert_eq!(b.true_count(), expected_true);
800 assert_eq!(b.false_count(), d.len() - expected_true);
801
802 let d: Vec<_> = (0..2000)
804 .map(|_| rng.random_bool(0.5).then(|| rng.random_bool(0.5)))
805 .collect();
806 let b = BooleanArray::from(d.clone());
807
808 let expected_true = d.iter().filter(|x| matches!(x, Some(true))).count();
809 assert_eq!(b.true_count(), expected_true);
810
811 let expected_false = d.iter().filter(|x| matches!(x, Some(false))).count();
812 assert_eq!(b.false_count(), expected_false);
813 }
814 }
815
816 #[test]
817 fn test_into_parts() {
818 let boolean_array = [Some(true), None, Some(false)]
819 .into_iter()
820 .collect::<BooleanArray>();
821 let (values, nulls) = boolean_array.into_parts();
822 assert_eq!(values.values(), &[0b0000_0001]);
823 assert!(nulls.is_some());
824 assert_eq!(nulls.unwrap().buffer().as_slice(), &[0b0000_0101]);
825
826 let boolean_array =
827 BooleanArray::from(vec![false, false, false, false, false, false, false, true]);
828 let (values, nulls) = boolean_array.into_parts();
829 assert_eq!(values.values(), &[0b1000_0000]);
830 assert!(nulls.is_none());
831 }
832}