Skip to main content

vortex_array/
mask.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use vortex_error::VortexResult;
5use vortex_error::vortex_bail;
6use vortex_mask::Mask;
7
8use crate::ArrayRef;
9use crate::Executable;
10use crate::ExecutionCtx;
11use crate::IntoArray;
12use crate::arrays::BoolArray;
13use crate::builtins::ArrayBuiltins;
14use crate::columnar::Columnar;
15use crate::dtype::DType;
16use crate::dtype::Nullability;
17
18impl Executable for Mask {
19    /// Executes a boolean array into a [`Mask`].
20    ///
21    /// The array must have a non-nullable boolean dtype. To execute a nullable boolean array,
22    /// coercing null elements to `false`, first call
23    /// [`ArrayRef::fill_null(false)`](crate::builtins::ArrayBuiltins::fill_null).
24    fn execute(array: ArrayRef, ctx: &mut ExecutionCtx) -> VortexResult<Self> {
25        if !matches!(array.dtype(), DType::Bool(Nullability::NonNullable)) {
26            vortex_bail!(
27                "Mask array must have boolean(NonNullable) dtype, not {}",
28                array.dtype()
29            );
30        }
31
32        let array_len = array.len();
33        Ok(match array.execute(ctx)? {
34            Columnar::Constant(s) => {
35                Mask::new(array_len, s.scalar().as_bool().value().unwrap_or(false))
36            }
37            Columnar::Canonical(a) => {
38                let bool = a.into_array().execute::<BoolArray>(ctx)?;
39                Mask::from(bool.into_bit_buffer())
40            }
41        })
42    }
43}
44
45#[deprecated = "Use array.fill_null(false)?.execute::<Mask>(ctx)"]
46pub struct NullAsFalse(ArrayRef);
47impl ArrayRef {
48    #[deprecated = "Use array.fill_null(false)?.execute::<Mask>(ctx)"]
49    #[allow(deprecated)]
50    pub fn null_as_false(self) -> NullAsFalse {
51        NullAsFalse(self)
52    }
53}
54#[allow(deprecated)]
55impl NullAsFalse {
56    #[deprecated = "Use array.fill_null(false)?.execute::<Mask>(ctx)"]
57    pub fn execute(self, ctx: &mut ExecutionCtx) -> VortexResult<Mask> {
58        self.0.fill_null(false)?.execute::<Mask>(ctx)
59    }
60}
61
62#[cfg(test)]
63mod tests {
64    use std::sync::LazyLock;
65
66    use vortex_error::VortexResult;
67    use vortex_mask::Mask;
68    use vortex_session::VortexSession;
69
70    use crate::ExecutionCtx;
71    use crate::IntoArray;
72    use crate::VortexSessionExecute;
73    use crate::arrays::BoolArray;
74    use crate::arrays::ConstantArray;
75    use crate::builtins::ArrayBuiltins;
76    use crate::dtype::DType;
77    use crate::dtype::Nullability;
78    use crate::scalar::Scalar;
79
80    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
81
82    fn ctx() -> ExecutionCtx {
83        SESSION.create_execution_ctx()
84    }
85
86    #[test]
87    fn mask_non_nullable() -> VortexResult<()> {
88        let array = BoolArray::from_iter([true, false, true]).into_array();
89        let mask = array.execute::<Mask>(&mut ctx())?;
90        assert_eq!(mask, Mask::from_iter([true, false, true]));
91        Ok(())
92    }
93
94    #[test]
95    fn mask_rejects_nullable() {
96        let array = BoolArray::from_iter([Some(true), None]).into_array();
97        assert!(array.execute::<Mask>(&mut ctx()).is_err());
98    }
99
100    #[test]
101    fn fill_null_then_mask_coerces_nulls() -> VortexResult<()> {
102        let array = BoolArray::from_iter([Some(true), None, Some(false), None]).into_array();
103        let mask = array.fill_null(false)?.execute::<Mask>(&mut ctx())?;
104        assert_eq!(mask, Mask::from_iter([true, false, false, false]));
105        Ok(())
106    }
107
108    #[test]
109    fn fill_null_then_mask_null_constant() -> VortexResult<()> {
110        let array =
111            ConstantArray::new(Scalar::null(DType::Bool(Nullability::Nullable)), 4).into_array();
112        let mask = array.fill_null(false)?.execute::<Mask>(&mut ctx())?;
113        assert_eq!(mask, Mask::new_false(4));
114        Ok(())
115    }
116}