fluss/row/

decimal.rs

// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

use crate::error::{Error, Result};
use bigdecimal::num_bigint::BigInt;
use bigdecimal::num_traits::Zero;
use bigdecimal::{BigDecimal, RoundingMode};
use std::fmt;

#[cfg(test)]
use std::str::FromStr;

/// Maximum decimal precision that can be stored compactly as a single i64.
/// Values with precision > MAX_COMPACT_PRECISION require byte array storage.
pub const MAX_COMPACT_PRECISION: u32 = 18;

/// An internal data structure representing a decimal value with fixed precision and scale.
///
/// This data structure is immutable and stores decimal values in a compact representation
/// (as a long value) if values are small enough (precision ≤ 18).
///
/// Matches Java's org.apache.fluss.row.Decimal class.
#[derive(Debug, Clone, serde::Serialize)]
pub struct Decimal {
    precision: u32,
    scale: u32,
    // If precision <= MAX_COMPACT_PRECISION, this holds the unscaled value
    long_val: Option<i64>,
    // BigDecimal representation (may be cached)
    decimal_val: Option<BigDecimal>,
}

impl Decimal {
    /// Returns the precision of this Decimal.
    ///
    /// The precision is the number of digits in the unscaled value.
    pub fn precision(&self) -> u32 {
        self.precision
    }

    /// Returns the scale of this Decimal.
    pub fn scale(&self) -> u32 {
        self.scale
    }

    /// Returns whether the decimal value is small enough to be stored in a long.
    pub fn is_compact(&self) -> bool {
        self.precision <= MAX_COMPACT_PRECISION
    }

    /// Returns whether a given precision can be stored compactly.
    pub fn is_compact_precision(precision: u32) -> bool {
        precision <= MAX_COMPACT_PRECISION
    }

    /// Converts this Decimal into a BigDecimal.
    pub fn to_big_decimal(&self) -> BigDecimal {
        if let Some(bd) = &self.decimal_val {
            bd.clone()
        } else if let Some(long_val) = self.long_val {
            BigDecimal::new(BigInt::from(long_val), self.scale as i64)
        } else {
            // Should never happen - we always have one representation
            BigDecimal::new(BigInt::from(0), self.scale as i64)
        }
    }

    /// Returns a long describing the unscaled value of this Decimal.
    pub fn to_unscaled_long(&self) -> Result<i64> {
        if let Some(long_val) = self.long_val {
            Ok(long_val)
        } else {
            // Extract unscaled value from BigDecimal
            let bd = self.to_big_decimal();
            let (unscaled, _) = bd.as_bigint_and_exponent();
            unscaled.try_into().map_err(|_| Error::IllegalArgument {
                message: format!(
                    "Decimal unscaled value does not fit in i64: precision={}",
                    self.precision
                ),
            })
        }
    }

    /// Returns a byte array describing the unscaled value of this Decimal.
    pub fn to_unscaled_bytes(&self) -> Vec<u8> {
        let bd = self.to_big_decimal();
        let (unscaled, _) = bd.as_bigint_and_exponent();
        unscaled.to_signed_bytes_be()
    }

    /// Creates a Decimal from Arrow's Decimal128 representation.
    // TODO: For compact decimals with matching scale we may call from_unscaled_long
    pub fn from_arrow_decimal128(
        i128_val: i128,
        arrow_scale: i64,
        precision: u32,
        scale: u32,
    ) -> Result<Self> {
        let bd = BigDecimal::new(BigInt::from(i128_val), arrow_scale);
        Self::from_big_decimal(bd, precision, scale)
    }

    /// Creates an instance of Decimal from a BigDecimal with the given precision and scale.
    ///
    /// The returned decimal value may be rounded to have the desired scale. The precision
    /// will be checked. If the precision overflows, an error is returned.
    pub fn from_big_decimal(bd: BigDecimal, precision: u32, scale: u32) -> Result<Self> {
        // Rescale to the target scale with HALF_UP rounding (matches Java)
        let scaled = bd.with_scale_round(scale as i64, RoundingMode::HalfUp);

        // Extract unscaled value
        let (unscaled, exp) = scaled.as_bigint_and_exponent();

        // Sanity check that scale matches
        debug_assert_eq!(
            exp, scale as i64,
            "Scaled decimal exponent ({exp}) != expected scale ({scale})"
        );

        let actual_precision = Self::compute_precision(&unscaled);
        if actual_precision > precision as usize {
            return Err(Error::IllegalArgument {
                message: format!(
                    "Decimal precision overflow: value has {actual_precision} digits but precision is {precision} (value: {scaled})"
                ),
            });
        }

        // Compute compact representation if possible
        let long_val = if precision <= MAX_COMPACT_PRECISION {
            Some(i64::try_from(&unscaled).map_err(|_| Error::IllegalArgument {
                message: format!(
                    "Decimal mantissa exceeds i64 range for compact precision {precision}: unscaled={unscaled} (value={scaled})"
                ),
            })?)
        } else {
            None
        };

        Ok(Decimal {
            precision,
            scale,
            long_val,
            decimal_val: Some(scaled),
        })
    }

