Merge develop into pratik/ranged-normalize-number-at-construction

The @note comparing this overload to the two-pass path stated where the two
diverge and called the first range "strictly wider". Both were wrong: they also
diverge below kMinExponent, and MantissaScale::Small is the IOU range exactly,
not wider. The comparison is not a contract a caller needs, so drop it rather
than reword it, and state only what the function returns.

include/xrpl/basics/Number.h

@@ -594,7 +594,61 @@ public:
     static InternalRep
     externalToInternal(rep mantissa);
 
+    /**
+     * Normalize raw (mantissa, exponent) integers directly to a target range.
+     *
+     * This is the construction-time counterpart of the member overload above.
+     * Callers that hold raw integers (e.g. IOUAmount) and want them in a
+     * narrow range would otherwise build a Number (one normalize pass to the
+     * default kRange) and then call the member normalizeToRange (a second pass
+     * down to the narrow range). This overload does a single pass: it converts
+     * the signed mantissa to its internal magnitude and normalizes straight to
+     * [MinMantissa, MaxMantissa], building no intermediate Number.
+     *
+     * Data flow (single pass), contrasted with the old two-pass path:
+     *
+     *     two-pass:  (m,e) --build Number--> [kRange/Large] --member--> [Min,Max]
+     *     one-pass:  (m,e) -------------- normalize --------------> [Min,Max]
+     *
+     * @tparam MinMantissa  Lower bound of the target mantissa range; must be a
+     *                      positive power of ten.
+     * @tparam MaxMantissa  Upper bound; must equal MinMantissa * 10 - 1.
+     * @tparam T            Result mantissa type, int64_t or uint64_t. Defaults
+     *                      to the type of MinMantissa.
+     * @param mantissa      Raw signed mantissa (sign is extracted internally).
+     * @param exponent      Raw exponent.
+     * @return  The normalized (mantissa, exponent) pair in the target range.
+     *          A zero mantissa returns {0, std::numeric_limits<int>::lowest()};
+     *          the sign of a zero is not preserved.
+     * @note  Thread-safety: reads the thread-local rounding mode only; holds no
+     *        shared state of its own. Safe to call concurrently.
+     *
+     * Example (IOU range, 10^15 .. 10^16-1):
+     * @code
+     *     auto [m, e] = Number::normalizeToRange<1'000'000'000'000'000,
+     *                                            9'999'999'999'999'999>(1, 0);
+     *     // m == 1'000'000'000'000'000, e == -15
+     * @endcode
+     */
+    template <
+        auto MinMantissa,
+        auto MaxMantissa,
+        Integral64 T = std::decay_t<decltype(MinMantissa)>>
+    [[nodiscard]]
+    static std::pair<T, int>
+    normalizeToRange(rep mantissa, int exponent);
+
 private:
+    // Shared implementation for both normalizeToRange overloads. Takes the sign
+    // and internal (uint64) magnitude already separated, normalizes in place to
+    // [MinMantissa, MaxMantissa], and returns the signed (mantissa, exponent).
+    template <
+        auto MinMantissa,
+        auto MaxMantissa,
+        Integral64 T = std::decay_t<decltype(MinMantissa)>>
+    static std::pair<T, int>
+    normalizeToRangeImpl(bool negative, InternalRep mantissa, int exponent);
+
     static thread_local RoundingMode mode;
     // The available ranges for mantissa
 
@@ -839,7 +893,7 @@ Number::isnormal() const noexcept
 
 template <auto MinMantissa, auto MaxMantissa, Integral64 T>
 std::pair<T, int>
