Method FromPositiveReal

cpp/src/arrow/util/decimal.cc:114–239

  template <typename Real>
  static Result<DecimalType> FromPositiveReal(Real real, int32_t precision,
                                              int32_t scale) {
    constexpr int kMantissaBits = RealTraits<Real>::kMantissaBits;
    constexpr int kMantissaDigits = RealTraits<Real>::kMantissaDigits;

    // to avoid precision and rounding issues, we'll unconditionally
    // throw Decimal32 to the approx algorithm instead. (GH-44216)
    if constexpr (std::is_base_of_v<BasicDecimal32, DecimalType>) {
      return Derived::FromPositiveRealApprox(real, precision, scale);
    }

    // Problem statement: construct the Decimal with the value
    // closest to `real * 10^scale`.
    if (scale < 0) {
      // Negative scales are not handled below, fall back to approx algorithm
      return Derived::FromPositiveRealApprox(real, precision, scale);
    }

    // 1. Check that `real` is within acceptable bounds.
    const Real limit = PowerOfTen<Real>(precision - scale);
    if (real > limit) {
      // Checking the limit early helps ensure the computations below do not
      // overflow.
      // NOTE: `limit` is allowed here as rounding can make it smaller than
      // the theoretical limit (for example, 1.0e23 < 10^23).
      return OverflowError(real, precision, scale);
    }

    // The algorithm below requires the destination decimal type
    // to be strictly more precise than the source float type
    // (see `kSafeMulByTenTo` calculation).
    if constexpr (kMaxPrecision <= kMantissaDigits) {
      return Derived::FromPositiveRealApprox(real, precision, scale);
    }

    // 2. Losslessly convert `real` to `mant * 2**k`
    int binary_exp = 0;
    const Real real_mant = std::frexp(real, &binary_exp);
    // `real_mant` is within 0.5 and 1 and has M bits of precision.
    // Multiply it by 2^M to get an exact integer.
    const uint64_t mant = static_cast<uint64_t>(std::ldexp(real_mant, kMantissaBits));
    const int k = binary_exp - kMantissaBits;
    // (note that `real = mant * 2^k`)

    // 3. Start with `mant`.
    // We want to end up with `real * 10^scale` i.e. `mant * 2^k * 10^scale`.
    DecimalType x(mant);

    if (k < 0) {
      // k < 0 (i.e. binary_exp < kMantissaBits), is probably the common case
      // when converting to decimal. It implies right-shifting by -k bits,
      // while multiplying by 10^scale. We also must avoid overflow (losing
      // bits on the left) and precision loss (losing bits on the right).
      int right_shift_by = -k;
      int mul_by_ten_to = scale;

      // At this point, `x` has kMantissaDigits significant digits but it can
      // fit kMaxPrecision (excluding sign). We can therefore multiply by up