    /// Creates an instance of Decimal from an unscaled long value with the given precision and scale.
    pub fn from_unscaled_long(unscaled_long: i64, precision: u32, scale: u32) -> Result<Self> {
        if precision > MAX_COMPACT_PRECISION {
            return Err(Error::IllegalArgument {
                message: format!(
                    "Precision {precision} exceeds MAX_COMPACT_PRECISION ({MAX_COMPACT_PRECISION})"
                ),
            });
        }

        let actual_precision = Self::compute_precision(&BigInt::from(unscaled_long));
        if actual_precision > precision as usize {
            return Err(Error::IllegalArgument {
                message: format!(
                    "Decimal precision overflow: unscaled value has {actual_precision} digits but precision is {precision}"
                ),
            });
        }

        Ok(Decimal {
            precision,
            scale,
            long_val: Some(unscaled_long),
            decimal_val: None,
        })
    }

    /// Creates an instance of Decimal from an unscaled byte array with the given precision and scale.
    pub fn from_unscaled_bytes(unscaled_bytes: &[u8], precision: u32, scale: u32) -> Result<Self> {
        let unscaled = BigInt::from_signed_bytes_be(unscaled_bytes);
        let bd = BigDecimal::new(unscaled, scale as i64);
        Self::from_big_decimal(bd, precision, scale)
    }

    /// Computes the precision of a decimal's unscaled value, matching Java's BigDecimal.precision().
    pub fn compute_precision(unscaled: &BigInt) -> usize {
        if unscaled.is_zero() {
            return 1;
        }

        // Count ALL digits in the unscaled value (matches Java's BigDecimal.precision())
        // For bounded precision (≤ 38 digits), string conversion is cheap and simple.
        unscaled.magnitude().to_str_radix(10).len()
    }
}

impl fmt::Display for Decimal {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.to_big_decimal())
    }
}

// Manual implementations of comparison traits to ignore cached fields
impl PartialEq for Decimal {
    fn eq(&self, other: &Self) -> bool {
        // Use numeric equality like Java's Decimal.equals() which delegates to compareTo.
        // This means 1.0 (scale=1) equals 1.00 (scale=2).
        self.cmp(other) == std::cmp::Ordering::Equal
    }
}

impl Eq for Decimal {}

impl PartialOrd for Decimal {
    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for Decimal {
    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
        // If both are compact and have the same scale, compare directly
        if self.is_compact() && other.is_compact() && self.scale == other.scale {
            self.long_val.cmp(&other.long_val)
        } else {
            // Otherwise, compare as BigDecimal
            self.to_big_decimal().cmp(&other.to_big_decimal())
        }
    }
}

impl std::hash::Hash for Decimal {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        // Hash the BigDecimal representation.
        //
        // IMPORTANT: Unlike Java's BigDecimal, Rust's bigdecimal crate normalizes
        // before hashing, so hash(1.0) == hash(1.00). Combined with our numeric
        // equality (1.0 == 1.00), this CORRECTLY satisfies the hash/equals contract.
        //
        // This is BETTER than Java's implementation which has a hash/equals violation:
        // - Java: equals(1.0, 1.00) = true, but hashCode(1.0) != hashCode(1.00)
        // - Rust: equals(1.0, 1.00) = true, and hash(1.0) == hash(1.00) ✓
        //
        // Result: HashMap/HashSet will work correctly even if you create Decimals
        // with different scales for the same numeric value (though this is rare in
        // practice since decimals are schema-driven with fixed precision/scale).
        self.to_big_decimal().hash(state);
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_precision_calculation() {
        // Zero is special case
        assert_eq!(Decimal::compute_precision(&BigInt::from(0)), 1);

        // Must count ALL digits including trailing zeros (matches Java BigDecimal.precision())
        assert_eq!(Decimal::compute_precision(&BigInt::from(10)), 2);
        assert_eq!(Decimal::compute_precision(&BigInt::from(100)), 3);
        assert_eq!(Decimal::compute_precision(&BigInt::from(12300)), 5);
        assert_eq!(
            Decimal::compute_precision(&BigInt::from(10000000000i64)),
            11
        );

        // Test the case: value=1, scale=10 → unscaled=10000000000 (11 digits)
        let bd = BigDecimal::new(BigInt::from(1), 0);
        assert!(
            Decimal::from_big_decimal(bd.clone(), 1, 10).is_err(),
            "Should reject: unscaled 10000000000 has 11 digits, precision=1 is too small"
        );
        assert!(
            Decimal::from_big_decimal(bd, 11, 10).is_ok(),
            "Should accept with correct precision=11"
        );
    }

