break: add Validity::definitely_all_null() method (#8447)

## Summary

This PR introduces a new `Validity::definitely_all_null()` method that
provides a fast path to check if a validity is definitively all-null
(i.e., `Validity::AllInvalid`). This is the counterpart to the existing
`definitely_no_nulls()` method.

This is a rename, but not a change in semantics

---------

Signed-off-by: Joe Isaacs <joe.isaacs@live.co.uk>
Co-authored-by: Claude <noreply@anthropic.com>

Author: joseph-isaacs

vortex-array/src/arrays/dict/vtable/mod.rs

@@ -46,7 +46,6 @@ use crate::executor::ExecutionResult;
 use crate::require_child;
 use crate::scalar::Scalar;
 use crate::serde::ArrayChildren;
-use crate::validity::Validity;
 
 mod kernel;
 mod operations;
@@ -179,7 +178,7 @@ impl VTable for Dict {
 
         let array = require_child!(array, array.codes(), DictSlots::CODES => Primitive);
 
-        if matches!(array.codes().validity()?, Validity::AllInvalid) {
+        if array.codes().validity()?.definitely_all_null() {
             return Ok(ExecutionResult::done(ConstantArray::new(
                 Scalar::null(array.dtype().as_nullable()),
                 array.codes().len(),

vortex-array/src/arrays/masked/vtable/mod.rs

@@ -165,7 +165,7 @@ impl VTable for Masked {
         let validity = array.masked_validity();
 
         // Fast path: all masked means result is all nulls.
-        if matches!(validity, Validity::AllInvalid) {
+        if validity.definitely_all_null() {
             return Ok(ExecutionResult::done(
                 ConstantArray::new(Scalar::null(array.dtype().as_nullable()), array.len())
                     .into_array(),

vortex-array/src/arrays/primitive/array/top_value.rs

@@ -17,7 +17,6 @@ use crate::arrays::primitive::NativeValue;
 use crate::dtype::NativePType;
 use crate::match_each_native_ptype;
 use crate::scalar::PValue;
-use crate::validity::Validity;
 
 impl PrimitiveArray {
     /// Compute most common present value of this array
@@ -26,7 +25,7 @@ impl PrimitiveArray {
             return Ok(None);
         }
 
-        if matches!(self.validity()?, Validity::AllInvalid) {
+        if self.validity()?.definitely_all_null() {
             return Ok(None);
         }
 

vortex-array/src/arrays/varbin/array.rs

@@ -255,7 +255,7 @@ impl VarBinData {
             }
             _ => None,
         };
-        let all_invalid = matches!(validity, Validity::AllInvalid);
+        let all_invalid = validity.definitely_all_null();
 
         match_each_integer_ptype!(primitive_offsets.dtype().as_ptype(), |O| {
             let offsets_slice = primitive_offsets.as_slice::<O>();

vortex-array/src/scalar_fn/fns/fill_null/kernel.rs

@@ -79,7 +79,7 @@ pub(super) fn precondition(
     }
 
     // If all values are null, replace the entire array with the fill value.
-    if matches!(array.validity()?, Validity::AllInvalid) {
+    if array.validity()?.definitely_all_null() {
         return Ok(Some(
             ConstantArray::new(fill_value.clone(), array.len()).into_array(),
         ));

vortex-array/src/scalar_fn/fns/list_contains/mod.rs

@@ -415,7 +415,7 @@ fn list_is_not_empty(
     ctx: &mut ExecutionCtx,
 ) -> VortexResult<ArrayRef> {
     // Short-circuit for all invalid.
-    if matches!(list_array.validity()?, Validity::AllInvalid) {
+    if list_array.validity()?.definitely_all_null() {
         return Ok(ConstantArray::new(
             Scalar::null(DType::Bool(Nullability::Nullable)),
             list_array.len(),

vortex-array/src/validity.rs

@@ -123,6 +123,19 @@ impl Validity {
         matches!(self, Self::NonNullable | Self::AllValid)
     }
 
+    /// Returns `true` if this validity is *definitely* all-null (every value is null), i.e. it
+    /// is [`Validity::AllInvalid`].
+    ///
+    /// Returning `false` does not prove that any value is valid: a [`Validity::Array`] may still
+    /// resolve to all-null once executed. Callers must treat `false` as "unknown without
+    /// compute". For a definitive answer, execute the validity with [`Self::execute_mask`] and
+    /// check whether the resulting [`Mask`] is all-false (`Mask::all_false`). This is the
+    /// all-null counterpart to [`Self::definitely_no_nulls`].
+    #[inline]
+    pub fn definitely_all_null(&self) -> bool {
+        matches!(self, Self::AllInvalid)
+    }
+
     /// Returns whether this validity contains no null values, executing the validity array if
     /// necessary.
     ///

vortex-cuda/src/dynamic_dispatch/mod.rs

@@ -32,7 +32,6 @@ use vortex::array::buffer::BufferHandle;
 use vortex::array::buffer::DeviceBufferExt;
 use vortex::array::match_each_unsigned_integer_ptype;
 use vortex::array::scalar::Scalar;
-use vortex::array::validity::Validity;
 use vortex::buffer::Alignment;
 use vortex::buffer::ByteBuffer;
 use vortex::buffer::ByteBufferMut;
@@ -434,7 +433,7 @@ impl MaterializedPlan {
         let output_ptype = self.dispatch_plan.output_ptype();
 
         // All values are null — no need to touch the GPU.
-        if matches!(self.validity, Validity::AllInvalid) {
+        if self.validity.definitely_all_null() {
             let dtype = DType::Primitive(output_ptype, Nullability::Nullable);
             return ConstantArray::new(Scalar::null(dtype), len)
                 .into_array()

vortex-cuda/src/kernel/encodings/date_time_parts.rs

@@ -72,7 +72,7 @@ impl CudaExecute for DateTimePartsExecutor {
             return Ok(Canonical::empty(array.dtype()));
         }
 
-        if matches!(validity, Validity::AllInvalid) {
+        if validity.definitely_all_null() {
             let storage_ptype = ext.storage_dtype().as_ptype();
             return Ok(Canonical::Extension(
                 TemporalArray::new_timestamp(

vortex-cuda/src/kernel/encodings/fsst.rs

@@ -23,7 +23,6 @@ use vortex::array::arrays::varbinview::build_views::build_views;
 use vortex::array::buffer::DeviceBuffer;
 use vortex::array::match_each_integer_ptype;
 use vortex::array::match_each_unsigned_integer_ptype;
-use vortex::array::validity::Validity;
 use vortex::buffer::Alignment;
 use vortex::buffer::Buffer;
 use vortex::dtype::NativePType;
@@ -62,7 +61,7 @@ impl CudaExecute for FSSTExecutor {
         let dtype = fsst.dtype().clone();
         let validity = fsst.codes().validity()?;
 
-        if fsst.is_empty() || matches!(validity, Validity::AllInvalid) {
+        if fsst.is_empty() || validity.definitely_all_null() {
             let empty = unsafe {
                 VarBinViewArray::new_unchecked(
                     Buffer::<BinaryView>::zeroed(fsst.len()),