Skip to main content

arrow_array/array/
boolean_array.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
3// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements
4
5use crate::array::print_long_array;
6use crate::builder::{BooleanBufferBuilder, BooleanBuilder};
7use crate::iterator::BooleanIter;
8use crate::{Array, ArrayAccessor, ArrayRef, Scalar};
9use arrow_buffer::{BooleanBuffer, Buffer, MutableBuffer, NullBuffer, bit_util};
10use arrow_data::{ArrayData, ArrayDataBuilder};
11use arrow_schema::DataType;
12use std::any::Any;
13use std::sync::Arc;
14
15/// An array of [boolean values](https://arrow.apache.org/docs/format/Columnar.html#fixed-size-primitive-layout)
16///
17/// # Example: From a Vec
18///
19/// ```
20/// # use arrow_array::{Array, BooleanArray};
21/// let arr: BooleanArray = vec![true, true, false].into();
22/// ```
23///
24/// # Example: From an optional Vec
25///
26/// ```
27/// # use arrow_array::{Array, BooleanArray};
28/// let arr: BooleanArray = vec![Some(true), None, Some(false)].into();
29/// ```
30///
31/// # Example: From an iterator
32///
33/// ```
34/// # use arrow_array::{Array, BooleanArray};
35/// let arr: BooleanArray = (0..5).map(|x| (x % 2 == 0).then(|| x % 3 == 0)).collect();
36/// let values: Vec<_> = arr.iter().collect();
37/// assert_eq!(&values, &[Some(true), None, Some(false), None, Some(false)])
38/// ```
39///
40/// # Example: Using Builder
41///
42/// ```
43/// # use arrow_array::Array;
44/// # use arrow_array::builder::BooleanBuilder;
45/// let mut builder = BooleanBuilder::new();
46/// builder.append_value(true);
47/// builder.append_null();
48/// builder.append_value(false);
49/// let array = builder.finish();
50/// let values: Vec<_> = array.iter().collect();
51/// assert_eq!(&values, &[Some(true), None, Some(false)])
52/// ```
53///
54#[derive(Clone)]
55pub struct BooleanArray {
56    values: BooleanBuffer,
57    nulls: Option<NullBuffer>,
58}
59
60impl std::fmt::Debug for BooleanArray {
61    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
62        write!(f, "BooleanArray\n[\n")?;
63        print_long_array(self, f, &mut |index, f| {
64            std::fmt::Debug::fmt(&self.value(index), f)
65        })?;
66        write!(f, "]")
67    }
68}
69
70impl BooleanArray {
71    /// Create a new [`BooleanArray`] from the provided values and nulls
72    ///
73    /// # Panics
74    ///
75    /// Panics if `values.len() != nulls.len()`
76    pub fn new(values: BooleanBuffer, nulls: Option<NullBuffer>) -> Self {
77        if let Some(n) = nulls.as_ref() {
78            assert_eq!(values.len(), n.len());
79        }
80        Self { values, nulls }
81    }
82
83    /// Create a new [`BooleanArray`] from the provided values and nulls without validation.
84    ///
85    /// # Safety
86    /// - `values.len() == nulls.len()` if `nulls` is `Some`
87    pub unsafe fn new_unchecked(values: BooleanBuffer, nulls: Option<NullBuffer>) -> Self {
88        if cfg!(feature = "force_validate") {
89            return Self::new(values, nulls);
90        }
91        Self { values, nulls }
92    }
93
94    /// Create a new [`BooleanArray`] with length `len` consisting only of nulls
95    pub fn new_null(len: usize) -> Self {
96        Self {
97            values: BooleanBuffer::new_unset(len),
98            nulls: Some(NullBuffer::new_null(len)),
99        }
100    }
101
102    /// Create a new [`Scalar`] from `value`
103    pub fn new_scalar(value: bool) -> Scalar<Self> {
104        let values = match value {
105            true => BooleanBuffer::new_set(1),
106            false => BooleanBuffer::new_unset(1),
107        };
108        Scalar::new(Self::new(values, None))
109    }
110
111    /// Create a new [`BooleanArray`] from a [`Buffer`] specified by `offset` and `len`, the `offset` and `len` in bits
112    /// Logically convert each bit in [`Buffer`] to boolean and use it to build [`BooleanArray`].
113    /// using this method will make the following points self-evident:
114    /// * there is no `null` in the constructed [`BooleanArray`];
115    /// * without considering `buffer.into()`, this method is efficient because there is no need to perform pack and unpack operations on boolean;
116    pub fn new_from_packed(buffer: impl Into<Buffer>, offset: usize, len: usize) -> Self {
117        BooleanBuffer::new(buffer.into(), offset, len).into()
118    }
119
120    /// Create a new [`BooleanArray`] from `&[u8]`
121    /// This method uses `new_from_packed` and constructs a [`Buffer`] using `value`, and offset is set to 0 and len is set to `value.len() * 8`
122    /// using this method will make the following points self-evident:
123    /// * there is no `null` in the constructed [`BooleanArray`];
124    /// * the length of the constructed [`BooleanArray`] is always a multiple of 8;
125    pub fn new_from_u8(value: &[u8]) -> Self {
126        BooleanBuffer::new(Buffer::from(value), 0, value.len() * 8).into()
127    }
128
129    /// Returns the length of this array.
130    pub fn len(&self) -> usize {
131        self.values.len()
132    }
133
134    /// Returns whether this array is empty.
135    pub fn is_empty(&self) -> bool {
136        self.values.is_empty()
137    }
138
139    /// Returns a zero-copy slice of this array with the indicated offset and length.
140    ///
141    /// # Panics
142    /// Panics if `offset + length > self.len()`
143    pub fn slice(&self, offset: usize, length: usize) -> Self {
144        Self {
145            values: self.values.slice(offset, length),
146            nulls: self.nulls.as_ref().map(|n| n.slice(offset, length)),
147        }
148    }
149
150    /// Returns a new boolean array builder
151    pub fn builder(capacity: usize) -> BooleanBuilder {
152        BooleanBuilder::with_capacity(capacity)
153    }
154
155    /// Returns the underlying [`BooleanBuffer`] holding all the values of this array
156    pub fn values(&self) -> &BooleanBuffer {
157        &self.values
158    }
159
160    /// Returns the number of non null, true values within this array.
161    /// If you only need to check if there is at least one true value, consider using `has_true()` which can short-circuit and be more efficient.
162    pub fn true_count(&self) -> usize {
163        match self.nulls() {
164            Some(nulls) => {
165                let null_chunks = nulls.inner().bit_chunks().iter_padded();
166                let value_chunks = self.values().bit_chunks().iter_padded();
167                null_chunks
168                    .zip(value_chunks)
169                    .map(|(a, b)| (a & b).count_ones() as usize)
170                    .sum()
171            }
172            None => self.values().count_set_bits(),
173        }
174    }
175
176    /// Returns the number of non null, false values within this array.
177    /// If you only need to check if there is at least one false value, consider using `has_false()` which can short-circuit and be more efficient.
178    pub fn false_count(&self) -> usize {
179        self.len() - self.null_count() - self.true_count()
180    }
181
182    /// Returns whether there is at least one non-null `true` value in this array.
183    ///
184    /// This is more efficient than `true_count() > 0` because it can short-circuit
185    /// as soon as a `true` value is found, without counting all set bits.
186    ///
187    /// Null values are not counted as `true`. Returns `false` for empty arrays.
188    pub fn has_true(&self) -> bool {
189        match self.nulls() {
190            Some(nulls) => {
191                let null_chunks = nulls.inner().bit_chunks().iter_padded();
192                let value_chunks = self.values().bit_chunks().iter_padded();
193                null_chunks.zip(value_chunks).any(|(n, v)| (n & v) != 0)
194            }
195            None => self.values().has_true(),
196        }
197    }
198
199    /// Returns whether there is at least one non-null `false` value in this array.
200    ///
201    /// This is more efficient than `false_count() > 0` because it can short-circuit
202    /// as soon as a `false` value is found, without counting all set bits.
203    ///
204    /// Null values are not counted as `false`. Returns `false` for empty arrays.
205    pub fn has_false(&self) -> bool {
206        match self.nulls() {
207            Some(nulls) => {
208                let null_chunks = nulls.inner().bit_chunks().iter_padded();
209                let value_chunks = self.values().bit_chunks().iter_padded();
210                null_chunks.zip(value_chunks).any(|(n, v)| (n & !v) != 0)
211            }
212            None => self.values().has_false(),
213        }
214    }
215
216    /// Returns the boolean value at index `i`.
217    ///
218    /// Note: This method does not check for nulls and the value is arbitrary
219    /// if [`is_null`](Self::is_null) returns true for the index.
220    ///
221    /// # Safety
222    /// This doesn't check bounds, the caller must ensure that index < self.len()
223    pub unsafe fn value_unchecked(&self, i: usize) -> bool {
224        unsafe { self.values.value_unchecked(i) }
225    }
226
227    /// Returns the boolean value at index `i`.
228    ///
229    /// Note: This method does not check for nulls and the value is arbitrary
230    /// if [`is_null`](Self::is_null) returns true for the index.
231    ///
232    /// # Panics
233    /// Panics if index `i` is out of bounds
234    pub fn value(&self, i: usize) -> bool {
235        assert!(
236            i < self.len(),
237            "Trying to access an element at index {} from a BooleanArray of length {}",
238            i,
239            self.len()
240        );
241        // Safety:
242        // `i < self.len()
243        unsafe { self.value_unchecked(i) }
244    }
245
246    /// Returns an iterator that returns the values of `array.value(i)` for an iterator with each element `i`
247    pub fn take_iter<'a>(
248        &'a self,
249        indexes: impl Iterator<Item = Option<usize>> + 'a,
250    ) -> impl Iterator<Item = Option<bool>> + 'a {
251        indexes.map(|opt_index| opt_index.map(|index| self.value(index)))
252    }
253
254    /// Returns an iterator that returns the values of `array.value(i)` for an iterator with each element `i`
255    /// # Safety
256    ///
257    /// caller must ensure that the offsets in the iterator are less than the array len()
258    pub unsafe fn take_iter_unchecked<'a>(
259        &'a self,
260        indexes: impl Iterator<Item = Option<usize>> + 'a,
261    ) -> impl Iterator<Item = Option<bool>> + 'a {
262        indexes.map(|opt_index| opt_index.map(|index| unsafe { self.value_unchecked(index) }))
263    }
264
265    /// Create a [`BooleanArray`] by evaluating the operation for
266    /// each element of the provided array
267    ///
268    /// ```
269    /// # use arrow_array::{BooleanArray, Int32Array};
270    ///
271    /// let array = Int32Array::from(vec![1, 2, 3, 4, 5]);
272    /// let r = BooleanArray::from_unary(&array, |x| x > 2);
273    /// assert_eq!(&r, &BooleanArray::from(vec![false, false, true, true, true]));
274    /// ```
275    pub fn from_unary<T: ArrayAccessor, F>(left: T, mut op: F) -> Self
276    where
277        F: FnMut(T::Item) -> bool,
278    {
279        let nulls = left.logical_nulls();
280        let values = BooleanBuffer::collect_bool(left.len(), |i| unsafe {
281            // SAFETY: i in range 0..len
282            op(left.value_unchecked(i))
283        });
284        Self::new(values, nulls)
285    }
286
287    /// Create a [`BooleanArray`] by evaluating the binary operation for
288    /// each element of the provided arrays
289    ///
290    /// ```
291    /// # use arrow_array::{BooleanArray, Int32Array};
292    ///
293    /// let a = Int32Array::from(vec![1, 2, 3, 4, 5]);
294    /// let b = Int32Array::from(vec![1, 2, 0, 2, 5]);
295    /// let r = BooleanArray::from_binary(&a, &b, |a, b| a == b);
296    /// assert_eq!(&r, &BooleanArray::from(vec![true, true, false, false, true]));
297    /// ```
298    ///
299    /// # Panics
300    ///
301    /// This function panics if left and right are not the same length
302    ///
303    pub fn from_binary<T: ArrayAccessor, S: ArrayAccessor, F>(left: T, right: S, mut op: F) -> Self
304    where
305        F: FnMut(T::Item, S::Item) -> bool,
306    {
307        assert_eq!(left.len(), right.len());
308
309        let nulls = NullBuffer::union(
310            left.logical_nulls().as_ref(),
311            right.logical_nulls().as_ref(),
312        );
313        let values = BooleanBuffer::collect_bool(left.len(), |i| unsafe {
314            // SAFETY: i in range 0..len
315            op(left.value_unchecked(i), right.value_unchecked(i))
316        });
317        Self::new(values, nulls)
318    }
319
320    /// Apply a bitwise operation to this array's values using u64 operations,
321    /// returning a new [`BooleanArray`].
322    ///
323    /// The null buffer is preserved unchanged.
324    ///
325    /// See [`BooleanBuffer::from_bitwise_unary_op`] for details on the operation.
326    ///
327    /// # Example
328    ///
329    /// ```
330    /// # use arrow_array::BooleanArray;
331    /// let array = BooleanArray::from(vec![true, false, true]);
332    /// let result = array.bitwise_unary(|x| !x);
333    /// assert_eq!(result, BooleanArray::from(vec![false, true, false]));
334    /// ```
335    pub fn bitwise_unary<F>(&self, op: F) -> BooleanArray
336    where
337        F: FnMut(u64) -> u64,
338    {
339        let values = BooleanBuffer::from_bitwise_unary_op(
340            self.values.values(),
341            self.values.offset(),
342            self.values.len(),
343            op,
344        );
345        BooleanArray::new(values, self.nulls.clone())
346    }
347
348    /// Try to apply a bitwise operation to this array's values in place using
349    /// u64 operations.
350    ///
351    /// If the underlying buffer is uniquely owned, the operation is applied
352    /// in place and `Ok` is returned. If the buffer is shared, `Err(self)` is
353    /// returned so the caller can fall back to [`bitwise_unary`](Self::bitwise_unary).
354    ///
355    /// The null buffer is preserved unchanged.
356    ///
357    /// # Example
358    ///
359    /// ```
360    /// # use arrow_array::BooleanArray;
361    /// let array = BooleanArray::from(vec![true, false, true]);
362    /// let result = array.bitwise_unary_mut(|x| !x).unwrap();
363    /// assert_eq!(result, BooleanArray::from(vec![false, true, false]));
364    /// ```
365    pub fn bitwise_unary_mut<F>(self, op: F) -> Result<BooleanArray, BooleanArray>
366    where
367        F: FnMut(u64) -> u64,
368    {
369        self.try_bitwise_unary_in_place(op)
370            .map_err(|(array, _op)| array)
371    }
372
373    /// Apply a bitwise operation to this array's values in place if the buffer
374    /// is uniquely owned, or clone and apply if shared.
375    ///
376    /// This is a convenience wrapper around [`bitwise_unary_mut`](Self::bitwise_unary_mut)
377    /// that falls back to [`bitwise_unary`](Self::bitwise_unary) when the buffer is shared.
378    ///
379    /// The null buffer is preserved unchanged.
380    ///
381    /// # Example
382    ///
383    /// ```
384    /// # use arrow_array::BooleanArray;
385    /// let array = BooleanArray::from(vec![true, false, true]);
386    /// let result = array.bitwise_unary_mut_or_clone(|x| !x);
387    /// assert_eq!(result, BooleanArray::from(vec![false, true, false]));
388    /// ```
389    pub fn bitwise_unary_mut_or_clone<F>(self, op: F) -> BooleanArray
390    where
391        F: FnMut(u64) -> u64,
392    {
393        match self.try_bitwise_unary_in_place(op) {
394            Ok(array) => array,
395            Err((array, op)) => array.bitwise_unary(op),
396        }
397    }
398
399    /// Try to apply a unary op in place. Returns `op` back on failure so
400    /// callers can fall back to an allocating path without requiring `F: Clone`.
401    fn try_bitwise_unary_in_place<F>(self, op: F) -> Result<BooleanArray, (BooleanArray, F)>
402    where
403        F: FnMut(u64) -> u64,
404    {
405        let (values, nulls) = self.into_parts();
406        let offset = values.offset();
407        let len = values.len();
408        let buffer = values.into_inner();
409        match buffer.into_mutable() {
410            Ok(mut buf) => {
411                bit_util::apply_bitwise_unary_op(buf.as_slice_mut(), offset, len, op);
412                let values = BooleanBuffer::new(buf.into(), offset, len);
413                Ok(BooleanArray::new(values, nulls))
414            }
415            Err(buffer) => {
416                let values = BooleanBuffer::new(buffer, offset, len);
417                Err((BooleanArray::new(values, nulls), op))
418            }
419        }
420    }
421
422    /// Apply a bitwise binary operation to this array and `rhs` using u64
423    /// operations, returning a new [`BooleanArray`].
424    ///
425    /// Null buffers are unioned: the result is null where either input is null.
426    ///
427    /// See [`BooleanBuffer::from_bitwise_binary_op`] for details on the operation.
428    ///
429    /// # Panics
430    ///
431    /// Panics if `self` and `rhs` have different lengths.
432    ///
433    /// # Example
434    ///
435    /// ```
436    /// # use arrow_array::BooleanArray;
437    /// let a = BooleanArray::from(vec![true, false, true, true]);
438    /// let b = BooleanArray::from(vec![true, true, false, true]);
439    /// let result = a.bitwise_bin_op(&b, |a, b| a & b);
440    /// assert_eq!(result, BooleanArray::from(vec![true, false, false, true]));
441    /// ```
442    pub fn bitwise_bin_op<F>(&self, rhs: &BooleanArray, op: F) -> BooleanArray
443    where
444        F: FnMut(u64, u64) -> u64,
445    {
446        assert_eq!(self.len(), rhs.len());
447        let nulls = NullBuffer::union(self.nulls(), rhs.nulls());
448        let values = BooleanBuffer::from_bitwise_binary_op(
449            self.values.values(),
450            self.values.offset(),
451            rhs.values.values(),
452            rhs.values.offset(),
453            self.values.len(),
454            op,
455        );
456        BooleanArray::new(values, nulls)
457    }
458
459    /// Try to apply a bitwise binary operation to this array and `rhs` in
460    /// place using u64 operations.
461    ///
462    /// If this array's underlying buffer is uniquely owned, the operation is
463    /// applied in place and `Ok` is returned. If the buffer is shared,
464    /// `Err(self)` is returned so the caller can fall back to
465    /// [`bitwise_bin_op`](Self::bitwise_bin_op).
466    ///
467    /// Null buffers are unioned: the result is null where either input is null.
468    ///
469    /// # Panics
470    ///
471    /// Panics if `self` and `rhs` have different lengths.
472    ///
473    /// # Example
474    ///
475    /// ```
476    /// # use arrow_array::BooleanArray;
477    /// let a = BooleanArray::from(vec![true, false, true, true]);
478    /// let b = BooleanArray::from(vec![true, true, false, true]);
479    /// let result = a.bitwise_bin_op_mut(&b, |a, b| a & b).unwrap();
480    /// assert_eq!(result, BooleanArray::from(vec![true, false, false, true]));
481    /// ```
482    pub fn bitwise_bin_op_mut<F>(
483        self,
484        rhs: &BooleanArray,
485        op: F,
486    ) -> Result<BooleanArray, BooleanArray>
487    where
488        F: FnMut(u64, u64) -> u64,
489    {
490        self.try_bitwise_bin_op_in_place(rhs, op)
491            .map_err(|(array, _op)| array)
492    }
493
494    /// Apply a bitwise binary operation to this array and `rhs` in place if the
495    /// buffer is uniquely owned, or clone and apply if shared.
496    ///
497    /// This is a convenience wrapper around [`bitwise_bin_op_mut`](Self::bitwise_bin_op_mut)
498    /// that falls back to [`bitwise_bin_op`](Self::bitwise_bin_op) when the buffer is shared.
499    ///
500    /// Null buffers are unioned: the result is null where either input is null.
501    ///
502    /// # Panics
503    ///
504    /// Panics if `self` and `rhs` have different lengths.
505    ///
506    /// # Example
507    ///
508    /// ```
509    /// # use arrow_array::BooleanArray;
510    /// let a = BooleanArray::from(vec![true, false, true, true]);
511    /// let b = BooleanArray::from(vec![true, true, false, true]);
512    /// let result = a.bitwise_bin_op_mut_or_clone(&b, |a, b| a & b);
513    /// assert_eq!(result, BooleanArray::from(vec![true, false, false, true]));
514    /// ```
515    pub fn bitwise_bin_op_mut_or_clone<F>(self, rhs: &BooleanArray, op: F) -> BooleanArray
516    where
517        F: FnMut(u64, u64) -> u64,
518    {
519        match self.try_bitwise_bin_op_in_place(rhs, op) {
520            Ok(array) => array,
521            Err((array, op)) => array.bitwise_bin_op(rhs, op),
522        }
523    }
524
525    /// Try to apply a binary op in place. Returns `op` back on failure so
526    /// callers can fall back to an allocating path without requiring `F: Clone`.
527    fn try_bitwise_bin_op_in_place<F>(
528        self,
529        rhs: &BooleanArray,
530        op: F,
531    ) -> Result<BooleanArray, (BooleanArray, F)>
532    where
533        F: FnMut(u64, u64) -> u64,
534    {
535        assert_eq!(self.len(), rhs.len());
536        let (values, nulls) = self.into_parts();
537        let offset = values.offset();
538        let len = values.len();
539        let buffer = values.into_inner();
540        match buffer.into_mutable() {
541            Ok(mut buf) => {
542                bit_util::apply_bitwise_binary_op(
543                    buf.as_slice_mut(),
544                    offset,
545                    rhs.values.inner(),
546                    rhs.values.offset(),
547                    len,
548                    op,
549                );
550                // Defer null union to the success path so the Err path returns
551                // self's original nulls, avoiding a redundant union in callers
552                // that fall back to bitwise_bin_op.
553                let nulls = NullBuffer::union(nulls.as_ref(), rhs.nulls());
554                let values = BooleanBuffer::new(buf.into(), offset, len);
555                Ok(BooleanArray::new(values, nulls))
556            }
557            Err(buffer) => {
558                let values = BooleanBuffer::new(buffer, offset, len);
559                Err((BooleanArray::new(values, nulls), op))
560            }
561        }
562    }
563
564    /// Returns a new [`BooleanArray`] of the same length where only the first
565    /// `n` non-null `true` positions remain `true`; any `true` positions
566    /// beyond the first `n` are replaced with `false`. The null buffer is
567    /// preserved unchanged.
568    ///
569    /// If this array has at most `n` non-null `true` values, `self` is
570    /// returned unchanged.
571    ///
572    /// # Example
573    ///
574    /// ```
575    /// # use arrow_array::BooleanArray;
576    /// let a = BooleanArray::from(vec![true, false, true, true, false, true]);
577    /// // Keep only the first 2 `true` positions; later trues become false.
578    /// let r = a.take_n_true(2);
579    /// assert_eq!(r, BooleanArray::from(vec![true, false, true, false, false, false]));
580    /// ```
581    pub fn take_n_true(self, n: usize) -> BooleanArray {
582        let len = self.len();
583        // `set_indices` scans 64 bits at a time via `trailing_zeros`, so locating
584        // the first set bit beyond the retained prefix is cheaper than visiting
585        // every bit. When a null buffer is present, skip set bits whose
586        // corresponding entry is null so only non-null trues count toward `n`
587        // (matching `true_count` semantics).
588        let mut iter = self.values.set_indices();
589        let end = match self.nulls.as_ref() {
590            Some(nulls) => iter.filter(|&i| nulls.is_valid(i)).nth(n),
591            None => iter.nth(n),
592        };
593        let Some(end) = end else {
594            return self;
595        };
596
597        let bit_offset = self.values.offset();
598        let inner_buf = self.values.into_inner();
599
600        match inner_buf.into_mutable() {
601            Ok(mut mutable_buffer) => {
602                // Unique ownership: zero trailing bits in place.
603                let actual_end = bit_offset + end;
604                let raw_bytes = mutable_buffer.as_slice_mut();
605                let byte_idx = actual_end / 8;
606                let bits_to_keep = actual_end % 8;
607                if bits_to_keep == 0 {
608                    raw_bytes[byte_idx..].fill(0);
609                } else {
610                    raw_bytes[byte_idx] &= (1_u8 << bits_to_keep) - 1;
611                    raw_bytes[byte_idx + 1..].fill(0);
612                }
613                BooleanArray::new(
614                    BooleanBuffer::new(mutable_buffer.into(), bit_offset, len),
615                    self.nulls,
616                )
617            }
618            Err(buf) => {
619                // Shared buffer: copy the retained prefix then pad with false.
620                let mut builder = BooleanBufferBuilder::new(len);
621                builder.append_buffer(&BooleanBuffer::new(buf, bit_offset, end));
622                builder.append_n(len - end, false);
623                BooleanArray::new(builder.finish(), self.nulls)
624            }
625        }
626    }
627
628    /// Deconstruct this array into its constituent parts
629    pub fn into_parts(self) -> (BooleanBuffer, Option<NullBuffer>) {
630        (self.values, self.nulls)
631    }
632}
633
634/// SAFETY: Correctly implements the contract of Arrow Arrays
635unsafe impl Array for BooleanArray {
636    fn as_any(&self) -> &dyn Any {
637        self
638    }
639
640    fn to_data(&self) -> ArrayData {
641        self.clone().into()
642    }
643
644    fn into_data(self) -> ArrayData {
645        self.into()
646    }
647
648    fn data_type(&self) -> &DataType {
649        &DataType::Boolean
650    }
651
652    fn slice(&self, offset: usize, length: usize) -> ArrayRef {
653        Arc::new(self.slice(offset, length))
654    }
655
656    fn len(&self) -> usize {
657        self.values.len()
658    }
659
660    fn is_empty(&self) -> bool {
661        self.values.is_empty()
662    }
663
664    fn shrink_to_fit(&mut self) {
665        self.values.shrink_to_fit();
666        if let Some(nulls) = &mut self.nulls {
667            nulls.shrink_to_fit();
668        }
669    }
670
671    fn offset(&self) -> usize {
672        self.values.offset()
673    }
674
675    fn nulls(&self) -> Option<&NullBuffer> {
676        self.nulls.as_ref()
677    }
678
679    fn logical_null_count(&self) -> usize {
680        self.null_count()
681    }
682
683    fn get_buffer_memory_size(&self) -> usize {
684        let mut sum = self.values.inner().capacity();
685        if let Some(x) = &self.nulls {
686            sum += x.buffer().capacity()
687        }
688        sum
689    }
690
691    fn get_array_memory_size(&self) -> usize {
692        std::mem::size_of::<Self>() + self.get_buffer_memory_size()
693    }
694
695    #[cfg(feature = "pool")]
696    fn claim(&self, pool: &dyn arrow_buffer::MemoryPool) {
697        self.values.claim(pool);
698        if let Some(nulls) = &self.nulls {
699            nulls.claim(pool);
700        }
701    }
702}
703
704impl ArrayAccessor for &BooleanArray {
705    type Item = bool;
706
707    fn value(&self, index: usize) -> Self::Item {
708        BooleanArray::value(self, index)
709    }
710
711    unsafe fn value_unchecked(&self, index: usize) -> Self::Item {
712        unsafe { BooleanArray::value_unchecked(self, index) }
713    }
714}
715
716impl From<Vec<bool>> for BooleanArray {
717    fn from(data: Vec<bool>) -> Self {
718        let mut mut_buf = MutableBuffer::new_null(data.len());
719        {
720            let mut_slice = mut_buf.as_slice_mut();
721            for (i, b) in data.iter().enumerate() {
722                if *b {
723                    bit_util::set_bit(mut_slice, i);
724                }
725            }
726        }
727        let array_data = ArrayData::builder(DataType::Boolean)
728            .len(data.len())
729            .add_buffer(mut_buf.into());
730
731        let array_data = unsafe { array_data.build_unchecked() };
732        BooleanArray::from(array_data)
733    }
734}
735
736impl From<Vec<Option<bool>>> for BooleanArray {
737    fn from(data: Vec<Option<bool>>) -> Self {
738        data.iter().collect()
739    }
740}
741
742impl From<ArrayData> for BooleanArray {
743    fn from(data: ArrayData) -> Self {
744        let (data_type, len, nulls, offset, mut buffers, _child_data) = data.into_parts();
745        assert_eq!(
746            data_type,
747            DataType::Boolean,
748            "BooleanArray expected ArrayData with type Boolean got {data_type:?}",
749        );
750        assert_eq!(
751            buffers.len(),
752            1,
753            "BooleanArray data should contain a single buffer only (values buffer)"
754        );
755        let buffer = buffers.pop().expect("checked above");
756        let values = BooleanBuffer::new(buffer, offset, len);
757
758        Self { values, nulls }
759    }
760}
761
762impl From<BooleanArray> for ArrayData {
763    fn from(array: BooleanArray) -> Self {
764        let builder = ArrayDataBuilder::new(DataType::Boolean)
765            .len(array.values.len())
766            .offset(array.values.offset())
767            .nulls(array.nulls)
768            .buffers(vec![array.values.into_inner()]);
769
770        unsafe { builder.build_unchecked() }
771    }
772}
773
774impl<'a> IntoIterator for &'a BooleanArray {
775    type Item = Option<bool>;
776    type IntoIter = BooleanIter<'a>;
777
778    fn into_iter(self) -> Self::IntoIter {
779        BooleanIter::<'a>::new(self)
780    }
781}
782
783impl<'a> BooleanArray {
784    /// constructs a new iterator
785    pub fn iter(&'a self) -> BooleanIter<'a> {
786        BooleanIter::<'a>::new(self)
787    }
788}
789
790/// An optional boolean value
791///
792/// This struct is used as an adapter when creating `BooleanArray` from an iterator.
793/// `FromIterator` for `BooleanArray` takes an iterator where the elements can be `into`
794/// this struct. So once implementing `From` or `Into` trait for a type, an iterator of
795/// the type can be collected to `BooleanArray`.
796///
797/// See also [NativeAdapter](crate::array::NativeAdapter).
798#[derive(Debug)]
799struct BooleanAdapter {
800    /// Corresponding Rust native type if available
801    pub native: Option<bool>,
802}
803
804impl From<bool> for BooleanAdapter {
805    fn from(value: bool) -> Self {
806        BooleanAdapter {
807            native: Some(value),
808        }
809    }
810}
811
812impl From<&bool> for BooleanAdapter {
813    fn from(value: &bool) -> Self {
814        BooleanAdapter {
815            native: Some(*value),
816        }
817    }
818}
819
820impl From<Option<bool>> for BooleanAdapter {
821    fn from(value: Option<bool>) -> Self {
822        BooleanAdapter { native: value }
823    }
824}
825
826impl From<&Option<bool>> for BooleanAdapter {
827    fn from(value: &Option<bool>) -> Self {
828        BooleanAdapter { native: *value }
829    }
830}
831
832impl<Ptr: Into<BooleanAdapter>> FromIterator<Ptr> for BooleanArray {
833    fn from_iter<I: IntoIterator<Item = Ptr>>(iter: I) -> Self {
834        let iter = iter.into_iter();
835        let capacity = match iter.size_hint() {
836            (lower, Some(upper)) if lower == upper => lower,
837            _ => 0,
838        };
839        let mut builder = BooleanBuilder::with_capacity(capacity);
840        builder.extend(iter.map(|item| item.into().native));
841        builder.finish()
842    }
843}
844
845impl BooleanArray {
846    /// Creates a [`BooleanArray`] from an iterator of trusted length.
847    ///
848    /// # Safety
849    ///
850    /// The iterator must be [`TrustedLen`](https://doc.rust-lang.org/std/iter/trait.TrustedLen.html).
851    /// I.e. that `size_hint().1` correctly reports its length. Note that this is a stronger
852    /// guarantee that `ExactSizeIterator` provides which could still report a wrong length.
853    ///
854    /// # Panics
855    ///
856    /// Panics if the iterator does not report an upper bound on `size_hint()`.
857    #[inline]
858    #[expect(
859        private_bounds,
860        reason = "We will expose BooleanAdapter if there is a need"
861    )]
862    pub unsafe fn from_trusted_len_iter<I, P>(iter: I) -> Self
863    where
864        P: Into<BooleanAdapter>,
865        I: ExactSizeIterator<Item = P>,
866    {
867        let data_len = iter.len();
868
869        let num_bytes = bit_util::ceil(data_len, 8);
870        let mut null_builder = MutableBuffer::from_len_zeroed(num_bytes);
871        let mut val_builder = MutableBuffer::from_len_zeroed(num_bytes);
872
873        let data = val_builder.as_slice_mut();
874
875        let null_slice = null_builder.as_slice_mut();
876        iter.enumerate().for_each(|(i, item)| {
877            if let Some(a) = item.into().native {
878                unsafe {
879                    // SAFETY: There will be enough space in the buffers due to the trusted len size
880                    // hint
881                    bit_util::set_bit_raw(null_slice.as_mut_ptr(), i);
882                    if a {
883                        bit_util::set_bit_raw(data.as_mut_ptr(), i);
884                    }
885                }
886            }
887        });
888
889        let values = BooleanBuffer::new(val_builder.into(), 0, data_len);
890        let nulls = NullBuffer::from_unsliced_buffer(null_builder, data_len);
891        BooleanArray::new(values, nulls)
892    }
893}
894
895impl From<BooleanBuffer> for BooleanArray {
896    fn from(values: BooleanBuffer) -> Self {
897        Self {
898            values,
899            nulls: None,
900        }
901    }
902}
903
904#[cfg(test)]
905mod tests {
906    use super::*;
907
908    // Captures the values-buffer identity for a BooleanArray so tests can assert
909    // whether an operation reused the original allocation or produced a new one.
910    struct PointerInfo {
911        ptr: *const u8,
912        offset: usize,
913        len: usize,
914    }
915
916    impl PointerInfo {
917        // Record the current values buffer pointer plus bit offset/length. The
918        // offset/length checks ensure a logically equivalent slice wasn't rebuilt
919        // with a different view over the same allocation.
920        fn new(array: &BooleanArray) -> Self {
921            Self {
922                ptr: array.values().inner().as_ptr(),
923                offset: array.values().offset(),
924                len: array.values().len(),
925            }
926        }
927
928        // Assert that the array still points at the exact same values buffer and
929        // preserves the same bit view.
930        fn assert_same(&self, array: &BooleanArray) {
931            assert_eq!(array.values().inner().as_ptr(), self.ptr);
932            assert_eq!(array.values().offset(), self.offset);
933            assert_eq!(array.values().len(), self.len);
934        }
935
936        // Assert that the array now points at a different values allocation,
937        // indicating the operation fell back to an allocating path.
938        fn assert_different(&self, array: &BooleanArray) {
939            assert_ne!(array.values().inner().as_ptr(), self.ptr);
940        }
941    }
942    use arrow_buffer::Buffer;
943    use rand::{RngExt, rng};
944
945    #[test]
946    fn test_boolean_fmt_debug() {
947        let arr = BooleanArray::from(vec![true, false, false]);
948        assert_eq!(
949            "BooleanArray\n[\n  true,\n  false,\n  false,\n]",
950            format!("{arr:?}")
951        );
952    }
953
954    #[test]
955    fn test_boolean_with_null_fmt_debug() {
956        let mut builder = BooleanArray::builder(3);
957        builder.append_value(true);
958        builder.append_null();
959        builder.append_value(false);
960        let arr = builder.finish();
961        assert_eq!(
962            "BooleanArray\n[\n  true,\n  null,\n  false,\n]",
963            format!("{arr:?}")
964        );
965    }
966
967    #[test]
968    fn test_boolean_array_from_vec() {
969        let buf = Buffer::from([10_u8]);
970        let arr = BooleanArray::from(vec![false, true, false, true]);
971        assert_eq!(&buf, arr.values().inner());
972        assert_eq!(4, arr.len());
973        assert_eq!(0, arr.offset());
974        assert_eq!(0, arr.null_count());
975        for i in 0..4 {
976            assert!(!arr.is_null(i));
977            assert!(arr.is_valid(i));
978            assert_eq!(i == 1 || i == 3, arr.value(i), "failed at {i}")
979        }
980    }
981
982    #[test]
983    fn test_boolean_array_from_vec_option() {
984        let buf = Buffer::from([10_u8]);
985        let arr = BooleanArray::from(vec![Some(false), Some(true), None, Some(true)]);
986        assert_eq!(&buf, arr.values().inner());
987        assert_eq!(4, arr.len());
988        assert_eq!(0, arr.offset());
989        assert_eq!(1, arr.null_count());
990        for i in 0..4 {
991            if i == 2 {
992                assert!(arr.is_null(i));
993                assert!(!arr.is_valid(i));
994            } else {
995                assert!(!arr.is_null(i));
996                assert!(arr.is_valid(i));
997                assert_eq!(i == 1 || i == 3, arr.value(i), "failed at {i}")
998            }
999        }
1000    }
1001
1002    #[test]
1003    fn test_boolean_array_from_packed() {
1004        let v = [1_u8, 2_u8, 3_u8];
1005        let arr = BooleanArray::new_from_packed(v, 0, 24);
1006        assert_eq!(24, arr.len());
1007        assert_eq!(0, arr.offset());
1008        assert_eq!(0, arr.null_count());
1009        assert!(arr.nulls.is_none());
1010        for i in 0..24 {
1011            assert!(!arr.is_null(i));
1012            assert!(arr.is_valid(i));
1013            assert_eq!(
1014                i == 0 || i == 9 || i == 16 || i == 17,
1015                arr.value(i),
1016                "failed t {i}"
1017            )
1018        }
1019    }
1020
1021    #[test]
1022    fn test_boolean_array_from_slice_u8() {
1023        let v: Vec<u8> = vec![1, 2, 3];
1024        let slice = &v[..];
1025        let arr = BooleanArray::new_from_u8(slice);
1026        assert_eq!(24, arr.len());
1027        assert_eq!(0, arr.offset());
1028        assert_eq!(0, arr.null_count());
1029        assert!(arr.nulls().is_none());
1030        for i in 0..24 {
1031            assert!(!arr.is_null(i));
1032            assert!(arr.is_valid(i));
1033            assert_eq!(
1034                i == 0 || i == 9 || i == 16 || i == 17,
1035                arr.value(i),
1036                "failed t {i}"
1037            )
1038        }
1039    }
1040
1041    #[test]
1042    fn test_boolean_array_from_iter() {
1043        let v = vec![Some(false), Some(true), Some(false), Some(true)];
1044        let arr = v.into_iter().collect::<BooleanArray>();
1045        assert_eq!(4, arr.len());
1046        assert_eq!(0, arr.offset());
1047        assert_eq!(0, arr.null_count());
1048        assert!(arr.nulls().is_none());
1049        for i in 0..3 {
1050            assert!(!arr.is_null(i));
1051            assert!(arr.is_valid(i));
1052            assert_eq!(i == 1 || i == 3, arr.value(i), "failed at {i}")
1053        }
1054    }
1055
1056    #[test]
1057    fn test_boolean_array_from_non_nullable_iter() {
1058        let v = vec![true, false, true];
1059        let arr = v.into_iter().collect::<BooleanArray>();
1060        assert_eq!(3, arr.len());
1061        assert_eq!(0, arr.offset());
1062        assert_eq!(0, arr.null_count());
1063        assert!(arr.nulls().is_none());
1064
1065        assert!(arr.value(0));
1066        assert!(!arr.value(1));
1067        assert!(arr.value(2));
1068    }
1069
1070    #[test]
1071    fn test_boolean_array_from_nullable_iter() {
1072        let v = vec![Some(true), None, Some(false), None];
1073        let arr = v.into_iter().collect::<BooleanArray>();
1074        assert_eq!(4, arr.len());
1075        assert_eq!(0, arr.offset());
1076        assert_eq!(2, arr.null_count());
1077        assert!(arr.nulls().is_some());
1078
1079        assert!(arr.is_valid(0));
1080        assert!(arr.is_null(1));
1081        assert!(arr.is_valid(2));
1082        assert!(arr.is_null(3));
1083
1084        assert!(arr.value(0));
1085        assert!(!arr.value(2));
1086    }
1087
1088    #[test]
1089    fn test_boolean_array_from_nullable_trusted_len_iter() {
1090        // Should exhibit the same behavior as `from_iter`, which is tested above.
1091        let v = vec![Some(true), None, Some(false), None];
1092        let expected = v.clone().into_iter().collect::<BooleanArray>();
1093        let actual = unsafe {
1094            // SAFETY: `v` has trusted length
1095            BooleanArray::from_trusted_len_iter(v.into_iter())
1096        };
1097        assert_eq!(expected, actual);
1098    }
1099
1100    #[test]
1101    fn test_boolean_array_from_iter_with_larger_upper_bound() {
1102        // See https://github.com/apache/arrow-rs/issues/8505
1103        // This returns an upper size hint of 4
1104        #[expect(
1105            clippy::iter_filter_is_some,
1106            reason = "the point of the test is the size hint of `filter`, which `flatten` does not have"
1107        )]
1108        let iterator = vec![Some(true), None, Some(false), None]
1109            .into_iter()
1110            .filter(Option::is_some);
1111        let arr = iterator.collect::<BooleanArray>();
1112        assert_eq!(2, arr.len());
1113    }
1114
1115    #[test]
1116    #[cfg_attr(miri, ignore)] // Unsupported inline assembly
1117    fn test_boolean_array_builder() {
1118        // Test building a boolean array with ArrayData builder and offset
1119        // 000011011
1120        let buf = Buffer::from([27_u8]);
1121        let buf2 = buf.clone();
1122        let data = ArrayData::builder(DataType::Boolean)
1123            .len(5)
1124            .offset(2)
1125            .add_buffer(buf)
1126            .build()
1127            .unwrap();
1128        let arr = BooleanArray::from(data);
1129        assert_eq!(&buf2, arr.values().inner());
1130        assert_eq!(5, arr.len());
1131        assert_eq!(2, arr.offset());
1132        assert_eq!(0, arr.null_count());
1133        for i in 0..3 {
1134            assert_eq!(i != 0, arr.value(i), "failed at {i}");
1135        }
1136    }
1137
1138    #[test]
1139    #[should_panic(
1140        expected = "Trying to access an element at index 4 from a BooleanArray of length 3"
1141    )]
1142    fn test_fixed_size_binary_array_get_value_index_out_of_bound() {
1143        let v = vec![Some(true), None, Some(false)];
1144        let array = v.into_iter().collect::<BooleanArray>();
1145
1146        array.value(4);
1147    }
1148
1149    #[test]
1150    #[should_panic(expected = "BooleanArray data should contain a single buffer only \
1151                               (values buffer)")]
1152    // Different error messages, so skip for now
1153    // https://github.com/apache/arrow-rs/issues/1545
1154    #[cfg(not(feature = "force_validate"))]
1155    fn test_boolean_array_invalid_buffer_len() {
1156        let data = unsafe {
1157            ArrayData::builder(DataType::Boolean)
1158                .len(5)
1159                .build_unchecked()
1160        };
1161        drop(BooleanArray::from(data));
1162    }
1163
1164    #[test]
1165    #[should_panic(expected = "BooleanArray expected ArrayData with type Boolean got Int32")]
1166    fn test_from_array_data_validation() {
1167        let _ = BooleanArray::from(ArrayData::new_empty(&DataType::Int32));
1168    }
1169
1170    #[test]
1171    #[cfg_attr(miri, ignore)] // Takes too long
1172    fn test_true_false_count() {
1173        let mut rng = rng();
1174
1175        for _ in 0..10 {
1176            // No nulls
1177            let d: Vec<_> = (0..2000).map(|_| rng.random_bool(0.5)).collect();
1178            let b = BooleanArray::from(d.clone());
1179
1180            let expected_true = d.iter().filter(|x| **x).count();
1181            assert_eq!(b.true_count(), expected_true);
1182            assert_eq!(b.false_count(), d.len() - expected_true);
1183
1184            // With nulls
1185            let d: Vec<_> = (0..2000)
1186                .map(|_| rng.random_bool(0.5).then(|| rng.random_bool(0.5)))
1187                .collect();
1188            let b = BooleanArray::from(d.clone());
1189
1190            let expected_true = d.iter().filter(|x| matches!(x, Some(true))).count();
1191            assert_eq!(b.true_count(), expected_true);
1192
1193            let expected_false = d.iter().filter(|x| matches!(x, Some(false))).count();
1194            assert_eq!(b.false_count(), expected_false);
1195        }
1196    }
1197
1198    #[test]
1199    fn test_into_parts() {
1200        let boolean_array = [Some(true), None, Some(false)]
1201            .into_iter()
1202            .collect::<BooleanArray>();
1203        let (values, nulls) = boolean_array.into_parts();
1204        assert_eq!(values.values(), &[0b0000_0001]);
1205        assert!(nulls.is_some());
1206        assert_eq!(nulls.unwrap().buffer().as_slice(), &[0b0000_0101]);
1207
1208        let boolean_array =
1209            BooleanArray::from(vec![false, false, false, false, false, false, false, true]);
1210        let (values, nulls) = boolean_array.into_parts();
1211        assert_eq!(values.values(), &[0b1000_0000]);
1212        assert!(nulls.is_none());
1213    }
1214
1215    #[test]
1216    fn test_new_null_array() {
1217        let arr = BooleanArray::new_null(5);
1218
1219        assert_eq!(arr.len(), 5);
1220        assert_eq!(arr.null_count(), 5);
1221        assert_eq!(arr.true_count(), 0);
1222        assert_eq!(arr.false_count(), 0);
1223
1224        for i in 0..5 {
1225            assert!(arr.is_null(i));
1226            assert!(!arr.is_valid(i));
1227        }
1228    }
1229
1230    #[test]
1231    fn test_slice_with_nulls() {
1232        let arr = BooleanArray::from(vec![Some(true), None, Some(false)]);
1233        let sliced = arr.slice(1, 2);
1234
1235        assert_eq!(sliced.len(), 2);
1236        assert_eq!(sliced.null_count(), 1);
1237
1238        assert!(sliced.is_null(0));
1239        assert!(sliced.is_valid(1));
1240        assert!(!sliced.value(1));
1241    }
1242
1243    #[test]
1244    fn test_has_true_has_false_all_true() {
1245        let arr = BooleanArray::from(vec![true, true, true]);
1246        assert!(arr.has_true());
1247        assert!(!arr.has_false());
1248    }
1249
1250    #[test]
1251    fn test_has_true_has_false_all_false() {
1252        let arr = BooleanArray::from(vec![false, false, false]);
1253        assert!(!arr.has_true());
1254        assert!(arr.has_false());
1255    }
1256
1257    #[test]
1258    fn test_has_true_has_false_mixed() {
1259        let arr = BooleanArray::from(vec![true, false, true]);
1260        assert!(arr.has_true());
1261        assert!(arr.has_false());
1262    }
1263
1264    #[test]
1265    fn test_has_true_has_false_empty() {
1266        let arr = BooleanArray::from(Vec::<bool>::new());
1267        assert!(!arr.has_true());
1268        assert!(!arr.has_false());
1269    }
1270
1271    #[test]
1272    fn test_has_true_has_false_nulls_all_valid_true() {
1273        let arr = BooleanArray::from(vec![Some(true), None, Some(true)]);
1274        assert!(arr.has_true());
1275        assert!(!arr.has_false());
1276    }
1277
1278    #[test]
1279    fn test_has_true_has_false_nulls_all_valid_false() {
1280        let arr = BooleanArray::from(vec![Some(false), None, Some(false)]);
1281        assert!(!arr.has_true());
1282        assert!(arr.has_false());
1283    }
1284
1285    #[test]
1286    fn test_has_true_has_false_all_null() {
1287        let arr = BooleanArray::new_null(5);
1288        assert!(!arr.has_true());
1289        assert!(!arr.has_false());
1290    }
1291
1292    #[test]
1293    fn test_has_false_aligned_suffix_all_true() {
1294        let arr = BooleanArray::from(vec![true; 129]);
1295        assert!(arr.has_true());
1296        assert!(!arr.has_false());
1297    }
1298
1299    #[test]
1300    fn test_has_false_non_aligned_all_true() {
1301        // 65 elements: exercises the remainder path in has_false
1302        let arr = BooleanArray::from(vec![true; 65]);
1303        assert!(arr.has_true());
1304        assert!(!arr.has_false());
1305    }
1306
1307    #[test]
1308    fn test_has_false_non_aligned_last_false() {
1309        // 64 trues + 1 false: remainder path should find the false
1310        let mut values = vec![true; 64];
1311        values.push(false);
1312        let arr = BooleanArray::from(values);
1313        assert!(arr.has_true());
1314        assert!(arr.has_false());
1315    }
1316
1317    #[test]
1318    fn test_has_false_exact_64_all_true() {
1319        // Exactly 64 elements, no remainder
1320        let arr = BooleanArray::from(vec![true; 64]);
1321        assert!(arr.has_true());
1322        assert!(!arr.has_false());
1323    }
1324
1325    #[test]
1326    fn test_has_true_has_false_unaligned_slices() {
1327        let cases = [
1328            (1, 129, true, false),
1329            (3, 130, true, false),
1330            (5, 65, true, false),
1331            (7, 64, true, false),
1332        ];
1333
1334        let base = BooleanArray::from(vec![true; 300]);
1335
1336        for (offset, len, expected_has_true, expected_has_false) in cases {
1337            let arr = base.slice(offset, len);
1338            assert_eq!(
1339                arr.has_true(),
1340                expected_has_true,
1341                "offset={offset} len={len}"
1342            );
1343            assert_eq!(
1344                arr.has_false(),
1345                expected_has_false,
1346                "offset={offset} len={len}"
1347            );
1348        }
1349    }
1350
1351    #[test]
1352    fn test_has_true_has_false_exact_multiples_of_64() {
1353        let cases = [
1354            (64, true, false),
1355            (128, true, false),
1356            (192, true, false),
1357            (256, true, false),
1358        ];
1359
1360        for (len, expected_has_true, expected_has_false) in cases {
1361            let arr = BooleanArray::from(vec![true; len]);
1362            assert_eq!(arr.has_true(), expected_has_true, "len={len}");
1363            assert_eq!(arr.has_false(), expected_has_false, "len={len}");
1364        }
1365    }
1366
1367    #[test]
1368    #[cfg_attr(miri, ignore)] // Unsupported inline assembly
1369    fn test_bitwise_unary_not() {
1370        let arr = BooleanArray::from(vec![true, false, true, false]);
1371        let result = arr.bitwise_unary(|x| !x);
1372        let expected = BooleanArray::from(vec![false, true, false, true]);
1373        assert_eq!(result, expected);
1374    }
1375
1376    #[test]
1377    #[cfg_attr(miri, ignore)] // Unsupported inline assembly
1378    fn test_bitwise_unary_preserves_nulls() {
1379        let arr = BooleanArray::from(vec![Some(true), None, Some(false), Some(true)]);
1380        let result = arr.bitwise_unary(|x| !x);
1381
1382        assert_eq!(result.null_count(), 1);
1383        assert!(result.is_null(1));
1384        assert!(!result.value(0));
1385        assert!(result.value(2));
1386        assert!(!result.value(3));
1387    }
1388
1389    #[test]
1390    #[cfg_attr(miri, ignore)] // Unsupported inline assembly
1391    fn test_bitwise_unary_mut_unshared() {
1392        let arr = BooleanArray::from(vec![true, false, true, false]);
1393        let info = PointerInfo::new(&arr);
1394        let result = arr.bitwise_unary_mut(|x| !x).unwrap();
1395        let expected = BooleanArray::from(vec![false, true, false, true]);
1396        assert_eq!(result, expected);
1397        info.assert_same(&result);
1398    }
1399
1400    #[test]
1401    #[cfg_attr(miri, ignore)] // Unsupported inline assembly
1402    fn test_bitwise_unary_mut_shared() {
1403        let arr = BooleanArray::from(vec![true, false, true, false]);
1404        let info = PointerInfo::new(&arr);
1405        let _shared = arr.clone();
1406        let result = arr.bitwise_unary_mut(|x| !x);
1407        assert!(result.is_err());
1408
1409        let returned = result.unwrap_err();
1410        assert_eq!(returned, BooleanArray::from(vec![true, false, true, false]));
1411        info.assert_same(&returned);
1412    }
1413
1414    #[test]
1415    #[cfg_attr(miri, ignore)] // Unsupported inline assembly
1416    fn test_bitwise_unary_mut_with_nulls() {
1417        let arr = BooleanArray::from(vec![Some(true), None, Some(false)]);
1418        let result = arr.bitwise_unary_mut(|x| !x).unwrap();
1419
1420        assert_eq!(result.null_count(), 1);
1421        assert!(result.is_null(1));
1422        assert!(!result.value(0));
1423        assert!(result.value(2));
1424    }
1425
1426    #[test]
1427    fn test_bitwise_unary_mut_or_clone_shared() {
1428        let arr = BooleanArray::from(vec![true, false, true]);
1429        let info = PointerInfo::new(&arr);
1430        let _shared = arr.clone();
1431        let result = arr.bitwise_unary_mut_or_clone(|x| !x);
1432        assert_eq!(result, BooleanArray::from(vec![false, true, false]));
1433        info.assert_different(&result);
1434    }
1435
1436    #[test]
1437    fn test_bitwise_unary_mut_or_clone_unshared() {
1438        // Covers the uniquely-owned fast path in bitwise_unary_mut_or_clone.
1439        let arr = BooleanArray::from(vec![true, false, true]);
1440        let info = PointerInfo::new(&arr);
1441        let result = arr.bitwise_unary_mut_or_clone(|x| !x);
1442        assert_eq!(result, BooleanArray::from(vec![false, true, false]));
1443        info.assert_same(&result);
1444    }
1445
1446    #[test]
1447    fn test_bitwise_bin_op_and() {
1448        let a = BooleanArray::from(vec![true, false, true, true]);
1449        let b = BooleanArray::from(vec![true, true, false, true]);
1450        let result = a.bitwise_bin_op(&b, |a, b| a & b);
1451        assert_eq!(result, BooleanArray::from(vec![true, false, false, true]));
1452    }
1453
1454    #[test]
1455    fn test_bitwise_bin_op_or() {
1456        let a = BooleanArray::from(vec![true, false, true, false]);
1457        let b = BooleanArray::from(vec![false, true, false, false]);
1458        let result = a.bitwise_bin_op(&b, |a, b| a | b);
1459        assert_eq!(result, BooleanArray::from(vec![true, true, true, false]));
1460    }
1461
1462    #[test]
1463    fn test_bitwise_bin_op_null_union() {
1464        let a = BooleanArray::from(vec![Some(true), None, Some(true), Some(false)]);
1465        let b = BooleanArray::from(vec![Some(true), Some(true), None, Some(true)]);
1466        let result = a.bitwise_bin_op(&b, |a, b| a & b);
1467
1468        assert_eq!(result.null_count(), 2);
1469        assert!(result.is_null(1));
1470        assert!(result.is_null(2));
1471        assert!(result.value(0));
1472        assert!(!result.value(3));
1473    }
1474
1475    #[test]
1476    fn test_bitwise_bin_op_one_nullable() {
1477        let a = BooleanArray::from(vec![Some(true), None, Some(true)]);
1478        let b = BooleanArray::from(vec![false, true, true]);
1479        let result = a.bitwise_bin_op(&b, |a, b| a & b);
1480
1481        assert_eq!(result.null_count(), 1);
1482        assert!(result.is_null(1));
1483        assert!(!result.value(0));
1484        assert!(result.value(2));
1485    }
1486
1487    #[test]
1488    fn test_bitwise_bin_op_no_nulls() {
1489        let a = BooleanArray::from(vec![true, false, true]);
1490        let b = BooleanArray::from(vec![false, true, true]);
1491        let result = a.bitwise_bin_op(&b, |a, b| a | b);
1492
1493        assert!(result.nulls().is_none());
1494        assert_eq!(result, BooleanArray::from(vec![true, true, true]));
1495    }
1496
1497    #[test]
1498    fn test_bitwise_bin_op_mut_unshared() {
1499        let a = BooleanArray::from(vec![true, false, true, true]);
1500        let info = PointerInfo::new(&a);
1501        let b = BooleanArray::from(vec![true, true, false, true]);
1502        let result = a.bitwise_bin_op_mut(&b, |a, b| a & b).unwrap();
1503        assert_eq!(result, BooleanArray::from(vec![true, false, false, true]));
1504        info.assert_same(&result);
1505    }
1506
1507    #[test]
1508    fn test_bitwise_bin_op_mut_shared() {
1509        let a = BooleanArray::from(vec![true, false, true, true]);
1510        let info = PointerInfo::new(&a);
1511        let _shared = a.clone();
1512        let result = a.bitwise_bin_op_mut(
1513            &BooleanArray::from(vec![true, true, false, true]),
1514            |a, b| a & b,
1515        );
1516        assert!(result.is_err());
1517        let returned = result.unwrap_err();
1518        info.assert_same(&returned);
1519    }
1520
1521    #[test]
1522    fn test_bitwise_bin_op_mut_with_nulls() {
1523        let a = BooleanArray::from(vec![Some(true), None, Some(true), Some(false)]);
1524        let b = BooleanArray::from(vec![Some(true), Some(true), None, Some(true)]);
1525        let result = a.bitwise_bin_op_mut(&b, |a, b| a & b).unwrap();
1526
1527        assert_eq!(result.null_count(), 2);
1528        assert!(result.is_null(1));
1529        assert!(result.is_null(2));
1530        assert!(result.value(0));
1531        assert!(!result.value(3));
1532    }
1533
1534    #[test]
1535    fn test_bitwise_bin_op_mut_or_clone_shared() {
1536        let a = BooleanArray::from(vec![true, false, true, true]);
1537        let info = PointerInfo::new(&a);
1538        let _shared = a.clone();
1539        let b = BooleanArray::from(vec![true, true, false, true]);
1540        let result = a.bitwise_bin_op_mut_or_clone(&b, |a, b| a & b);
1541        assert_eq!(result, BooleanArray::from(vec![true, false, false, true]));
1542        info.assert_different(&result);
1543    }
1544
1545    #[test]
1546    fn test_bitwise_bin_op_mut_or_clone_shared_with_nulls() {
1547        // When the buffer is shared, _mut_or_clone falls back to bitwise_bin_op.
1548        // The null union must only be applied once, not double-applied.
1549        let a = BooleanArray::from(vec![Some(true), None, Some(true), Some(false)]);
1550        let info = PointerInfo::new(&a);
1551        let _shared = a.clone();
1552        let b = BooleanArray::from(vec![Some(true), Some(true), None, Some(true)]);
1553
1554        let expected = a.bitwise_bin_op(&b, |a, b| a & b);
1555        let result = a.bitwise_bin_op_mut_or_clone(&b, |a, b| a & b);
1556
1557        assert_eq!(result, expected);
1558        assert_eq!(result.null_count(), 2);
1559        assert!(result.is_null(1));
1560        assert!(result.is_null(2));
1561        info.assert_different(&result);
1562    }
1563
1564    #[test]
1565    fn test_bitwise_bin_op_mut_or_clone_unshared_with_nulls() {
1566        // Covers the uniquely-owned fast path in bitwise_bin_op_mut_or_clone,
1567        // including null union on the in-place path.
1568        let a = BooleanArray::from(vec![Some(true), None, Some(true), Some(false)]);
1569        let info = PointerInfo::new(&a);
1570        let b = BooleanArray::from(vec![Some(true), Some(true), None, Some(true)]);
1571        let result = a.bitwise_bin_op_mut_or_clone(&b, |a, b| a & b);
1572
1573        assert_eq!(result.null_count(), 2);
1574        assert!(result.is_null(1));
1575        assert!(result.is_null(2));
1576        assert!(result.value(0));
1577        assert!(!result.value(3));
1578        info.assert_same(&result);
1579    }
1580
1581    #[test]
1582    fn test_bitwise_unary_empty() {
1583        let arr = BooleanArray::from(Vec::<bool>::new());
1584        let result = arr.bitwise_unary(|x| !x);
1585        assert_eq!(result.len(), 0);
1586    }
1587
1588    #[test]
1589    fn test_bitwise_bin_op_empty() {
1590        let a = BooleanArray::from(Vec::<bool>::new());
1591        let b = BooleanArray::from(Vec::<bool>::new());
1592        let result = a.bitwise_bin_op(&b, |a, b| a & b);
1593        assert_eq!(result.len(), 0);
1594    }
1595
1596    #[test]
1597    #[cfg_attr(miri, ignore)] // Unsupported inline assembly
1598    fn test_bitwise_unary_sliced() {
1599        // Slicing creates a non-zero offset into the underlying buffer.
1600        let arr = BooleanArray::from(vec![true, false, true, true, false]);
1601        let sliced = arr.slice(1, 3); // [false, true, true]
1602
1603        let result = sliced.bitwise_unary(|x| !x);
1604        assert_eq!(result.len(), 3);
1605        assert!(result.value(0));
1606        assert!(!result.value(1));
1607        assert!(!result.value(2));
1608    }
1609
1610    #[test]
1611    #[cfg_attr(miri, ignore)] // Unsupported inline assembly
1612    fn test_bitwise_unary_mut_sliced() {
1613        // Slicing shares the buffer, so _mut must return Err.
1614        let arr = BooleanArray::from(vec![true, false, true, true, false]);
1615        let sliced = arr.slice(1, 3);
1616        assert!(sliced.bitwise_unary_mut(|x| !x).is_err());
1617    }
1618
1619    #[test]
1620    fn test_bitwise_unary_mut_or_clone_sliced() {
1621        // Slicing shares the buffer, so _mut_or_clone falls back to allocating.
1622        let arr = BooleanArray::from(vec![true, false, true, true, false]);
1623        let sliced = arr.slice(1, 3); // [false, true, true]
1624
1625        let result = sliced.bitwise_unary_mut_or_clone(|x| !x);
1626        assert_eq!(result.len(), 3);
1627        assert!(result.value(0));
1628        assert!(!result.value(1));
1629        assert!(!result.value(2));
1630    }
1631
1632    #[test]
1633    fn test_bitwise_bin_op_different_offsets() {
1634        // Left and right sliced to different offsets exercises misaligned
1635        // bit handling in from_bitwise_binary_op.
1636        let left_full = BooleanArray::from(vec![false, true, false, true, true]);
1637        let right_full = BooleanArray::from(vec![true, true, true, false, true, false]);
1638
1639        let left = left_full.slice(1, 3); // [true, false, true]
1640        let right = right_full.slice(2, 3); // [true, false, true]
1641
1642        let result = left.bitwise_bin_op(&right, |a, b| a & b);
1643        assert_eq!(result.len(), 3);
1644        assert!(result.value(0));
1645        assert!(!result.value(1));
1646        assert!(result.value(2));
1647    }
1648
1649    #[test]
1650    fn test_bitwise_bin_op_mut_or_clone_different_offsets() {
1651        // Both sliced (shared buffers), so falls back to allocating path.
1652        let left_full = BooleanArray::from(vec![false, true, true, false, true]);
1653        let right_full = BooleanArray::from(vec![true, true, false, false, true, false]);
1654
1655        let left = left_full.slice(1, 3); // [true, true, false]
1656        let right = right_full.slice(2, 3); // [false, false, true]
1657
1658        let expected = left.bitwise_bin_op(&right, |a, b| a & b);
1659        let result = left.bitwise_bin_op_mut_or_clone(&right, |a, b| a & b);
1660        assert_eq!(result, expected);
1661    }
1662
1663    #[test]
1664    fn test_take_n_true_keeps_first_n_matches() {
1665        let a = BooleanArray::from(vec![true, false, true, true, false, true, true]);
1666        // true positions: 0, 2, 3, 5, 6
1667        let r = a.clone().take_n_true(3);
1668        assert_eq!(r.len(), a.len());
1669        assert_eq!(r.true_count(), 3);
1670        let out: Vec<bool> = (0..r.len()).map(|i| r.value(i)).collect();
1671        assert_eq!(
1672            out,
1673            vec![true, false, true, true, false, false, false],
1674            "first three trues should survive, the rest become false"
1675        );
1676    }
1677
1678    #[test]
1679    fn test_take_n_true_passes_through_when_already_small_enough() {
1680        let a = BooleanArray::from(vec![true, false, true, false]);
1681        let r = a.clone().take_n_true(5);
1682        assert_eq!(r.len(), a.len());
1683        assert_eq!(r.true_count(), 2);
1684        assert_eq!(r, a);
1685    }
1686
1687    #[test]
1688    fn test_take_n_true_zero_returns_all_false() {
1689        let a = BooleanArray::from(vec![true, true, true]);
1690        let r = a.take_n_true(0);
1691        assert_eq!(r.len(), 3);
1692        assert_eq!(r.true_count(), 0);
1693    }
1694
1695    #[test]
1696    fn test_take_n_true_preserves_nulls_and_skips_them() {
1697        // Non-null trues: positions 0, 3, 5. Null at 2 must not count toward `n`.
1698        let a = BooleanArray::from(vec![
1699            Some(true),
1700            Some(false),
1701            None,
1702            Some(true),
1703            Some(false),
1704            Some(true),
1705        ]);
1706        assert_eq!(a.true_count(), 3);
1707        let len = a.len();
1708
1709        let r = a.take_n_true(2);
1710        assert_eq!(r.len(), len);
1711        assert_eq!(r.true_count(), 2);
1712        // Null buffer is preserved unchanged.
1713        assert_eq!(r.null_count(), 1);
1714        assert!(r.is_null(2));
1715        // First two non-null trues kept; the third (position 5) becomes false.
1716        assert!(r.value(0));
1717        assert!(!r.value(1));
1718        assert!(r.value(3));
1719        assert!(!r.value(4));
1720        assert!(!r.value(5));
1721    }
1722
1723    #[test]
1724    fn test_take_n_true_empty_array() {
1725        let a = BooleanArray::from(Vec::<bool>::new());
1726        let r = a.take_n_true(5);
1727        assert_eq!(r.len(), 0);
1728        assert_eq!(r.true_count(), 0);
1729    }
1730
1731    #[test]
1732    fn test_take_n_true_unique_buffer() {
1733        // unique buffer ownership -> mutable in-place path.
1734        let arr = BooleanArray::from(vec![true, false, true, true, false, true, true]);
1735        let result = arr.take_n_true(3);
1736        assert_eq!(result.true_count(), 3);
1737        let values: Vec<bool> = (0..result.len()).map(|i| result.value(i)).collect();
1738        assert_eq!(values, vec![true, false, true, true, false, false, false]);
1739    }
1740}