    /// Test precision validation boundaries
    #[test]
    fn test_precision_validation() {
        let test_cases = vec![
            (10i64, 1, 2),            // 1.0 → unscaled: 10 (2 digits)
            (100i64, 2, 3),           // 1.00 → unscaled: 100 (3 digits)
            (10000000000i64, 10, 11), // 1.0000000000 → unscaled: 10000000000 (11 digits)
        ];

        for (unscaled, scale, min_precision) in test_cases {
            let bd = BigDecimal::new(BigInt::from(unscaled), scale as i64);

            // Reject if precision too small
            assert!(Decimal::from_big_decimal(bd.clone(), min_precision - 1, scale).is_err());
            // Accept with correct precision
            assert!(Decimal::from_big_decimal(bd, min_precision, scale).is_ok());
        }

        // i64::MAX has 19 digits, should reject with precision=5
        let bd = BigDecimal::new(BigInt::from(i64::MAX), 0);
        assert!(Decimal::from_big_decimal(bd, 5, 0).is_err());
    }

    /// Test creation and basic operations for both compact and non-compact decimals
    #[test]
    fn test_creation_and_representation() {
        // Compact (precision ≤ 18): from unscaled long
        let compact = Decimal::from_unscaled_long(12345, 10, 2).unwrap();
        assert_eq!(compact.precision(), 10);
        assert_eq!(compact.scale(), 2);
        assert!(compact.is_compact());
        assert_eq!(compact.to_unscaled_long().unwrap(), 12345);
        assert_eq!(compact.to_big_decimal().to_string(), "123.45");

        // Non-compact (precision > 18): from BigDecimal
        let bd = BigDecimal::new(BigInt::from(12345), 0);
        let non_compact = Decimal::from_big_decimal(bd, 28, 0).unwrap();
        assert_eq!(non_compact.precision(), 28);
        assert!(!non_compact.is_compact());
        assert_eq!(
            non_compact.to_unscaled_bytes(),
            BigInt::from(12345).to_signed_bytes_be()
        );

        // Test compact boundary
        assert!(Decimal::is_compact_precision(18));
        assert!(!Decimal::is_compact_precision(19));

        // Test rounding during creation
        let bd = BigDecimal::new(BigInt::from(12345), 3); // 12.345
        let rounded = Decimal::from_big_decimal(bd, 10, 2).unwrap();
        assert_eq!(rounded.to_unscaled_long().unwrap(), 1235); // 12.35
    }

    /// Test serialization round-trip (unscaled bytes)
    #[test]
    fn test_serialization_roundtrip() {
        // Compact decimal
        let bd1 = BigDecimal::new(BigInt::from(1314567890123i64), 5); // 13145678.90123
        let decimal1 = Decimal::from_big_decimal(bd1.clone(), 15, 5).unwrap();
        let (unscaled1, _) = bd1.as_bigint_and_exponent();
        let from_bytes1 =
            Decimal::from_unscaled_bytes(&unscaled1.to_signed_bytes_be(), 15, 5).unwrap();
        assert_eq!(from_bytes1, decimal1);
        assert_eq!(
            from_bytes1.to_unscaled_bytes(),
            unscaled1.to_signed_bytes_be()
        );

        // Non-compact decimal
        let bd2 = BigDecimal::new(BigInt::from(12345678900987654321i128), 10);
        let decimal2 = Decimal::from_big_decimal(bd2.clone(), 23, 10).unwrap();
        let (unscaled2, _) = bd2.as_bigint_and_exponent();
        let from_bytes2 =
            Decimal::from_unscaled_bytes(&unscaled2.to_signed_bytes_be(), 23, 10).unwrap();
        assert_eq!(from_bytes2, decimal2);
        assert_eq!(
            from_bytes2.to_unscaled_bytes(),
            unscaled2.to_signed_bytes_be()
        );
    }