-Number::normalizeToRange() const
+Number::normalizeToRangeImpl(bool negative, InternalRep mantissa, int exponent)
 {
     static_assert(std::is_same_v<T, std::uint64_t> || std::is_same_v<T, std::int64_t>);
     static_assert(std::is_same_v<T, std::decay_t<decltype(MinMantissa)>>);
@@ -852,10 +906,6 @@ Number::normalizeToRange() const
     static_assert(kMAX % 10 == 9);
     static_assert((kMAX + 1) / 10 == kMIN);
 
-    bool negative = negative_;
-    InternalRep mantissa = mantissa_;
-    int exponent = exponent_;
-
     if constexpr (std::is_unsigned_v<T>)
     {
         XRPL_ASSERT_PARTS(
@@ -872,6 +922,26 @@ Number::normalizeToRange() const
     return std::make_pair(static_cast<T>(sign * mantissa), exponent);
 }
 
+template <auto MinMantissa, auto MaxMantissa, Integral64 T>
+std::pair<T, int>
+Number::normalizeToRange() const
+{
+    // Forward this Number's already-separated internal components to the shared
+    // implementation. Passing mantissa_ (which may exceed kMaxRep in the Large
+    // range) through unchanged keeps the result byte-identical to before.
+    return normalizeToRangeImpl<MinMantissa, MaxMantissa, T>(negative_, mantissa_, exponent_);
+}
+
+template <auto MinMantissa, auto MaxMantissa, Integral64 T>
+std::pair<T, int>
+Number::normalizeToRange(rep mantissa, int exponent)
+{
+    // Separate sign and magnitude from the raw signed mantissa, then normalize
+    // straight to the target range in a single pass (no intermediate Number).
+    return normalizeToRangeImpl<MinMantissa, MaxMantissa, T>(
+        mantissa < 0, externalToInternal(mantissa), exponent);
+}
+
 constexpr Number
 abs(Number x) noexcept
 {

include/xrpl/protocol/IOUAmount.h

@@ -40,6 +40,20 @@ private:
     void
     normalize();
 
+    /**
+     * Constrains the exponent to IOUAmount's range, which is narrower than
+     * the one Number normalization enforces.
+     *
+     * The two ends are deliberately asymmetric, matching the class contract:
+     * an exponent above the range is unrepresentable and throws, while one
+     * below it is a silent underflow that truncates the amount to zero.
+     *
+     * @throws std::overflow_error if the exponent exceeds the largest
+     *         representable IOU exponent.
+     */
+    void
+    enforceExponentBounds();
+
     static IOUAmount
     fromNumber(Number const& number);
 

src/libxrpl/protocol/IOUAmount.cpp

@@ -43,19 +43,7 @@ IOUAmount::minPositiveAmount()
 }
 
 void
-IOUAmount::normalize()
-{
-    if (mantissa_ == 0)
-    {
-        *this = beast::kZero;
-        return;
-    }
-
-    Number const v{mantissa_, exponent_};
-    *this = IOUAmount(v);
-}
-
-IOUAmount::IOUAmount(Number const& other) : IOUAmount(fromNumber(other))
+IOUAmount::enforceExponentBounds()
 {
     if (exponent_ > kMaxExponent)
     {
@@ -67,6 +55,27 @@ IOUAmount::IOUAmount(Number const& other) : IOUAmount(fromNumber(other))
     }
 }
 
+void
+IOUAmount::normalize()
+{
+    if (mantissa_ == 0)
+    {
+        *this = beast::kZero;
+        return;
+    }
+    std::tie(mantissa_, exponent_) =
+        Number::normalizeToRange<kMinMantissa, kMaxMantissa>(mantissa_, exponent_);
+
+    // normalizeToRange only enforces Number's much wider exponent bounds, so
+    // IOUAmount's narrower range still has to be applied on top.
+    enforceExponentBounds();
+}
+
+IOUAmount::IOUAmount(Number const& other) : IOUAmount(fromNumber(other))
+{
+    enforceExponentBounds();
+}
+
 IOUAmount&
 IOUAmount::operator+=(IOUAmount const& other)
 {

src/tests/libxrpl/basics/Number.cpp

@@ -3050,4 +3050,215 @@ TEST(NumberTest, number_cusp_rounding_with_fractional_parts)
     }
 }
 
+// The IOUAmount mantissa range: [10^15, 10^16 - 1]. Kept here as signed
+// constants so the default template parameter T resolves to std::int64_t,
+// matching IOUAmount's own use of Number::normalizeToRange.
+constexpr std::int64_t kMin = 1'000'000'000'000'000;
+constexpr std::int64_t kMax = (kMin * 10) - 1;
+
+// The two-pass path that the static primitive replaces: build a Number (one
+// normalize pass to the default range) and then re-normalize to the narrow IOU
+// range via the const member overload (a second pass).
+std::pair<std::int64_t, int>
+twoPass(std::int64_t mantissa, int exponent)
+{
+    Number const v{mantissa, exponent};
+    return v.normalizeToRange<kMin, kMax>();
+}
+
+// The single-pass static primitive under test.
+std::pair<std::int64_t, int>
+onePass(std::int64_t mantissa, int exponent)
+{
+    return Number::normalizeToRange<kMin, kMax>(mantissa, exponent);
+}
+
+// The static primitive must produce bit-identical (mantissa, exponent) to the
+// old two-pass path across a broad sweep of inputs: values needing scale-up,
+// scale-down, rounding cusps, negatives, and exponent extremes.
+TEST(NumberTest, normalize_to_range_equivalence)
+{
+    // A spread of mantissa magnitudes: tiny (heavy scale-up), mid, at the IOU
+    // floor/ceiling, beyond it (scale-down), and int64 extremes.
+    std::int64_t const mantissas[] = {
+        1,
+        2,
+        7,
+        9,
+        99,
+        100,
+        12345,
+        999'999'999'999'999,
+        kMin,
+        kMin + 1,
+        kMax,
+        kMax + 1,
+        1'234'567'890'123'456,
+        12'345'678'901'234'567,
+        std::numeric_limits<std::int64_t>::max(),
+        std::numeric_limits<std::int64_t>::max() - 1,
+    };
+
+    for (std::int64_t const absM : mantissas)
+    {
+        for (std::int64_t const m : {absM, -absM})
+        {
+            for (int const e : {-90, -32, -1, 0, 1, 5, 32, 70})
+            {
+                auto const expected = twoPass(m, e);
+                auto const actual = onePass(m, e);
+                EXPECT_EQ(actual.first, expected.first)
+                    << "mantissa mismatch for m=" << m << " e=" << e;
+                EXPECT_EQ(actual.second, expected.second)
+                    << "exponent mismatch for m=" << m << " e=" << e;
+            }
+        }
+    }
+
+    // int64::min cannot be negated naively; externalToInternal handles it. Make
+    // sure the static path agrees with the two-pass path on it too.
+    {
+        std::int64_t const m = std::numeric_limits<std::int64_t>::min();
+        auto const expected = twoPass(m, 0);
+        auto const actual = onePass(m, 0);
+        EXPECT_EQ(actual.first, expected.first);
+        EXPECT_EQ(actual.second, expected.second);
+    }
+}
+
+// Exact, hand-computed results (state + cause), not just "equals the old path".
+TEST(NumberTest, normalize_to_range_exact_values)
+{
+    // A single digit scales up by 15 powers of ten to reach the floor 10^15,
+    // with the exponent dropping by the same 15.
+    {
+        auto const [m, e] = onePass(1, 0);
+        EXPECT_EQ(m, kMin);  // 1'000'000'000'000'000
+        EXPECT_EQ(e, -15);
+    }
+    // Already exactly at the floor: unchanged.
+    {
+        auto const [m, e] = onePass(kMin, 4);
+        EXPECT_EQ(m, kMin);
+        EXPECT_EQ(e, 4);
+    }
+    // Already exactly at the ceiling: unchanged.
+    {
+        auto const [m, e] = onePass(kMax, -7);
+        EXPECT_EQ(m, kMax);  // 9'999'999'999'999'999
+        EXPECT_EQ(e, -7);
+    }
+    // One past the ceiling scales down by one power of ten; the dropped ones
+    // digit (0) truncates cleanly and the exponent rises by one.
+    {
+        auto const [m, e] = onePass(kMax + 1, 0);  // 10'000'000'000'000'000
+        EXPECT_EQ(m, kMin);                        // 1'000'000'000'000'000
+        EXPECT_EQ(e, 1);
+    }
+    // Negative values keep their sign through normalization.
+    {
+        auto const [m, e] = onePass(-5, 0);
+        EXPECT_EQ(m, -5 * kMin);  // -5'000'000'000'000'000
+        EXPECT_EQ(e, -15);
+    }
+    // Zero mantissa: the workhorse leaves it as zero (callers special-case it).
+    {
+        auto const [m, e] = onePass(0, 0);
+        EXPECT_EQ(m, 0);
+    }
+}
+
+// Equivalence must hold under every rounding mode, not just the default
+// ToNearest. This is the subtlest risk: the single-pass impl hardcodes
+// CuspRoundingFix::Disabled, whereas the old two-pass path ran an intermediate
+// normalize to the wider range first. Sweep all four modes, including inputs
+// that round at a tie (a trailing digit of exactly 5 when scaling down).
+TEST(NumberTest, normalize_to_range_all_rounding_modes)
+{
+    // Inputs chosen so scale-down drops a non-zero (and tie) trailing digit.
+    std::int64_t const mantissas[] = {
+        15,
+        25,
+        12'345'678'901'234'565,  // 17 digits, trailing 5 -> tie on the drop
+        99'999'999'999'999'995,
+        kMax + 5,
+        std::numeric_limits<std::int64_t>::max(),
+    };
+
+    for (auto mode :
+         {Number::RoundingMode::ToNearest,
+          Number::RoundingMode::TowardsZero,
+          Number::RoundingMode::Downward,
+          Number::RoundingMode::Upward})
+    {
+        for (std::int64_t const absM : mantissas)
+        {
+            for (std::int64_t const m : {absM, -absM})
+            {
+                for (int const e : {-20, 0, 13})
+                {
+                    NumberRoundModeGuard const g(mode);
+                    auto const expected = twoPass(m, e);
+                    auto const actual = onePass(m, e);
+                    EXPECT_EQ(actual.first, expected.first)
+                        << "mantissa mismatch: mode=" << static_cast<int>(mode) << " m=" << m
+                        << " e=" << e;
+                    EXPECT_EQ(actual.second, expected.second)
+                        << "exponent mismatch: mode=" << static_cast<int>(mode) << " m=" << m
+                        << " e=" << e;
+                }
+            }
+        }
+    }
+}
+
+// The refactored const member overload must forward to the static primitive
+// and yield identical results for the same Number.
+TEST(NumberTest, normalize_to_range_member_static_consistency)
+{
+    std::int64_t const mantissas[] = {3, 42, kMin, kMin + 7, kMax, kMax + 1, 1'234'567'890'123'456};
+
+    for (std::int64_t const absM : mantissas)
+    {
+        for (std::int64_t const m : {absM, -absM})
+        {
+            for (int const e : {-50, -3, 0, 11, 60})
+            {
+                Number const v{m, e};
+                auto const viaMember = v.normalizeToRange<kMin, kMax>();
+                // Feed the static the raw inputs that built the Number.
+                auto const viaStatic = Number::normalizeToRange<kMin, kMax>(m, e);
+                EXPECT_EQ(viaMember.first, viaStatic.first) << "m=" << m << " e=" << e;
+                EXPECT_EQ(viaMember.second, viaStatic.second) << "m=" << m << " e=" << e;
+            }
+        }
+    }
+}
+
+// A zero mantissa returns the zero sentinel, ignoring the exponent passed in.
+TEST(NumberTest, normalize_to_range_zero_mantissa)
+{
+    for (int const e : {Number::kMinExponent, -90, -1, 0, 1, 90, Number::kMaxExponent})
+    {
+        auto const [m, exponent] = onePass(0, e);
+        EXPECT_EQ(m, 0) << "e=" << e;
+        EXPECT_EQ(exponent, std::numeric_limits<int>::lowest()) << "e=" << e;
+    }
+}
+
+// At the exponent floor the two paths differ: the two-pass path zeroes, while
+// the single pass scales down and keeps the value.
+TEST(NumberTest, normalize_to_range_exponent_floor_diverges_from_two_pass)
+{
+    // 10^17: above the IOU minimum, below the Large330 minimum of 10^18.
+    constexpr std::int64_t kBelowWideMin = kMin * 100;
+
+    auto const [oneM, oneE] = onePass(kBelowWideMin, Number::kMinExponent);
+    EXPECT_EQ(oneM, kMin);
+    EXPECT_EQ(oneE, Number::kMinExponent + 2);
+
+    auto const [twoM, twoE] = twoPass(kBelowWideMin, Number::kMinExponent);
+    EXPECT_EQ(twoM, 0);
+    EXPECT_EQ(twoE, std::numeric_limits<int>::lowest());
+}
 }  // namespace xrpl