xrpld
Loading...
Searching...
No Matches
Number.h
1#pragma once
2
3#include <xrpl/beast/utility/instrumentation.h>
4
5#include <algorithm>
6#include <array>
7#include <cstddef>
8#include <cstdint>
9#include <functional>
10#include <limits>
11#include <optional>
12#include <ostream>
13#include <set>
14#include <stdexcept>
15#include <string>
16#include <type_traits>
17#include <utility>
18
19namespace xrpl {
20
21class Number;
22
23std::string
24to_string(Number const& amount);
25
26template <typename T>
27constexpr std::optional<int>
28logTen(T value)
29{
30 int log = 0;
31 while (value >= 10 && value % 10 == 0)
32 {
33 value /= 10;
34 ++log;
35 }
36 if (value == 1)
37 return log;
38 return std::nullopt;
39}
40
41template <typename T>
42constexpr bool
44{
45 return logTen(value).has_value();
46}
47
48namespace detail {
49
59[[maybe_unused]] constexpr std::size_t kUint128Digits = 39;
60
61template <typename T, std::size_t Digits>
64{
65 std::array<T, Digits> result{};
66
67 T power = 1;
68 std::size_t exponent = 0;
69 // end the loop early so it doesn't overflow;
70 for (; exponent < result.size() - 1; ++exponent, power *= 10)
71 {
72 result[exponent] = power;
74 throw std::logic_error("Power of 10 table is too big");
75 }
76 result[exponent] = power;
78 throw std::logic_error("Power of 10 table is not big enough for the given type");
79
80 return result;
81}
82
83} // namespace detail
84
85template <typename T = std::uint64_t, std::size_t Digits = detail::kUint64Digits>
87
89
90static_assert(kPowerOfTen[0] == 1);
91static_assert(kPowerOfTen[1] == 10);
92static_assert(kPowerOfTen[10] == 10'000'000'000);
93static_assert(
95
130struct MantissaRange final
131{
133
134 // NOLINTBEGIN(readability-enum-initial-value)
135 // The values don't matter, except for Large
136 enum class MantissaScale {
137 // Small can be removed when any of featureSingleAssetVault, featureLendingProtocol, or
138 // featureMPTokensV2 are retired
140 // LargeLegacy can be removed when fixCleanup3_2_0 is retired
142 // Large320 can be removed when fixCleanup3_3_0 is retired
144 // If Large330 is ever the only remaining "Large*" entry, it can be renamed to just "Large".
146 // Large is a de-facto alias for "the latest", and is only here for backward compatibility
147 // in the extremely unlikely case that a downstream project made use of it. Note that
148 // because the behavior changed, this may still be a breaking change.
150 };
151 // NOLINTEND(readability-enum-initial-value)
152
153 // This entire enum can be removed when the last relevant amendment is retired
155 // Disabled can be removed when fixCleanup3_2_0 is retired
157 // Enabled320 can be removed when fixCleanup3_3_0 is retired
159 // If we ever get to the point that there's only one entry, remove the entire enum
161 // Enabled is a de-facto alias for "the latest", and is only here for backward compatibility
162 // in the extremely unlikely case that a downstream project made use of it. Note that
163 // because the behavior changed, this may still be a breaking change.
165 };
166
167 explicit constexpr MantissaRange(MantissaScale sc) : scale(sc)
168 {
169 }
170
172 int const log{getExponent(scale)};
174 rep const max{(min * 10) - 1};
176
177 static std::set<MantissaScale> const&
188
189 class Access
190 {
191 static constexpr MantissaRange const&
193
194 friend Number;
195 };
196
197private:
198 static constexpr int
200 {
201 switch (scale)
202 {
204 return 15;
208 return 18;
209 // LCOV_EXCL_START
210 default:
211 // If called in a constexpr context, this throw assures that the build fails if an
212 // invalid scale is used.
213 throw std::runtime_error("Unknown mantissa scale");
214 // LCOV_EXCL_STOP
215 }
216 }
217
218 // Keep this function for future use with different ways to compute
219 // the ranges.
220 static constexpr rep
222 {
223 if (exponent < 0 || exponent >= kPowerOfTen.size())
224 throw std::runtime_error("Invalid exponent"); // LCOV_EXCL_LINE
225 return kPowerOfTen[exponent];
226 }
227
228 static constexpr CuspRoundingFix
230 {
231 switch (scale)
232 {
240 default:
241 // If called in a constexpr context, this throw assures that the build fails if an
242 // invalid scale is used.
243 throw std::runtime_error("Unknown mantissa scale"); // LCOV_EXCL_LINE
244 }
245 }
246};
247
248// Like std::integral, but only 64-bit integral types.
249template <class T>
251
350class Number final
351{
354
357 bool negative_{false};
358
359public:
360 // The range for the exponent when normalized
361 static constexpr int kMinExponent = -32768;
362 static constexpr int kMaxExponent = 32768;
363
365 static_assert(kMaxRep == 9'223'372'036'854'775'807);
366 static_assert(-kMaxRep == std::numeric_limits<rep>::min() + 1);
367 static constexpr InternalRep kMaxRepUp = ((kMaxRep / 10) + 1) * 10;
368 static_assert(kMaxRepUp == 9'223'372'036'854'775'810ULL);
369
370 // May need to make unchecked private
372 {
373 explicit Unchecked() = default;
374 };
375
376 // Like unchecked, normalized is used with the ctors that take an
377 // internalrep mantissa. Unlike unchecked, those ctors will normalize the
378 // value.
379 // Only unit tests are expected to use this class
381 {
382 explicit Normalized() = default;
383 };
384
385 explicit constexpr Number() = default;
386
388 explicit Number(rep mantissa, int exponent);
389 explicit constexpr Number(
390 bool negative,
392 int exponent,
393 Unchecked) noexcept;
394 // Assume unsigned values are... unsigned. i.e. positive
395 explicit constexpr Number(InternalRep mantissa, int exponent, Unchecked) noexcept;
396 // Only unit tests are expected to use this ctor
397 explicit Number(bool negative, InternalRep mantissa, int exponent, Normalized);
398 // Assume unsigned values are... unsigned. i.e. positive
400
401 [[nodiscard]] constexpr rep
402 mantissa() const noexcept;
403 [[nodiscard]] constexpr int
404 exponent() const noexcept;
405
406 constexpr Number
407 operator+() const noexcept;
408 constexpr Number
409 operator-() const noexcept;
410 Number&
411 operator++();
412 Number
413 operator++(int);
414 Number&
415 operator--();
416 Number
417 operator--(int);
418
419 Number&
420 operator+=(Number const& x);
421 Number&
422 operator-=(Number const& x);
423
424 Number&
425 operator*=(Number const& x);
426 Number&
427 operator/=(Number const& x);
428
429 static Number
430 min() noexcept;
431 static Number
432 max() noexcept;
433 static Number
434 lowest() noexcept;
435
442 explicit
443 operator rep() const; // round to nearest, even on tie
444
445 friend constexpr bool
446 operator==(Number const& x, Number const& y) noexcept
447 {
448 return x.negative_ == y.negative_ && x.mantissa_ == y.mantissa_ &&
449 x.exponent_ == y.exponent_;
450 }
451
452 friend constexpr bool
453 operator<(Number const& l, Number const& r) noexcept
454 {
455 bool const lneg = l.negative_;
456 bool const rneg = r.negative_;
457
458 // If the two amounts have different signs (zero is treated as positive)
459 // then the comparison is true iff the left is negative.
460 if (lneg != rneg)
461 return lneg;
462
463 // Both have same sign and the left is zero: both must be non-negative.
464 // If the right is greater than 0, then it is larger, so the comparison is true.
465 if (l.mantissa_ == 0)
466 return r.mantissa_ > 0;
467
468 // Both have same sign, the right is zero and the left is non-zero, so the left must be
469 // positive, and thus is larger, so the comparison is false.
470 if (r.mantissa_ == 0)
471 return false;
472
473 // Both have the same sign, compare by exponents:
474 if (l.exponent_ > r.exponent_)
475 return lneg;
476 if (l.exponent_ < r.exponent_)
477 return !lneg;
478
479 // If equal signs and exponents, compare mantissas.
480 if (lneg)
481 {
482 // If negative, the operator is reversed.
483 return l.mantissa_ > r.mantissa_;
484 }
485
486 return l.mantissa_ < r.mantissa_;
487 }
488
492 [[nodiscard]] constexpr int
493 signum() const noexcept
494 {
495 if (negative_)
496 return -1;
497 return (mantissa_ != 0u) ? 1 : 0;
498 }
499
500 [[nodiscard]] Number
501 truncate() const noexcept;
502
503 friend constexpr bool
504 operator>(Number const& x, Number const& y) noexcept
505 {
506 return y < x;
507 }
508
509 friend constexpr bool
510 operator<=(Number const& x, Number const& y) noexcept
511 {
512 return !(y < x);
513 }
514
515 friend constexpr bool
516 operator>=(Number const& x, Number const& y) noexcept
517 {
518 return !(x < y);
519 }
520
522 operator<<(std::ostream& os, Number const& x)
523 {
524 return os << to_string(x);
525 }
526
527 friend std::string
528 to_string(Number const& amount);
529
530 friend Number
531 root(Number f, unsigned d);
532
533 friend Number
534 root2(Number f);
535
536 // Thread local rounding control. Default is to_nearest
538
539 static RoundingMode
540 getround();
541
542 static RoundingMode
543 setround(RoundingMode inMode);
544
552
558 static void
560
561 static InternalRep
563 {
564 return kRange.get().min;
565 }
566
567 static InternalRep
569 {
570 return kRange.get().max;
571 }
572
573 static int
575 {
576 return kRange.get().log;
577 }
578
579 static Number
580 one();
581
582 template <
583 auto MinMantissa,
584 auto MaxMantissa,
585 Integral64 T = std::decay_t<decltype(MinMantissa)>>
586 [[nodiscard]]
588 normalizeToRange() const;
589
590 // Safely convert rep (int64) mantissa to internalrep (uint64). If the rep
591 // is negative, returns the positive value. This takes a little extra work
592 // because converting std::numeric_limits<std::int64_t>::min() flirts with
593 // UB, and can vary across compilers.
594 static InternalRep
596
597private:
598 static thread_local RoundingMode mode;
599 // The available ranges for mantissa
600
601 // The range for the mantissa when normalized.
602 // Use reference_wrapper to avoid making copies, and prevent accidentally
603 // changing the values inside the range.
605
606 class Guard;
607
608 void
610
611 // Guard has the fields that we need, as well as MantissaRange, so if we have a guard, use that
612 void
613 normalize(Guard const& guard);
614
622 template <class T>
623 static void
625 bool& negative,
626 T& mantissa,
627 int& exponent,
630 MantissaRange::CuspRoundingFix cuspRoundingFix);
631
632 template <class T>
633 friend void
635 bool& negative,
636 T& mantissa,
637 int& exponent,
640 MantissaRange::CuspRoundingFix cuspRoundingFix,
641 bool dropped);
642
643 [[nodiscard]] bool
644 isnormal() const noexcept;
645
646 // Copy the number, but modify the exponent by "exponentDelta". Because the
647 // mantissa doesn't change, the result will be "mostly" normalized, but the
648 // exponent could go out of range, so it will be checked.
649 [[nodiscard]] Number
650 shiftExponent(int exponentDelta) const;
651};
652
653// The number class currently has 3 tail padding bytes. If you are adding new
654// members, try to fit them there before expanding the size of the class.
655static_assert(sizeof(Number) == 16);
656
657constexpr Number::Number(bool negative, InternalRep mantissa, int exponent, Unchecked) noexcept
659{
660}
661
663 : Number(false, mantissa, exponent, Unchecked{})
664{
665}
666
667static constexpr Number kNumZero{};
668
670 : Number(negative, mantissa, exponent, Unchecked{})
671{
673}
674
679
684
686{
687}
688
695constexpr Number::rep
696Number::mantissa() const noexcept
697{
698 auto m = mantissa_;
699 if (m > kMaxRep)
700 {
701 XRPL_ASSERT_PARTS(
702 !isnormal() || (m % 10 == 0 && m / 10 <= kMaxRep),
703 "xrpl::Number::mantissa",
704 "large normalized mantissa has no remainder");
705 m /= 10;
706 }
707 auto const sign = negative_ ? -1 : 1;
708 return sign * static_cast<Number::rep>(m);
709}
710
717constexpr int
718Number::exponent() const noexcept
719{
720 auto e = exponent_;
721 if (mantissa_ > kMaxRep)
722 {
723 XRPL_ASSERT_PARTS(
724 !isnormal() || (mantissa_ % 10 == 0 && mantissa_ / 10 <= kMaxRep),
725 "xrpl::Number::exponent",
726 "large normalized mantissa has no remainder");
727 ++e;
728 }
729 return e;
730}
731
732constexpr Number
733Number::operator+() const noexcept
734{
735 return *this;
736}
737
738constexpr Number
739Number::operator-() const noexcept
740{
741 if (mantissa_ == 0)
742 return Number{};
743 auto x = *this;
744 x.negative_ = !x.negative_;
745 return x;
746}
747
748inline Number&
750{
751 *this += one();
752 return *this;
753}
754
755inline Number
757{
758 auto x = *this;
759 ++(*this);
760 return x;
761}
762
763inline Number&
765{
766 *this -= one();
767 return *this;
768}
769
770inline Number
772{
773 auto x = *this;
774 --(*this);
775 return x;
776}
777
778inline Number&
780{
781 return *this += -x;
782}
783
784inline Number
785operator+(Number const& x, Number const& y)
786{
787 auto z = x;
788 z += y;
789 return z;
790}
791
792inline Number
793operator-(Number const& x, Number const& y)
794{
795 auto z = x;
796 z -= y;
797 return z;
798}
799
800inline Number
801operator*(Number const& x, Number const& y)
802{
803 auto z = x;
804 z *= y;
805 return z;
806}
807
808inline Number
809operator/(Number const& x, Number const& y)
810{
811 auto z = x;
812 z /= y;
813 return z;
814}
815
816inline Number
817Number::min() noexcept
818{
819 return Number{false, kRange.get().min, kMinExponent, Unchecked{}};
820}
821
822inline Number
823Number::max() noexcept
824{
825 return Number{false, std::min(kRange.get().max, kMaxRep), kMaxExponent, Unchecked{}};
826}
827
828inline Number
830{
831 return Number{true, std::min(kRange.get().max, kMaxRep), kMaxExponent, Unchecked{}};
832}
833
834inline bool
835Number::isnormal() const noexcept
836{
837 MantissaRange const& range = kRange;
838 auto const absM = mantissa_;
839 return *this == Number{} ||
840 (range.min <= absM && absM <= range.max && (absM <= kMaxRep || absM % 10 == 0) &&
842}
843
844template <auto MinMantissa, auto MaxMantissa, Integral64 T>
847{
849 static_assert(std::is_same_v<T, std::decay_t<decltype(MinMantissa)>>);
850 static_assert(std::is_same_v<T, std::decay_t<decltype(MaxMantissa)>>);
851 auto constexpr kMIN = static_cast<T>(MinMantissa);
852 auto constexpr kMAX = static_cast<T>(MaxMantissa);
853 static_assert(kMIN > 0);
854 static_assert(kMIN % 10 == 0);
855 static_assert(isPowerOfTen(kMIN));
856 static_assert(kMAX % 10 == 9);
857 static_assert((kMAX + 1) / 10 == kMIN);
858
859 bool negative = negative_;
861 int exponent = exponent_;
862
863 if constexpr (std::is_unsigned_v<T>)
864 {
865 XRPL_ASSERT_PARTS(
866 !negative,
867 "xrpl::Number::normalizeToRange",
868 "Number is non-negative for unsigned range.");
869 }
870 // Don't need to worry about the cuspRounding fix because rounding up will never take the
871 // mantissa over maxMantissa with a ones digit value other than 0. 0 can safely be truncated.
874
875 auto const sign = negative ? -1 : 1;
876 return std::make_pair(static_cast<T>(sign * mantissa), exponent);
877}
878
879constexpr Number
880abs(Number x) noexcept
881{
882 if (x < Number{})
883 x = -x;
884 return x;
885}
886
887// Returns f^n
888// Uses a log_2(n) number of multiplications
889
890Number
891power(Number const& f, unsigned n);
892
893// Returns f^(1/d)
894// Uses Newton–Raphson iterations until the result stops changing
895// to find the root of the polynomial g(x) = x^d - f
896
897Number
898root(Number f, unsigned d);
899
900Number
901root2(Number f);
902
903// Returns f^(n/d)
904
905Number
906power(Number const& f, unsigned n, unsigned d);
907
908// Return 0 if abs(x) < limit, else returns x
909
910constexpr Number
911squelch(Number const& x, Number const& limit) noexcept
912{
913 if (abs(x) < limit)
914 return Number{};
915 return x;
916}
917
920
922to_string(Number::RoundingMode const& round);
923
940
941// saveNumberRoundMode doesn't do quite enough for us. What we want is a
942// Number::RoundModeGuard that sets the new mode and restores the old mode
943// when it leaves scope. Since Number doesn't have that facility, we'll
944// build it here.
960
987
988} // namespace xrpl
static constexpr MantissaRange const & mantissaRange(MantissaScale scale)
NumberMantissaScaleGuard(NumberMantissaScaleGuard const &)=delete
MantissaRange::MantissaScale const saved_
Definition Number.h:968
NumberMantissaScaleGuard & operator=(NumberMantissaScaleGuard const &)=delete
NumberMantissaScaleGuard(MantissaRange::MantissaScale scale) noexcept
Definition Number.h:971
NumberRoundModeGuard(Number::RoundingMode mode) noexcept
Definition Number.h:950
SaveNumberRoundMode saved_
Definition Number.h:947
NumberRoundModeGuard & operator=(NumberRoundModeGuard const &)=delete
NumberRoundModeGuard(NumberRoundModeGuard const &)=delete
Number is a floating point type that can represent a wide range of values.
Definition Number.h:351
Number & operator++()
Definition Number.h:749
constexpr rep mantissa() const noexcept
Returns the mantissa of the external view of the Number.
Definition Number.h:696
std::pair< T, int > normalizeToRange() const
Definition Number.h:846
static InternalRep maxMantissa()
Definition Number.h:568
MantissaRange::rep InternalRep
Definition Number.h:353
static constexpr InternalRep kMaxRepUp
Definition Number.h:367
Number truncate() const noexcept
std::int64_t rep
Definition Number.h:352
friend std::string to_string(Number const &amount)
friend constexpr bool operator<(Number const &l, Number const &r) noexcept
Definition Number.h:453
static constexpr int kMinExponent
Definition Number.h:361
static RoundingMode setround(RoundingMode inMode)
static constexpr InternalRep kMaxRep
Definition Number.h:364
static RoundingMode mode
Definition Number.h:598
friend void doNormalize(bool &negative, T &mantissa, int &exponent, MantissaRange::rep const &minMantissa, MantissaRange::rep const &maxMantissa, MantissaRange::CuspRoundingFix cuspRoundingFix, bool dropped)
constexpr Number operator-() const noexcept
Definition Number.h:739
static Number max() noexcept
Definition Number.h:823
static RoundingMode getround()
static std::reference_wrapper< MantissaRange const > kRange
Definition Number.h:604
static void normalize(bool &negative, T &mantissa, int &exponent, InternalRep const &minMantissa, InternalRep const &maxMantissa, MantissaRange::CuspRoundingFix cuspRoundingFix)
Normalize Number components to an arbitrary range.
constexpr Number operator+() const noexcept
Definition Number.h:733
Number & operator--()
Definition Number.h:764
Number shiftExponent(int exponentDelta) const
static MantissaRange::MantissaScale getMantissaScale()
Returns which mantissa scale is currently in use for normalization.
friend constexpr bool operator>=(Number const &x, Number const &y) noexcept
Definition Number.h:516
static InternalRep minMantissa()
Definition Number.h:562
static constexpr int kMaxExponent
Definition Number.h:362
bool isnormal() const noexcept
Definition Number.h:835
constexpr int exponent() const noexcept
Returns the exponent of the external view of the Number.
Definition Number.h:718
friend std::ostream & operator<<(std::ostream &os, Number const &x)
Definition Number.h:522
friend Number root2(Number f)
constexpr int signum() const noexcept
Return the sign of the amount.
Definition Number.h:493
Number & operator-=(Number const &x)
Definition Number.h:779
static InternalRep externalToInternal(rep mantissa)
static Number min() noexcept
Definition Number.h:817
int exponent_
Definition Number.h:356
void normalize(MantissaRange const &range)
constexpr Number()=default
static void setMantissaScale(MantissaRange::MantissaScale scale)
Changes which mantissa scale is used for normalization.
static Number lowest() noexcept
Definition Number.h:829
bool negative_
Definition Number.h:357
static int mantissaLog()
Definition Number.h:574
InternalRep mantissa_
Definition Number.h:355
friend constexpr bool operator<=(Number const &x, Number const &y) noexcept
Definition Number.h:510
friend Number root(Number f, unsigned d)
SaveNumberRoundMode(SaveNumberRoundMode const &)=delete
SaveNumberRoundMode & operator=(SaveNumberRoundMode const &)=delete
SaveNumberRoundMode(Number::RoundingMode mode) noexcept
Definition Number.h:933
Number::RoundingMode mode_
Definition Number.h:926
T is_same_v
T is_unsigned_v
T lowest(T... args)
T make_pair(T... args)
T max(T... args)
T min(T... args)
constexpr std::size_t kUint64Digits
Builds a table of the powers of 10.
Definition Number.h:58
consteval std::array< T, Digits > buildPowersOfTen()
Definition Number.h:63
constexpr std::size_t kUint128Digits
Definition Number.h:59
Use hash_* containers for keys that do not need a cryptographically secure hashing algorithm.
Definition algorithm.h:5
static constexpr Number kNumZero
Definition Number.h:667
constexpr BaseUInt< Bits, Tag > operator+(BaseUInt< Bits, Tag > const &a, BaseUInt< Bits, Tag > const &b)
Definition base_uint.h:650
Number operator-(Number const &x, Number const &y)
Definition Number.h:793
ClosedInterval< T > range(T low, T high)
Create a closed range interval.
Definition RangeSet.h:37
Number operator/(Number const &x, Number const &y)
Definition Number.h:809
int scale(Number const &number, Asset const &asset)
Get the scale of a Number for a given asset.
Definition STAmount.h:819
constexpr std::array< T, Digits > kPowerOfTenImpl
Definition Number.h:86
Number root(Number f, unsigned d)
Number power(Number const &f, unsigned n)
Number operator*(Number const &x, Number const &y)
Definition Number.h:801
std::string to_string(BaseUInt< Bits, Tag > const &a)
Definition base_uint.h:658
constexpr std::optional< int > logTen(T value)
Definition Number.h:28
constexpr auto kPowerOfTen
Definition Number.h:88
constexpr bool isPowerOfTen(T value)
Definition Number.h:43
Number root2(Number f)
constexpr Number abs(Number x) noexcept
Definition Number.h:880
Buffer sign(PublicKey const &pk, SecretKey const &sk, Slice const &message)
Generate a signature for a message.
constexpr Number squelch(Number const &x, Number const &limit) noexcept
Definition Number.h:911
T has_value(T... args)
T size(T... args)
MantissaRange defines a range for the mantissa of a normalized Number.
Definition Number.h:131
rep const min
Definition Number.h:173
MantissaScale const scale
Definition Number.h:171
static constexpr int getExponent(MantissaScale scale)
Definition Number.h:199
std::uint64_t rep
Definition Number.h:132
int const log
Definition Number.h:172
CuspRoundingFix const cuspRoundingFix
Definition Number.h:175
constexpr MantissaRange(MantissaScale sc)
Definition Number.h:167
static constexpr rep getMin(MantissaScale scale, int exponent)
Definition Number.h:221
static constexpr CuspRoundingFix isCuspFixEnabled(MantissaScale scale)
Definition Number.h:229
static std::set< MantissaScale > const & getAllScales()
Definition Number.h:178
rep const max
Definition Number.h:174