    /// Test numeric equality and ordering (matches Java semantics)
    #[test]
    fn test_equality_and_ordering() {
        // Same value, different precision/scale → should be equal (numeric equality)
        let d1 = Decimal::from_big_decimal(BigDecimal::new(BigInt::from(10), 1), 2, 1).unwrap(); // 1.0
        let d2 = Decimal::from_big_decimal(BigDecimal::new(BigInt::from(100), 2), 3, 2).unwrap(); // 1.00
        assert_eq!(d1, d2, "Numeric equality: 1.0 == 1.00");
        assert_eq!(d1.cmp(&d2), std::cmp::Ordering::Equal);

        // Test ordering with positive values
        let small = Decimal::from_unscaled_long(10, 5, 0).unwrap();
        let large = Decimal::from_unscaled_long(15, 5, 0).unwrap();
        assert!(small < large);
        assert_eq!(small.cmp(&large), std::cmp::Ordering::Less);

        // Test ordering with negative values
        let negative_large = Decimal::from_unscaled_long(-10, 5, 0).unwrap(); // -10
        let negative_small = Decimal::from_unscaled_long(-15, 5, 0).unwrap(); // -15
        assert!(negative_small < negative_large); // -15 < -10
        assert_eq!(
            negative_small.cmp(&negative_large),
            std::cmp::Ordering::Less
        );

        // Test ordering with mixed positive and negative
        let positive = Decimal::from_unscaled_long(5, 5, 0).unwrap();
        let negative = Decimal::from_unscaled_long(-5, 5, 0).unwrap();
        assert!(negative < positive);
        assert_eq!(negative.cmp(&positive), std::cmp::Ordering::Less);

        // Test clone and round-trip equality
        let original = Decimal::from_unscaled_long(10, 5, 0).unwrap();
        assert_eq!(original.clone(), original);
        assert_eq!(
            Decimal::from_unscaled_long(original.to_unscaled_long().unwrap(), 5, 0).unwrap(),
            original
        );
    }

    /// Test hash/equals contract (Rust implementation is correct, unlike Java)
    #[test]
    fn test_hash_equals_contract() {
        use std::collections::hash_map::DefaultHasher;
        use std::hash::{Hash, Hasher};

        let d1 = Decimal::from_big_decimal(BigDecimal::new(BigInt::from(10), 1), 2, 1).unwrap(); // 1.0
        let d2 = Decimal::from_big_decimal(BigDecimal::new(BigInt::from(100), 2), 3, 2).unwrap(); // 1.00

        // Numeric equality
        assert_eq!(d1, d2);

        // Hash contract: if a == b, then hash(a) == hash(b)
        let mut hasher1 = DefaultHasher::new();
        d1.hash(&mut hasher1);
        let hash1 = hasher1.finish();

        let mut hasher2 = DefaultHasher::new();
        d2.hash(&mut hasher2);
        let hash2 = hasher2.finish();

        assert_eq!(hash1, hash2, "Equal decimals must have equal hashes");

        // Verify HashMap works correctly (this would fail in Java due to their hash/equals bug)
        let mut map = std::collections::HashMap::new();
        map.insert(d1.clone(), "value");
        assert_eq!(map.get(&d2), Some(&"value"));
    }

    /// Test edge cases: zeros, large numbers, rescaling
    #[test]
    fn test_edge_cases() {
        // Zero handling (compact and non-compact)
        let zero_compact = Decimal::from_unscaled_long(0, 5, 2).unwrap();
        assert_eq!(
            zero_compact.to_big_decimal(),
            BigDecimal::new(BigInt::from(0), 2)
        );

        let zero_non_compact =
            Decimal::from_big_decimal(BigDecimal::new(BigInt::from(0), 2), 20, 2).unwrap();
        assert_eq!(
            zero_non_compact.to_big_decimal(),
            BigDecimal::new(BigInt::from(0), 2)
        );

        // Large number (39 digits)
        let large_bd = BigDecimal::from_str("123456789012345678901234567890123456789").unwrap();
        let large = Decimal::from_big_decimal(large_bd, 39, 0).unwrap();
        let double_val = large.to_big_decimal().to_string().parse::<f64>().unwrap();
        assert!((double_val - 1.2345678901234568E38).abs() < 0.01);

        // Rescaling: 5.0 (scale=1) → 5.00 (scale=2)
        let d1 = Decimal::from_big_decimal(BigDecimal::new(BigInt::from(50), 1), 10, 1).unwrap();
        let d2 = Decimal::from_big_decimal(d1.to_big_decimal(), 10, 2).unwrap();
        assert_eq!(d2.to_big_decimal().to_string(), "5.00");
        assert_eq!(d2.scale(), 2);
    }
}