Skip to main content

vortex_array/arrays/bool/compute/
zip.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use vortex_buffer::BitBuffer;
5use vortex_buffer::BufferMut;
6use vortex_error::VortexResult;
7use vortex_mask::Mask;
8
9use crate::ArrayRef;
10use crate::ExecutionCtx;
11use crate::IntoArray;
12use crate::array::ArrayView;
13use crate::arrays::Bool;
14use crate::arrays::BoolArray;
15use crate::arrays::bool::BoolArrayExt;
16use crate::builtins::ArrayBuiltins;
17use crate::scalar_fn::fns::zip::ZipKernel;
18use crate::scalar_fn::fns::zip::zip_validity;
19
20/// A branchless boolean zip kernel that blends the two value bitmaps with the mask in one pass.
21///
22/// Booleans are bit-packed, so selecting `if_true` where the mask is set and `if_false` where it is
23/// not is a single bitwise blend over the packed words — `(true & mask) | (false & !mask)` — instead
24/// of the generic per-run builder. Validity is combined with the shared `zip_validity`, which itself
25/// reuses this kernel (terminating immediately, since validity bitmaps are non-nullable).
26impl ZipKernel for Bool {
27    fn zip(
28        if_true: ArrayView<'_, Bool>,
29        if_false: &ArrayRef,
30        mask: &ArrayRef,
31        ctx: &mut ExecutionCtx,
32    ) -> VortexResult<Option<ArrayRef>> {
33        let Some(if_false) = if_false.as_opt::<Bool>() else {
34            return Ok(None);
35        };
36
37        // Null mask entries select `if_false`, matching `Zip`'s SQL ELSE semantics.
38        let mask = mask.clone().fill_null(false)?.execute::<Mask>(ctx)?;
39        let mask_values = match &mask {
40            // Defer trivial masks to the generic zip, which just casts the surviving side.
41            Mask::AllTrue(_) | Mask::AllFalse(_) => return Ok(None),
42            Mask::Values(values) => values,
43        };
44        let mask_bits = mask_values.bit_buffer();
45
46        let values = zip_value_bits(
47            &if_true.to_bit_buffer(),
48            &if_false.to_bit_buffer(),
49            mask_bits,
50        );
51
52        let validity = zip_validity(if_true.validity()?, if_false.validity()?, &mask)?;
53
54        Ok(Some(BoolArray::new(values, validity).into_array()))
55    }
56}
57
58fn zip_value_bits(if_true: &BitBuffer, if_false: &BitBuffer, mask: &BitBuffer) -> BitBuffer {
59    assert_eq!(if_true.len(), if_false.len());
60    assert_eq!(if_true.len(), mask.len());
61
62    let true_chunks = if_true.chunks();
63    let false_chunks = if_false.chunks();
64    let mask_chunks = mask.chunks();
65
66    let mut values = BufferMut::<u64>::with_capacity(true_chunks.num_u64s());
67    for ((true_bits, false_bits), mask_bits) in true_chunks
68        .iter()
69        .zip(false_chunks.iter())
70        .zip(mask_chunks.iter())
71    {
72        values.push((true_bits & mask_bits) | (false_bits & !mask_bits));
73    }
74
75    if true_chunks.remainder_len() != 0 {
76        let true_bits = true_chunks.remainder_bits();
77        let false_bits = false_chunks.remainder_bits();
78        let mask_bits = mask_chunks.remainder_bits();
79        values.push((true_bits & mask_bits) | (false_bits & !mask_bits));
80    }
81
82    BitBuffer::new(values.freeze().into_byte_buffer(), if_true.len())
83}
84
85#[cfg(test)]
86mod tests {
87    use std::sync::LazyLock;
88
89    use vortex_error::VortexResult;
90    use vortex_mask::Mask;
91    use vortex_session::VortexSession;
92
93    use super::zip_value_bits;
94    use crate::ArrayRef;
95    use crate::IntoArray;
96    use crate::VortexSessionExecute;
97    use crate::arrays::Bool;
98    use crate::arrays::BoolArray;
99    use crate::assert_arrays_eq;
100    use crate::builtins::ArrayBuiltins;
101
102    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
103
104    #[test]
105    fn blend_value_bits_boundaries() {
106        for len in [0usize, 1, 2, 7, 8, 9, 63, 64, 65, 127, 128] {
107            let if_true = (0..len).map(|i| i.is_multiple_of(2)).collect();
108            let if_false = (0..len).map(|i| i.is_multiple_of(3)).collect();
109            let mask = (0..len).map(|i| i % 3 != 1).collect();
110
111            let values = zip_value_bits(&if_true, &if_false, &mask);
112
113            assert_eq!(values.len(), len);
114            assert_eq!(
115                values.iter().collect::<Vec<_>>(),
116                (0..len)
117                    .map(|i| {
118                        if i % 3 != 1 {
119                            i.is_multiple_of(2)
120                        } else {
121                            i.is_multiple_of(3)
122                        }
123                    })
124                    .collect::<Vec<_>>(),
125                "failed for len {len}",
126            );
127        }
128    }
129
130    /// Blend two non-nullable bool arrays across the 64-bit mask chunk boundary + remainder.
131    #[test]
132    fn zip_nonnull_spans_mask_chunks() -> VortexResult<()> {
133        let len = 150usize;
134        let if_true = BoolArray::from_iter((0..len).map(|i| i.is_multiple_of(2))).into_array();
135        let if_false = BoolArray::from_iter((0..len).map(|i| i.is_multiple_of(3))).into_array();
136
137        let bits: Vec<bool> = (0..len).map(|i| i.is_multiple_of(5) || i == 64).collect();
138        let mask = Mask::from_iter(bits.iter().copied());
139
140        let mut ctx = SESSION.create_execution_ctx();
141        let result = mask
142            .into_array()
143            .zip(if_true, if_false)?
144            .execute::<ArrayRef>(&mut ctx)?;
145        assert!(result.is::<Bool>());
146
147        let expected = BoolArray::from_iter((0..len).map(|i| {
148            if bits[i] {
149                i.is_multiple_of(2)
150            } else {
151                i.is_multiple_of(3)
152            }
153        }))
154        .into_array();
155        assert_arrays_eq!(result, expected, &mut ctx);
156        Ok(())
157    }
158
159    /// With `Validity::Array` on both sides, select values and validity from the chosen side.
160    #[test]
161    fn zip_nullable_selects_values_and_validity() -> VortexResult<()> {
162        let len = 130usize;
163        let if_true = BoolArray::from_iter(
164            (0..len).map(|i| (!i.is_multiple_of(4)).then_some(i.is_multiple_of(2))),
165        )
166        .into_array();
167        let if_false = BoolArray::from_iter(
168            (0..len).map(|i| (!i.is_multiple_of(5)).then_some(i.is_multiple_of(3))),
169        )
170        .into_array();
171
172        let bits: Vec<bool> = (0..len).map(|i| i.is_multiple_of(2)).collect();
173        let mask = Mask::from_iter(bits.iter().copied());
174
175        let mut ctx = SESSION.create_execution_ctx();
176        let result = mask
177            .into_array()
178            .zip(if_true, if_false)?
179            .execute::<ArrayRef>(&mut ctx)?;
180        assert!(result.is::<Bool>());
181
182        let expected = BoolArray::from_iter((0..len).map(|i| {
183            if bits[i] {
184                (!i.is_multiple_of(4)).then_some(i.is_multiple_of(2))
185            } else {
186                (!i.is_multiple_of(5)).then_some(i.is_multiple_of(3))
187            }
188        }))
189        .into_array();
190        assert_arrays_eq!(result, expected, &mut ctx);
191        Ok(())
192    }
193}