Skip to content

Commit 71d4088

Browse files
committed
docs(array): tighten the cast nullability docs
Signed-off-by: Connor Tsui <[email protected]> Claude-Session: https://claude.ai/code/session_01V1YHcosAAKufkyKPorUC2n
1 parent 16bb8b8 commit 71d4088

3 files changed

Lines changed: 15 additions & 33 deletions

File tree

‎vortex-array/src/compute/conformance/cast.rs‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,9 +41,8 @@ fn cast_and_execute(
4141
/// - Casting between string types (Utf8/Binary)
4242
/// - Edge cases like overflow behavior
4343
///
44-
/// The tests of an encoding that supports nullable dtypes **must** also pass a partially valid
45-
/// array. Its cast to the non-nullable dtype fails, which checks the nullability contract of
46-
/// [`CastReduce`].
44+
/// An encoding that supports nullable dtypes **must** also pass a partially valid array, which
45+
/// checks the nullability contract of [`CastReduce`].
4746
///
4847
/// [`CastReduce`]: crate::scalar_fn::fns::cast::CastReduce
4948
pub fn test_cast_conformance(array: &ArrayRef, ctx: &mut ExecutionCtx) {

‎vortex-array/src/scalar_fn/fns/cast/kernel.rs‎

Lines changed: 9 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -25,33 +25,22 @@ use crate::scalar_fn::fns::cast::Cast;
2525
///
2626
/// # Nullability
2727
///
28-
/// A cast to a non-nullable dtype **must** fail when the array has a null row. A rule runs in the
29-
/// optimizer and cannot execute, so it cannot count the nulls of a validity array. A rule that
30-
/// removes nullability takes one of two forms:
28+
/// A cast to a non-nullable dtype **must** fail when the array has a null row. A rule cannot
29+
/// execute, so it handles this in one of two ways:
3130
///
32-
/// - **The rule builds the new validity.** The rules of [`Primitive`] and [`Decimal`] build a new
33-
/// [`Validity`] for their result. Such a rule **must** call
34-
/// [`Validity::trivially_cast_nullability`] and return `Ok(None)` when that call returns
35-
/// `Ok(None)`. The encoding then also implements [`CastKernel`], which checks the nulls at
36-
/// execution with [`Validity::cast_nullability`].
37-
/// - **The rule pushes the cast into its children.** The rules of FoR and DecimalByteParts cast the
38-
/// children that hold their validity and rebuild themselves over the results. The casts of the
39-
/// children check the nulls, so the rule needs no check of its own. This form **requires** that
40-
/// each null in those children appears as a null row of the array, and that each null row of
41-
/// the array comes from a null in those children.
31+
/// - It builds a new [`Validity`], as [`Primitive`] does. It **must** return `Ok(None)` when
32+
/// [`Validity::trivially_cast_nullability`] does, and the encoding implements [`CastKernel`] for
33+
/// that case.
34+
/// - It pushes the cast into the children that hold its validity, as FoR does, and the casts of
35+
/// those children check the nulls. Every null in those children **must** reach a row of the
36+
/// array. The values of [`Dict`] break this with nulls that no code references.
4237
///
43-
/// [`Dict`] does not meet the requirement of the second form. Its values can hold nulls that no
44-
/// code references, so a cast of the values can fail for a dictionary without null rows. The rule
45-
/// of [`Dict`] proves that the values have no nulls before it pushes a cast to non-nullable.
46-
///
47-
/// [`test_cast_conformance`] checks both forms when it receives a partially valid array.
38+
/// [`test_cast_conformance`] checks both forms with a partially valid array.
4839
///
4940
/// [`Primitive`]: crate::arrays::Primitive
50-
/// [`Decimal`]: crate::arrays::Decimal
5141
/// [`Dict`]: crate::arrays::Dict
5242
/// [`Validity`]: crate::validity::Validity
5343
/// [`Validity::trivially_cast_nullability`]: crate::validity::Validity::trivially_cast_nullability
54-
/// [`Validity::cast_nullability`]: crate::validity::Validity::cast_nullability
5544
/// [`test_cast_conformance`]: crate::compute::conformance::cast::test_cast_conformance
5645
pub trait CastReduce: VTable {
5746
fn cast(array: ArrayView<'_, Self>, dtype: &DType) -> VortexResult<Option<ArrayRef>>;

‎vortex-array/src/validity.rs‎

Lines changed: 4 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -429,10 +429,8 @@ impl Validity {
429429

430430
/// Convert into a variant compatible with the given nullability.
431431
///
432-
/// This is the execution-time half of the nullability-cast pair. A [`CastKernel`] calls this
433-
/// method, which can execute the validity array to compute its minimum. The optimizer-time
434-
/// half is [`Self::trivially_cast_nullability`]. [`CastReduce`] documents which cast rules
435-
/// need the pair.
432+
/// Unlike [`Self::trivially_cast_nullability`], this can execute the validity array, so a
433+
/// [`CastKernel`] calls it. [`CastReduce`] documents when a cast rule needs the pair.
436434
///
437435
/// Returns `Err` when nullability cannot be cast (for example, casting to non-nullable while
438436
/// invalid values are present).
@@ -456,11 +454,8 @@ impl Validity {
456454

457455
/// Best-effort, non-executing variant of [`Self::cast_nullability`].
458456
///
459-
/// A [`CastReduce`] rule that builds a new [`Validity`] calls this method, because the rule
460-
/// runs in the optimizer and cannot execute. When this method returns `Ok(None)`, the rule
461-
/// returns `Ok(None)` and the [`CastKernel`] of the encoding handles the cast at execution. A
462-
/// rule that pushes the cast into the children that hold its validity does not call this
463-
/// method. [`CastReduce`] documents both forms of rule.
457+
/// A [`CastReduce`] rule that builds a new [`Validity`] calls this, because a rule cannot
458+
/// execute.
464459
///
465460
/// Return values:
466461
/// - `Ok(Some(_))` — the cast is provably safe and the new [`Validity`] is returned.
@@ -479,7 +474,6 @@ impl Validity {
479474
/// };
480475
/// ```
481476
///
482-
/// [`CastKernel`]: crate::scalar_fn::fns::cast::CastKernel
483477
/// [`CastReduce`]: crate::scalar_fn::fns::cast::CastReduce
484478
#[inline]
485479
pub fn trivially_cast_nullability(

0 commit comments

Comments
 (0)