Skip to main content

vortex_array/arrays/widen/
array.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_error::vortex_ensure;
7
8use crate::ArrayRef;
9use crate::EmptyArrayData;
10use crate::array::ArrayParts;
11use crate::array_slots;
12use crate::arrays::Widen;
13use crate::arrays::WidenArray;
14use crate::dtype::DType;
15
16/// The child slots of a [`WidenArray`].
17#[array_slots(Widen)]
18pub struct WidenSlots {
19    /// The stored values, with a canonical width strictly narrower than the logical dtype.
20    #[slot(0)]
21    pub values: ArrayRef,
22}
23
24impl WidenArray {
25    /// Creates a `Widen` that presents `values` with the wider logical `dtype`, without reading
26    /// any values.
27    ///
28    /// `values` and `dtype` **must** both be integers with the same signedness, or decimals with
29    /// the same scale. They **must** have the same nullability, and the canonical width of `values`
30    /// **must** be strictly narrower. When `values` is itself a `Widen`, the new array stores its
31    /// values instead, so that `Widen` arrays do not nest.
32    ///
33    /// A decimal child **must** be a valid decimal array for its declared dtype. Comparisons,
34    /// bounds checks and fills rely on this requirement. A violation gives incorrect results,
35    /// but no undefined behavior.
36    pub fn try_new(mut values: ArrayRef, dtype: DType) -> VortexResult<Self> {
37        // NB: Check `values` before the flatten. The values of a `Widen` child are narrower than
38        // the child, so the check in `try_from_parts` alone would accept a child as wide as `dtype`
39        // or wider.
40        validate_dtypes(values.dtype(), &dtype)?;
41
42        while let Some(widen) = values.as_opt::<Widen>() {
43            values = widen.values().clone();
44        }
45
46        let len = values.len();
47        Self::try_from_parts(ArrayParts::new(
48            Widen,
49            dtype,
50            len,
51            EmptyArrayData,
52            WidenSlots { values }.into_slots(),
53        ))
54    }
55}
56
57/// Checks that the dtypes of `values` and `logical` meet the requirements of
58/// [`WidenArray::try_new`].
59pub(super) fn validate_dtypes(values: &DType, logical: &DType) -> VortexResult<()> {
60    match (values, logical) {
61        (DType::Primitive(values_ptype, _), DType::Primitive(logical_ptype, _))
62            if values_ptype.is_int() && logical_ptype.is_int() =>
63        {
64            vortex_ensure!(
65                values_ptype.is_signed_int() == logical_ptype.is_signed_int(),
66                "Widen requires values with the signedness of {logical}, got {values}"
67            );
68            vortex_ensure!(
69                values_ptype.byte_width() < logical_ptype.byte_width(),
70                "Widen requires values narrower than {logical}, got {values}"
71            );
72        }
73        (DType::Decimal(values_decimal, _), DType::Decimal(logical_decimal, _)) => {
74            vortex_ensure!(
75                values_decimal.scale() == logical_decimal.scale(),
76                "Widen requires values with the scale of {logical}, got {values}"
77            );
78            vortex_ensure!(
79                values_decimal.canonical_values_type() < logical_decimal.canonical_values_type(),
80                "Widen requires values narrower than {logical}, got {values}"
81            );
82        }
83        _ => vortex_bail!(
84            "Widen requires integer dtypes or decimal dtypes for {logical}, got {values}"
85        ),
86    }
87
88    vortex_ensure!(
89        values.nullability() == logical.nullability(),
90        "Widen requires values with the nullability of {logical}, got {values}"
91    );
92
93    Ok(())
94}