Skip to main content

vortex_array/arrays/widen/encode/
integer.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Integer narrowing that preserves signedness and excludes null payloads.
5//!
6//! Encoding and the deprecated dtype-changing helper share this implementation so they select the
7//! same storage type for each valid-value range.
8
9use std::ops::RangeInclusive;
10
11use vortex_error::VortexExpect;
12use vortex_error::VortexResult;
13use vortex_error::vortex_ensure;
14
15use crate::ArrayRef;
16use crate::ExecutionCtx;
17use crate::IntoArray;
18use crate::aggregate_fn::NumericalAggregateOpts;
19use crate::aggregate_fn::fns::min_max::MinMaxResult;
20use crate::aggregate_fn::fns::min_max::min_max;
21use crate::arrays::PrimitiveArray;
22use crate::arrays::WidenArray;
23use crate::arrays::widen::compute::wrap_values;
24use crate::builtins::ArrayBuiltins;
25use crate::dtype::DType;
26use crate::dtype::PType;
27use crate::scalar::PValue;
28
29impl WidenArray {
30    /// Stores `array` as a `Widen` over the smallest integer type with the same signedness that
31    /// holds its valid values, or returns `array` unchanged when no narrower type holds them.
32    ///
33    /// Null rows do not count, so their payloads can be outside the stored type, and an empty or
34    /// all-null array gets a 1-byte type. Fails when `array` is not an integer array.
35    pub fn encode(array: PrimitiveArray, ctx: &mut ExecutionCtx) -> VortexResult<ArrayRef> {
36        let dtype = array.dtype().clone();
37        wrap_values(narrow_values(array, ctx)?.into_array(), dtype)
38    }
39
40    /// Returns `array` cast to the type that [`Self::encode`] chooses for its values, without a
41    /// `Widen` around them.
42    ///
43    /// The result keeps the signedness and the validity of `array`, but its dtype can be narrower.
44    /// A float array returns unchanged, where [`Self::encode`] fails. This is for an internal child
45    /// whose parent chooses its dtype, such as list offsets or dictionary codes. An array whose
46    /// dtype is fixed, such as a column, needs [`Self::encode`] instead.
47    #[deprecated(
48        note = "Changes the dtype. Each caller must decide whether it needs a Widen (#10733)"
49    )]
50    pub fn encode_values(
51        array: PrimitiveArray,
52        ctx: &mut ExecutionCtx,
53    ) -> VortexResult<PrimitiveArray> {
54        if !array.ptype().is_int() {
55            return Ok(array);
56        }
57
58        narrow_values(array, ctx)
59    }
60}
61
62/// Returns `array` cast to the stored type that [`WidenArray::encode`] chooses, or `array`
63/// unchanged when no narrower type holds its valid values.
64///
65/// [`WidenArray::encode`] and the deprecated [`WidenArray::encode_values`] share this function,
66/// so that `encode` needs no `#[expect(deprecated)]`. Fails when `array` is not an integer array.
67fn narrow_values(array: PrimitiveArray, ctx: &mut ExecutionCtx) -> VortexResult<PrimitiveArray> {
68    let ptype = array.ptype();
69    vortex_ensure!(ptype.is_int(), "Widen requires integer values, got {ptype}");
70
71    // No integer type is narrower than one byte, so the bounds cannot change the result.
72    if ptype.byte_width() == 1 {
73        return Ok(array);
74    }
75
76    // An array without valid values fits any type, and the bounds `0..=0` select the 1-byte type.
77    let bounds = match min_max(array.as_ref(), ctx, NumericalAggregateOpts::default())? {
78        Some(bounds) => integer_extrema(bounds),
79        None => 0..=0,
80    };
81    let Some(stored_ptype) = smallest_integer_ptype(bounds, ptype.is_signed_int())
82        .filter(|stored_ptype| stored_ptype.byte_width() < ptype.byte_width())
83    else {
84        return Ok(array);
85    };
86
87    let stored_dtype = DType::Primitive(stored_ptype, array.dtype().nullability());
88    array
89        .into_array()
90        .cast(stored_dtype)?
91        .execute::<PrimitiveArray>(ctx)
92}
93
94/// Widens integer extrema to `i128`, which holds every integer [`PValue`] exactly.
95///
96/// Both extrema **must** be non-null integers, as returned by [`min_max`] on an integer array.
97pub(in crate::arrays::widen) fn integer_extrema(bounds: MinMaxResult) -> RangeInclusive<i128> {
98    let [min, max] = [bounds.min, bounds.max].map(|bound| {
99        bound
100            .as_primitive()
101            .pvalue()
102            .and_then(PValue::as_i128)
103            .vortex_expect("min_max of an integer array returns non-null integer extrema")
104    });
105
106    min..=max
107}
108
109/// Returns the smallest integer type with the given signedness that holds every value in `bounds`,
110/// or `None` when no integer type of at most 64 bits holds them.
111pub(in crate::arrays::widen) fn smallest_integer_ptype(
112    bounds: RangeInclusive<i128>,
113    signed: bool,
114) -> Option<PType> {
115    let (min, max) = bounds.into_inner();
116    if signed {
117        let min_ptype = PType::min_signed_ptype_for_value(i64::try_from(min).ok()?);
118        let max_ptype = PType::min_signed_ptype_for_value(i64::try_from(max).ok()?);
119        Some(min_ptype.max_signed_ptype(max_ptype))
120    } else {
121        let min_ptype = PType::min_unsigned_ptype_for_value(u64::try_from(min).ok()?);
122        let max_ptype = PType::min_unsigned_ptype_for_value(u64::try_from(max).ok()?);
123        Some(min_ptype.max_unsigned_ptype(max_ptype))
124    }
125}