|
| 1 | +// SPDX-License-Identifier: Apache-2.0 |
| 2 | +// SPDX-FileCopyrightText: Copyright the Vortex contributors |
| 3 | + |
| 4 | +//! Arrow's decimal arithmetic rules, and their evaluation over [`DecimalValue`]. |
| 5 | +//! |
| 6 | +//! Vortex coerces both operands of a decimal arithmetic expression to a single [`DecimalDType`], |
| 7 | +//! so Arrow's general `(p1, s1) op (p2, s2)` formulas collapse to a function of one input type: |
| 8 | +//! |
| 9 | +//! | operator | result precision | result scale | |
| 10 | +//! | -------- | ---------------- | ------------ | |
| 11 | +//! | Add, Sub | `p + 1` | `s` | |
| 12 | +//! | Mul | `2p + 1` | `2s` | |
| 13 | +//! | Div | `p + s + 4` | `s + 4` | |
| 14 | +//! |
| 15 | +//! Precision saturates at [`MAX_PRECISION`]. Because Mul widens the scale, the product of the |
| 16 | +//! stored integers already sits at the result scale and no rounding is needed. Div instead scales |
| 17 | +//! the dividend up front and truncates toward zero, which is what Arrow does. |
| 18 | +//! |
| 19 | +//! Div is the one operator whose intermediate can outgrow the widest native width: scaling the |
| 20 | +//! dividend by `10^result_scale` overflows `i256` once `p + result_scale` passes |
| 21 | +//! [`MAX_PRECISION`], even for a quotient that would have fit the result precision. That is |
| 22 | +//! reported as an overflow. The array kernels derive their working width the same way, so both |
| 23 | +//! paths agree on which operations are representable. |
| 24 | +
|
| 25 | +use num_traits::CheckedAdd; |
| 26 | +use num_traits::CheckedDiv; |
| 27 | +use num_traits::CheckedMul; |
| 28 | +use num_traits::CheckedSub; |
| 29 | +use vortex_error::VortexResult; |
| 30 | +use vortex_error::vortex_bail; |
| 31 | +use vortex_error::vortex_err; |
| 32 | + |
| 33 | +use crate::dtype::BigCast; |
| 34 | +use crate::dtype::DecimalDType; |
| 35 | +use crate::dtype::MAX_PRECISION; |
| 36 | +use crate::dtype::MAX_SCALE; |
| 37 | +use crate::dtype::NativeDecimalType; |
| 38 | +use crate::match_each_decimal_value_type; |
| 39 | +use crate::scalar::DecimalValue; |
| 40 | +use crate::scalar::NumericOperator; |
| 41 | + |
| 42 | +/// Derive the result decimal dtype of a numeric operation over two operands of `input`. |
| 43 | +/// |
| 44 | +/// # Errors |
| 45 | +/// |
| 46 | +/// Returns an error if the operation has no valid result type: a Mul whose doubled scale is |
| 47 | +/// unrepresentable — above [`MAX_SCALE`], or below the `i8::MIN` floor of the scale field — or a |
| 48 | +/// Div whose precision would fall outside the legal range. |
| 49 | +pub(crate) fn decimal_numeric_result_dtype( |
| 50 | + input: DecimalDType, |
| 51 | + op: NumericOperator, |
| 52 | +) -> VortexResult<DecimalDType> { |
| 53 | + match op { |
| 54 | + NumericOperator::Add | NumericOperator::Sub => { |
| 55 | + // A p-digit Add/Sub result needs at most one carry digit: |
| 56 | + // 2 * (10^p - 1) < 10^(p + 1). |
| 57 | + Ok(DecimalDType::new( |
| 58 | + input.precision().saturating_add(1).min(MAX_PRECISION), |
| 59 | + input.scale(), |
| 60 | + )) |
| 61 | + } |
| 62 | + NumericOperator::Mul => { |
| 63 | + // Doubling the scale in i8 would saturate a very negative sum into a legal-looking |
| 64 | + // scale, so widen first. The SQL standard rejects a product whose scale cannot be |
| 65 | + // represented rather than rounding it away. |
| 66 | + let result_scale = <i16 as From<i8>>::from(input.scale()) * 2; |
| 67 | + let Some(result_scale) = i8::try_from(result_scale) |
| 68 | + .ok() |
| 69 | + .filter(|scale| *scale <= MAX_SCALE) |
| 70 | + else { |
| 71 | + vortex_bail!( |
| 72 | + "output scale {result_scale} of {input} {op} {input} is outside the \ |
| 73 | + representable scale range of {} to {MAX_SCALE}", |
| 74 | + i8::MIN |
| 75 | + ); |
| 76 | + }; |
| 77 | + let result_precision = input |
| 78 | + .precision() |
| 79 | + .saturating_add(input.precision().saturating_add(1)) |
| 80 | + .min(MAX_PRECISION); |
| 81 | + DecimalDType::try_new(result_precision, result_scale) |
| 82 | + } |
| 83 | + NumericOperator::Div => { |
| 84 | + // Arrow follows Postgres and MySQL in adding a fixed four fractional digits. Its |
| 85 | + // precision formula `p1 - s1 + s2 + result_scale` simplifies to `p + result_scale` |
| 86 | + // once both operands share a dtype. |
| 87 | + let result_scale = input.scale().saturating_add(4).min(MAX_SCALE); |
| 88 | + let result_precision = |
| 89 | + <i16 as From<u8>>::from(input.precision()) + <i16 as From<i8>>::from(result_scale); |
| 90 | + let result_precision = u8::try_from(result_precision).map_err(|_| { |
| 91 | + vortex_err!( |
| 92 | + InvalidArgument: |
| 93 | + "decimal division result precision {result_precision} is invalid" |
| 94 | + ) |
| 95 | + })?; |
| 96 | + DecimalDType::try_new(result_precision.min(MAX_PRECISION), result_scale) |
| 97 | + } |
| 98 | + } |
| 99 | +} |
| 100 | + |
| 101 | +/// Apply `op` to two stored values of `input`, returning the result stored in `result`'s width. |
| 102 | +/// |
| 103 | +/// Returns `None` if the result overflows `result`'s precision, or if `op` is a division by zero. |
| 104 | +pub(crate) fn checked_decimal_numeric( |
| 105 | + lhs: DecimalValue, |
| 106 | + rhs: DecimalValue, |
| 107 | + input: DecimalDType, |
| 108 | + result: DecimalDType, |
| 109 | + op: NumericOperator, |
| 110 | +) -> Option<DecimalValue> { |
| 111 | + let work = work_decimal_dtype(input, result, op); |
| 112 | + match_each_decimal_value_type!(DecimalType::smallest_decimal_value_type(&work), |W| { |
| 113 | + let value = checked_at_width::<W>(lhs.cast::<W>()?, rhs.cast::<W>()?, result.scale(), op)?; |
| 114 | + DecimalValue::from(value).normalize(result) |
| 115 | + }) |
| 116 | +} |
| 117 | + |
| 118 | +/// Pick a native width wide enough to hold every intermediate of an in-precision operation. |
| 119 | +/// |
| 120 | +/// The result precision covers Add, Sub and Mul, whose intermediates are the result itself. Div |
| 121 | +/// scales the dividend (or the divisor, for a negative result scale) by `10^result_scale` before |
| 122 | +/// dividing, so it needs room for `p + |result_scale|` digits. |
| 123 | +fn work_decimal_dtype( |
| 124 | + input: DecimalDType, |
| 125 | + result: DecimalDType, |
| 126 | + op: NumericOperator, |
| 127 | +) -> DecimalDType { |
| 128 | + let precision = match op { |
| 129 | + NumericOperator::Add | NumericOperator::Sub | NumericOperator::Mul => result.precision(), |
| 130 | + NumericOperator::Div => input |
| 131 | + .precision() |
| 132 | + .saturating_add(result.scale().unsigned_abs()) |
| 133 | + .max(result.precision()) |
| 134 | + .min(MAX_PRECISION), |
| 135 | + }; |
| 136 | + DecimalDType::new(precision, 0) |
| 137 | +} |
| 138 | + |
| 139 | +fn checked_at_width<W>(lhs: W, rhs: W, result_scale: i8, op: NumericOperator) -> Option<W> |
| 140 | +where |
| 141 | + W: NativeDecimalType + CheckedAdd + CheckedSub + CheckedMul + CheckedDiv, |
| 142 | +{ |
| 143 | + match op { |
| 144 | + NumericOperator::Add => lhs.checked_add(&rhs), |
| 145 | + NumericOperator::Sub => lhs.checked_sub(&rhs), |
| 146 | + // The result scale is the sum of the operand scales, so the raw product is already |
| 147 | + // correctly scaled. |
| 148 | + NumericOperator::Mul => lhs.checked_mul(&rhs), |
| 149 | + NumericOperator::Div => { |
| 150 | + // Arrow scales the quotient by `10^(result_scale - lhs_scale + rhs_scale)`, which is |
| 151 | + // `10^result_scale` for equal operand dtypes. A negative exponent scales the divisor |
| 152 | + // instead of the dividend. |
| 153 | + let factor = |
| 154 | + decimal_scale_factor::<W>(<u32 as From<u8>>::from(result_scale.unsigned_abs()))?; |
| 155 | + if result_scale >= 0 { |
| 156 | + lhs.checked_mul(&factor)?.checked_div(&rhs) |
| 157 | + } else { |
| 158 | + lhs.checked_div(&rhs.checked_mul(&factor)?) |
| 159 | + } |
| 160 | + } |
| 161 | + } |
| 162 | +} |
| 163 | + |
| 164 | +/// `10^exp` at width `W`, or `None` if it is not representable there. |
| 165 | +fn decimal_scale_factor<W>(exp: u32) -> Option<W> |
| 166 | +where |
| 167 | + W: NativeDecimalType + CheckedAdd, |
| 168 | +{ |
| 169 | + let max = *W::MAX_BY_PRECISION.get(usize::try_from(exp).ok()?)?; |
| 170 | + max.checked_add(&<W as BigCast>::from(1_i8)?) |
| 171 | +} |
0 commit comments