Number is a floating point type that can represent a wide range of values. More...
#include <Number.h>
Classes | |
| struct | Unchecked |
| struct | Normalized |
| class | Guard |
Public Types | |
| enum class | RoundingMode { ToNearest , TowardsZero , Downward , Upward } |
Public Member Functions | |
| constexpr | Number ()=default |
| Number (rep mantissa) | |
| Number (rep mantissa, int exponent) | |
| constexpr | Number (bool negative, internalrep mantissa, int exponent, Unchecked) noexcept |
| constexpr | Number (internalrep mantissa, int exponent, Unchecked) noexcept |
| Number (bool negative, internalrep mantissa, int exponent, Normalized) | |
| Number (internalrep mantissa, int exponent, Normalized) | |
| constexpr rep | mantissa () const noexcept |
| Returns the mantissa of the external view of the Number. | |
| constexpr int | exponent () const noexcept |
| Returns the exponent of the external view of the Number. | |
| constexpr Number | operator+ () const noexcept |
| constexpr Number | operator- () const noexcept |
| Number & | operator++ () |
| Number | operator++ (int) |
| Number & | operator-- () |
| Number | operator-- (int) |
| Number & | operator+= (Number const &x) |
| Number & | operator-= (Number const &x) |
| Number & | operator*= (Number const &x) |
| Number & | operator/= (Number const &x) |
| operator rep () const | |
| Conversions to Number are implicit and conversions away from Number are explicit. | |
| constexpr int | signum () const noexcept |
| Return the sign of the amount. | |
| Number | truncate () const noexcept |
| template<auto MinMantissa, auto MaxMantissa, Integral64 T = std::decay_t<decltype(MinMantissa)>> | |
| std::pair< T, int > | normalizeToRange () const |
Static Public Member Functions | |
| static Number | min () noexcept |
| static Number | max () noexcept |
| static Number | lowest () noexcept |
| static RoundingMode | getround () |
| static RoundingMode | setround (RoundingMode inMode) |
| static MantissaRange::MantissaScale | getMantissaScale () |
| Returns which mantissa scale is currently in use for normalization. | |
| static void | setMantissaScale (MantissaRange::MantissaScale scale) |
| Changes which mantissa scale is used for normalization. | |
| static internalrep | minMantissa () |
| static internalrep | maxMantissa () |
| static int | mantissaLog () |
| static Number | one () |
Static Public Attributes | |
| static constexpr int | kMinExponent = -32768 |
| static constexpr int | kMaxExponent = 32768 |
| static constexpr internalrep | kMaxRep = std::numeric_limits<rep>::max() |
Private Types | |
| using | rep = std::int64_t |
| using | internalrep = MantissaRange::rep |
Private Member Functions | |
| void | normalize (MantissaRange const &range) |
| bool | isnormal () const noexcept |
| Number | shiftExponent (int exponentDelta) const |
Static Private Member Functions | |
| template<class T> | |
| static void | normalize (bool &negative, T &mantissa, int &exponent, internalrep const &minMantissa, internalrep const &maxMantissa, MantissaRange::CuspRoundingFix cuspRoundingFixEnabled) |
| Normalize Number components to an arbitrary range. | |
| static internalrep | externalToInternal (rep mantissa) |
| template<> | |
| void | normalize (bool &negative, uint128_t &mantissa, int &exponent, internalrep const &minMantissa, internalrep const &maxMantissa, MantissaRange::CuspRoundingFix cuspRoundingFixEnabled) |
| template<> | |
| void | normalize (bool &negative, unsigned long long &mantissa, int &exponent, internalrep const &minMantissa, internalrep const &maxMantissa, MantissaRange::CuspRoundingFix cuspRoundingFixEnabled) |
| template<> | |
| void | normalize (bool &negative, unsigned long &mantissa, int &exponent, internalrep const &minMantissa, internalrep const &maxMantissa, MantissaRange::CuspRoundingFix cuspRoundingFixEnabled) |
Private Attributes | |
| bool | negative_ {false} |
| internalrep | mantissa_ {0} |
| int | exponent_ {std::numeric_limits<int>::lowest()} |
Static Private Attributes | |
| static RoundingMode | mode = Number::RoundingMode::ToNearest |
| static std::reference_wrapper< MantissaRange const > | kRange |
Friends | |
| constexpr bool | operator== (Number const &x, Number const &y) noexcept |
| constexpr bool | operator!= (Number const &x, Number const &y) noexcept |
| constexpr bool | operator< (Number const &l, Number const &r) noexcept |
| constexpr bool | operator> (Number const &x, Number const &y) noexcept |
| constexpr bool | operator<= (Number const &x, Number const &y) noexcept |
| constexpr bool | operator>= (Number const &x, Number const &y) noexcept |
| std::ostream & | operator<< (std::ostream &os, Number const &x) |
| std::string | to_string (Number const &amount) |
| Number | root (Number f, unsigned d) |
| Number | root2 (Number f) |
| template<class T> | |
| void | doNormalize (bool &negative, T &mantissa, int &exponent, MantissaRange::rep const &minMantissa, MantissaRange::rep const &maxMantissa, MantissaRange::CuspRoundingFix cuspRoundingFixEnabled, bool dropped) |
Detailed Description
Number is a floating point type that can represent a wide range of values.
It can represent all values that can be represented by an STAmount - regardless of asset type - XRPAmount, MPTAmount, and IOUAmount, with at least as much precision as those types require.
-— Internal Representation -—
Internally, Number is represented with three values:
- a bool sign flag,
- a std::uint64_t mantissa,
- an int exponent.
The internal mantissa is an unsigned integer in the range defined by the current MantissaRange. The exponent is an integer in the range [minExponent, maxExponent].
See the description of MantissaRange for more details on the ranges.
A non-zero mantissa is (almost) always normalized, meaning it and the exponent are grown or shrunk until the mantissa is in the range [MantissaRange.min, MantissaRange.max].
Note:
- Normalization can be disabled by using the "unchecked" ctor tag. This should only be used at specific conversion points, some constexpr values, and in unit tests.
- The max of the "large" range, 10^19-1, is the largest 10^X-1 value that fits in an unsigned 64-bit number. (10^19-1 < 2^64-1 and 10^20-1 > 2^64-1). This avoids under- and overflows.
-— External Interface -—
The external interface of Number consists of a std::int64_t mantissa, which is restricted to 63-bits, and an int exponent, which must be in the range [minExponent, maxExponent]. The range of the mantissa depends on which MantissaRange is currently active. For the "short" range, the mantissa will be between 10^15 and 10^16-1. For the "large" range, the mantissa will be between -(2^63-1) and 2^63-1. As noted above, the "large" range is needed to represent the full range of valid XRP and MPT integer values accurately.
Note:
- 2^63-1 is between 10^18 and 10^19-1, which are the limits of the "large" mantissa range.
- The functions mantissa() and exponent() return the external view of the Number value, specifically using a signed 63-bit mantissa. This may require altering the internal representation to fit into that range before the value is returned. The interface guarantees consistency of the two values.
- Number cannot represent -2^63 (std::numeric_limits<std::int64_t>::min()) as an exact integer, but it doesn't need to, because all asset values on-ledger are non-negative. This is due to implementation details of several operations which use unsigned arithmetic internally. This is sufficient to represent all valid XRP values (where the absolute value can not exceed INITIAL_XRP: 10^17), and MPT values (where the absolute value can not exceed maxMPTokenAmount: 2^63-1).
-— Mantissa Range Switching -—
The mantissa range may be changed at runtime via setMantissaScale(). The default mantissa range is "large". The range is updated whenever transaction processing begins, based on whether SingleAssetVault or LendingProtocol are enabled. If either is enabled, the mantissa range is set to "large". If not, it is set to "small", preserving backward compatibility and correct "amendment-gating".
It is extremely unlikely that any more calls to setMantissaScale() will be needed outside of unit tests.
-— Usage With Different Ranges -—
Outside of unit tests, and existing checks, code that uses Number should not know or care which mantissa range is active.
The results of computations using Numbers with a small mantissa may differ from computations using Numbers with a large mantissa, specifically as it effects the results after rounding. That is why the large mantissa range is amendment gated in transaction processing.
It is extremely unlikely that any more calls to getMantissaScale() will be needed outside of unit tests.
Code that uses Number should not assume or check anything about the mantissa() or exponent() except that they fit into the "large" range specified in the "External Interface" section.
--— Unit Tests --—
Within unit tests, it may be useful to explicitly switch between the two ranges, or to check which range is active when checking the results of computations. If the test is doing the math directly, the set/getMantissaScale() functions may be most appropriate. However, if the test has anything to do with transaction processing, it should enable or disable the amendments that control the mantissa range choice (SingleAssetVault and LendingProtocol), and/or check if either of those amendments are enabled to determine which result to expect.
Member Typedef Documentation
◆ rep
|
private |
◆ internalrep
|
private |
Member Enumeration Documentation
◆ RoundingMode
|
strong |
Constructor & Destructor Documentation
◆ Number() [1/7]
|
explicitconstexprdefault |
◆ Number() [2/7]
◆ Number() [3/7]
|
explicit |
◆ Number() [4/7]
|
explicitconstexprnoexcept |
◆ Number() [5/7]
|
explicitconstexprnoexcept |
◆ Number() [6/7]
|
explicit |
◆ Number() [7/7]
|
explicit |
Member Function Documentation
◆ mantissa()
|
nodiscardconstexprnoexcept |
◆ exponent()
|
nodiscardconstexprnoexcept |
◆ operator+()
◆ operator-()
◆ operator++() [1/2]
◆ operator++() [2/2]
◆ operator--() [1/2]
◆ operator--() [2/2]
◆ operator+=()
Definition at line 691 of file Number.cpp.
◆ operator-=()
◆ operator*=()
Definition at line 792 of file Number.cpp.
◆ operator/=()
Definition at line 854 of file Number.cpp.
◆ min()
◆ max()
◆ lowest()
◆ operator rep()
|
explicit |
Conversions to Number are implicit and conversions away from Number are explicit.
This design encourages and facilitates the use of Number as the preferred type for floating point arithmetic as it makes "mixed mode" more convenient, e.g. MPTAmount + Number.
Definition at line 1033 of file Number.cpp.
◆ signum()
|
nodiscardconstexprnoexcept |
◆ truncate()
|
nodiscardnoexcept |
Definition at line 1062 of file Number.cpp.
◆ getround()
|
static |
Definition at line 105 of file Number.cpp.
◆ setround()
|
static |
Definition at line 111 of file Number.cpp.
◆ getMantissaScale()
|
static |
Returns which mantissa scale is currently in use for normalization.
If you think you need to call this outside of unit tests, no you don't.
Definition at line 117 of file Number.cpp.
◆ setMantissaScale()
|
static |
Changes which mantissa scale is used for normalization.
If you think you need to call this outside of unit tests, no you don't.
Definition at line 123 of file Number.cpp.
◆ minMantissa()
|
static |
◆ maxMantissa()
|
static |
◆ mantissaLog()
◆ one()
|
static |
Definition at line 519 of file Number.cpp.
◆ normalizeToRange()
|
nodiscard |
◆ normalize() [1/5]
|
private |
Definition at line 666 of file Number.cpp.
◆ normalize() [2/5]
|
staticprivate |
Normalize Number components to an arbitrary range.
min/maxMantissa are parameters because this function is used by both normalize(), which reads from kRange, and by normalizeToRange, which is public and can accept an arbitrary range from the caller.
◆ isnormal()
|
nodiscardprivatenoexcept |
◆ shiftExponent()
|
nodiscardprivate |
Definition at line 675 of file Number.cpp.
◆ externalToInternal()
|
staticprivate |
Definition at line 500 of file Number.cpp.
◆ normalize() [3/5]
|
staticprivate |
Definition at line 616 of file Number.cpp.
◆ normalize() [4/5]
|
staticprivate |
Definition at line 634 of file Number.cpp.
◆ normalize() [5/5]
|
staticprivate |
Definition at line 652 of file Number.cpp.
Friends And Related Symbol Documentation
◆ operator==
◆ operator!=
◆ operator<
◆ operator>
◆ operator<=
◆ operator>=
◆ operator<<
|
friend |
◆ to_string
|
friend |
Definition at line 1080 of file Number.cpp.
◆ root
Definition at line 1201 of file Number.cpp.
◆ root2
Definition at line 1275 of file Number.cpp.
◆ doNormalize
|
friend |
Definition at line 527 of file Number.cpp.
Member Data Documentation
◆ negative_
◆ mantissa_
|
private |
◆ exponent_
|
private |
◆ kMinExponent
◆ kMaxExponent
◆ kMaxRep
|
staticconstexpr |
◆ mode
|
thread_localstaticprivate |
◆ kRange
|
thread_localstaticprivate |
Generated by
1.16.1