Documentation ¶
Index ¶
- Constants
- Variables
- func AbsDifferenceWithSign(a, b sdk.Dec) (sdk.Dec, bool)
- func BinarySearch(f func(sdk.Int) (sdk.Int, error), lowerbound sdk.Int, upperbound sdk.Int, ...) (sdk.Int, error)
- func DecApproxEq(t *testing.T, d1 BigDec, d2 BigDec, tol BigDec) (*testing.T, bool, string, string, string)
- func DecEq(t *testing.T, exp, got BigDec) (*testing.T, bool, string, string, string)
- func DecsEqual(d1s, d2s []BigDec) bool
- func GetPowPrecision() sdk.Dec
- func IntEq(t *testing.T, exp, got BigInt) (*testing.T, bool, string, string, string)
- func MonotonicSqrt(d sdk.Dec) (sdk.Dec, error)
- func MustMonotonicSqrt(d sdk.Dec) sdk.Dec
- func Pow(base sdk.Dec, exp sdk.Dec) sdk.Dec
- func PowApprox(base sdk.Dec, exp sdk.Dec, precision sdk.Dec) sdk.Dec
- func SigFigRound(d sdk.Dec, tenToSigFig sdk.Int) sdk.Dec
- func SortableDecBytes(dec BigDec) []byte
- func ValidSortableDec(dec BigDec) bool
- type BigDec
- func BigDecFromSDKDec(d sdk.Dec) BigDec
- func BigDecFromSDKDecCoinSlice(ds []sdk.DecCoin) []BigDec
- func BigDecFromSDKDecSlice(ds []sdk.Dec) []BigDec
- func BinarySearchBigDec(f func(BigDec) BigDec, lowerbound BigDec, upperbound BigDec, ...) (BigDec, error)
- func DivCoinAmtsByU64ToBigDec(coins []sdk.Coin, scales []uint64, round RoundingDirection) ([]BigDec, error)
- func DivIntByU64ToBigDec(i sdk.Int, u uint64, round RoundingDirection) (BigDec, error)
- func Exp2(exponent BigDec) BigDec
- func MaxDec(d1, d2 BigDec) BigDec
- func MinDec(d1, d2 BigDec) BigDec
- func MustNewDecFromStr(s string) BigDec
- func NewBigDec(i int64) BigDec
- func NewDecFromBigInt(i *big.Int) BigDec
- func NewDecFromBigIntWithPrec(i *big.Int, prec int64) BigDec
- func NewDecFromInt(i BigInt) BigDec
- func NewDecFromIntWithPrec(i BigInt, prec int64) BigDec
- func NewDecFromStr(str string) (BigDec, error)
- func NewDecWithPrec(i, prec int64) BigDec
- func OneDec() BigDec
- func SmallestDec() BigDec
- func ZeroDec() BigDec
- func (d BigDec) Abs() BigDec
- func (d BigDec) Add(d2 BigDec) BigDec
- func (d BigDec) AddMut(d2 BigDec) BigDec
- func (d BigDec) ApproxRoot(root uint64) (guess BigDec, err error)
- func (d BigDec) ApproxSqrt() (BigDec, error)
- func (d BigDec) BigInt() *big.Int
- func (d BigDec) Ceil() BigDec
- func (d BigDec) Clone() BigDec
- func (x BigDec) CustomBaseLog(base BigDec) BigDec
- func (d BigDec) Equal(d2 BigDec) bool
- func (d BigDec) Float64() (float64, error)
- func (d BigDec) Format(s fmt.State, verb rune)
- func (d BigDec) GT(d2 BigDec) bool
- func (d BigDec) GTE(d2 BigDec) bool
- func (d BigDec) IsInteger() bool
- func (d BigDec) IsNegative() bool
- func (d BigDec) IsNil() bool
- func (d BigDec) IsPositive() bool
- func (d BigDec) IsZero() bool
- func (d BigDec) LT(d2 BigDec) bool
- func (d BigDec) LTE(d2 BigDec) bool
- func (x BigDec) Ln() BigDec
- func (x BigDec) LogBase2() BigDec
- func (d BigDec) Marshal() ([]byte, error)
- func (d BigDec) MarshalAmino() ([]byte, error)
- func (d BigDec) MarshalJSON() ([]byte, error)
- func (d *BigDec) MarshalTo(data []byte) (n int, err error)
- func (d BigDec) MarshalYAML() (interface{}, error)
- func (d BigDec) Mul(d2 BigDec) BigDec
- func (d BigDec) MulInt(i BigInt) BigDec
- func (d BigDec) MulInt64(i int64) BigDec
- func (d BigDec) MulMut(d2 BigDec) BigDec
- func (d BigDec) MulRoundUp(d2 BigDec) BigDec
- func (d BigDec) MulTruncate(d2 BigDec) BigDec
- func (d BigDec) MustFloat64() float64
- func (d BigDec) Neg() BigDec
- func (d BigDec) Power(power BigDec) BigDec
- func (d BigDec) PowerInteger(power uint64) BigDec
- func (d BigDec) PowerIntegerMut(power uint64) BigDec
- func (d BigDec) Quo(d2 BigDec) BigDec
- func (d BigDec) QuoInt(i BigInt) BigDec
- func (d BigDec) QuoInt64(i int64) BigDec
- func (d BigDec) QuoMut(d2 BigDec) BigDec
- func (d BigDec) QuoRaw(d2 int64) BigDec
- func (d BigDec) QuoRoundUp(d2 BigDec) BigDec
- func (d BigDec) QuoTruncate(d2 BigDec) BigDec
- func (d BigDec) RoundInt() BigInt
- func (d BigDec) RoundInt64() int64
- func (d BigDec) SDKDec() sdk.Dec
- func (d BigDec) SDKDecRoundUp() sdk.Dec
- func (d *BigDec) Size() int
- func (d BigDec) String() string
- func (d BigDec) Sub(d2 BigDec) BigDec
- func (x BigDec) TickLog() BigDec
- func (d BigDec) TruncateDec() BigDec
- func (d BigDec) TruncateInt() BigInt
- func (d BigDec) TruncateInt64() int64
- func (d *BigDec) Unmarshal(data []byte) error
- func (d *BigDec) UnmarshalAmino(bz []byte) error
- func (d *BigDec) UnmarshalJSON(bz []byte) error
- type BigInt
- func MaxInt(i, i2 BigInt) BigInt
- func MinInt(i1, i2 BigInt) BigInt
- func NewInt(n int64) BigInt
- func NewIntFromBigInt(i *big.Int) BigInt
- func NewIntFromString(s string) (res BigInt, ok bool)
- func NewIntFromUint64(n uint64) BigInt
- func NewIntWithDecimal(n int64, dec int) BigInt
- func OneInt() BigInt
- func ZeroInt() BigInt
- func (i BigInt) Abs() BigInt
- func (i BigInt) Add(i2 BigInt) (res BigInt)
- func (i BigInt) AddRaw(i2 int64) BigInt
- func (i BigInt) BigInt() *big.Int
- func (i BigInt) Equal(i2 BigInt) bool
- func (i BigInt) GT(i2 BigInt) bool
- func (i BigInt) GTE(i2 BigInt) bool
- func (i BigInt) Int64() int64
- func (i BigInt) IsInt64() bool
- func (i BigInt) IsNegative() bool
- func (i BigInt) IsNil() bool
- func (i BigInt) IsPositive() bool
- func (i BigInt) IsUint64() bool
- func (i BigInt) IsZero() bool
- func (i BigInt) LT(i2 BigInt) bool
- func (i BigInt) LTE(i2 BigInt) bool
- func (i BigInt) Marshal() ([]byte, error)
- func (i BigInt) MarshalAmino() ([]byte, error)
- func (i BigInt) MarshalJSON() ([]byte, error)
- func (i *BigInt) MarshalTo(data []byte) (n int, err error)
- func (i BigInt) MarshalYAML() (interface{}, error)
- func (i BigInt) Mod(i2 BigInt) BigInt
- func (i BigInt) ModRaw(i2 int64) BigInt
- func (i BigInt) Mul(i2 BigInt) (res BigInt)
- func (i BigInt) MulRaw(i2 int64) BigInt
- func (i BigInt) Neg() (res BigInt)
- func (i BigInt) Quo(i2 BigInt) (res BigInt)
- func (i BigInt) QuoRaw(i2 int64) BigInt
- func (i BigInt) Sign() int
- func (i *BigInt) Size() int
- func (i BigInt) String() string
- func (i BigInt) Sub(i2 BigInt) (res BigInt)
- func (i BigInt) SubRaw(i2 int64) BigInt
- func (i BigInt) ToDec() BigDec
- func (i BigInt) Uint64() uint64
- func (i *BigInt) Unmarshal(data []byte) error
- func (i *BigInt) UnmarshalAmino(bz []byte) error
- func (i *BigInt) UnmarshalJSON(bz []byte) error
- type ErrTolerance
- type RoundingDirection
- type SdkDec
Constants ¶
const ( // number of decimal places Precision = 36 // bytes required to represent the above precision // Ceiling[Log2[10**Precision - 1]] DecimalPrecisionBits = 120 )
Variables ¶
var ( ErrEmptyDecimalStr = errors.New("decimal string cannot be empty") ErrInvalidDecimalLength = errors.New("invalid decimal length") ErrInvalidDecimalStr = errors.New("invalid decimal string") )
Decimal errors
var MaxSortableDec = OneDec().Quo(SmallestDec())
MaxSortableDec is the largest Dec that can be passed into SortableDecBytes() Its negative form is the least Dec that can be passed in.
Functions ¶
func AbsDifferenceWithSign ¶
AbsDifferenceWithSign returns | a - b |, (a - b).sign() a is mutated and returned.
func BinarySearch ¶
func BinarySearch(f func(sdk.Int) (sdk.Int, error), lowerbound sdk.Int, upperbound sdk.Int, targetOutput sdk.Int, errTolerance ErrTolerance, maxIterations int, ) (sdk.Int, error)
Binary search inputs between [lowerbound, upperbound] to a monotonic increasing function f. We stop once f(found_input) meets the ErrTolerance constraints. If we perform more than maxIterations (or equivalently lowerbound = upperbound), we return an error.
func DecApproxEq ¶
func DecApproxEq(t *testing.T, d1 BigDec, d2 BigDec, tol BigDec) (*testing.T, bool, string, string, string)
DecApproxEq returns true if the differences between two given decimals are smaller than the tolerance range. Intended to be used with require/assert: require.True(t, DecEq(...))
func DecEq ¶
DecEq returns true if two given decimals are equal. Intended to be used with require/assert: require.True(t, DecEq(...))
func GetPowPrecision ¶
Returns the internal "power precision". All fractional exponentiation in percosis is expected to be accurate up to powPrecision. *technically* the error term can be greater than this powPrecision, but for small bases this bound applies. See comments in the PowApprox function for more detail.
func MonotonicSqrt ¶
Returns square root of d returns an error iff one of the following conditions is met: - d is negative - d is too small to have a representable square root. This function guarantees: the returned root r, will be such that r^2 >= d This function is monotonic, i.e. if d1 >= d2, then sqrt(d1) >= sqrt(d2)
func MustMonotonicSqrt ¶
MustMonotonicSqrt returns the output of MonotonicSqrt, panicking on error.
func Pow ¶
Pow computes base^(exp) However since the exponent is not an integer, we must do an approximation algorithm. TODO: In the future, lets add some optimized routines for common exponents, e.g. for common wIn / wOut ratios Many simple exponents like 2:1 pools.
func SigFigRound ¶
SigFigRound rounds to a specified significant figure.
func SortableDecBytes ¶
SortableDecBytes returns a byte slice representation of a Dec that can be sorted. Left and right pads with 0s so there are 18 digits to left and right of the decimal point. For this reason, there is a maximum and minimum value for this, enforced by ValidSortableDec.
func ValidSortableDec ¶
ValidSortableDec ensures that a Dec is within the sortable bounds, a BigDec can't have a precision of less than 10^-18. Max sortable decimal was set to the reciprocal of SmallestDec.
Types ¶
type BigDec ¶
type BigDec struct {
// contains filtered or unexported fields
}
NOTE: never use new(BigDec) or else we will panic unmarshalling into the nil embedded big.Int
func BigDecFromSDKDec ¶
BigDecFromSdkDec returns the BigDec representation of an SDKDec. Values in any additional decimal places are truncated.
func BigDecFromSDKDecCoinSlice ¶
BigDecFromSdkDecSlice returns the []BigDec representation of an []SDKDec. Values in any additional decimal places are truncated.
func BigDecFromSDKDecSlice ¶
BigDecFromSdkDecSlice returns the []BigDec representation of an []SDKDec. Values in any additional decimal places are truncated.
func BinarySearchBigDec ¶
func BinarySearchBigDec(f func(BigDec) BigDec, lowerbound BigDec, upperbound BigDec, targetOutput BigDec, errTolerance ErrTolerance, maxIterations int, ) (BigDec, error)
BinarySearchBigDec takes as input: * an input range [lowerbound, upperbound] * an increasing function f * a target output x * max number of iterations (for gas control / handling does-not-converge cases)
It binary searches on the input range, until it finds an input y s.t. f(y) meets the err tolerance constraints for how close it is to x. If we perform more than maxIterations (or equivalently lowerbound = upperbound), we return an error.
func DivIntByU64ToBigDec ¶
func Exp2 ¶
Exp2 takes 2 to the power of a given non-negative decimal exponent and returns the result. The computation is performed by using th following property: 2^decimal_exp = 2^{integer_exp + fractional_exp} = 2^integer_exp * 2^fractional_exp The max supported exponent is defined by the global maxSupportedExponent. If a greater exponent is given, the function panics. Panics if the exponent is negative. The answer is correct up to a factor of 10^-18. Meaning, result = result * k for k in [1 - 10^(-18), 1 + 10^(-18)] Note: our Python script plots show accuracy up to a factor of 10^22. However, in Go tests we only test up to 10^18. Therefore, this is the guarantee.
func MustNewDecFromStr ¶
Decimal from string, panic on error
func NewDecFromBigInt ¶
create a new BigDec from big integer assuming whole numbers CONTRACT: prec <= Precision
func NewDecFromBigIntWithPrec ¶
create a new BigDec from big integer assuming whole numbers CONTRACT: prec <= Precision
func NewDecFromInt ¶
create a new BigDec from big integer assuming whole numbers CONTRACT: prec <= Precision
func NewDecFromIntWithPrec ¶
create a new BigDec from big integer with decimal place at prec CONTRACT: prec <= Precision
func NewDecFromStr ¶
create a decimal from an input decimal string. valid must come in the form:
(-) whole integers (.) decimal integers
examples of acceptable input include:
-123.456 456.7890 345 -456789
NOTE - An error will return if more decimal places are provided in the string than the constant Precision.
CONTRACT - This function does not mutate the input str.
func NewDecWithPrec ¶
create a new BigDec from integer with decimal place at prec CONTRACT: prec <= Precision
func SmallestDec ¶
func SmallestDec() BigDec
func (BigDec) ApproxRoot ¶
ApproxRoot returns an approximate estimation of a Dec's positive real nth root using Newton's method (where n is positive). The algorithm starts with some guess and computes the sequence of improved guesses until an answer converges to an approximate answer. It returns `|d|.ApproxRoot() * -1` if input is negative. A maximum number of 100 iterations is used a backup boundary condition for cases where the answer never converges enough to satisfy the main condition.
func (BigDec) ApproxSqrt ¶
ApproxSqrt is a wrapper around ApproxRoot for the common special case of finding the square root of a number. It returns -(sqrt(abs(d)) if input is negative.
func (BigDec) Ceil ¶
Ceil returns the smallest interger value (as a decimal) that is greater than or equal to the given decimal.
func (BigDec) CustomBaseLog ¶
log_a(x) custom base logarithm Formula: log_a(b) = log_2(b) / log_2(a)
func (BigDec) Float64 ¶
Float64 returns the float64 representation of a BigDec. Will return the error if the conversion failed.
func (BigDec) IsNegative ¶
func (BigDec) IsPositive ¶
func (BigDec) LogBase2 ¶
LogBase2 returns log_2 {x}. Rounds down by truncations during division and right shifting. Accurate up to 32 precision digits. Implementation is based on: https://stm32duinoforum.com/forum/dsp/BinaryLogarithm.pdf
func (BigDec) MarshalAmino ¶
Override Amino binary serialization by proxying to protobuf.
func (BigDec) MarshalJSON ¶
MarshalJSON marshals the decimal
func (BigDec) MarshalYAML ¶
MarshalYAML returns the YAML representation.
func (BigDec) Mul ¶
Mut performs non-mutative multiplication. The receiver is not modifier but the result is.
func (BigDec) MulMut ¶
Mut performs non-mutative multiplication. The receiver is not modifier but the result is.
func (BigDec) MustFloat64 ¶
MustFloat64 returns the float64 representation of a BigDec. Would panic if the conversion failed.
func (BigDec) Power ¶
Power returns a result of raising the given big dec to a positive decimal power. Panics if the power is negative. Panics if the base is negative. Does not mutate the receiver. The max supported exponent is defined by the global maxSupportedExponent. If a greater exponent is given, the function panics. The error is not bounded but expected to be around 10^-18, use with care. See the underlying Exp2, LogBase2 and Mul for the details of their bounds. WARNING: This function is broken for base < 1. The reason is that logarithm function is negative between zero and 1, and the Exp2(k) is undefined for negative k. As a result, this function panics if called for d < 1.
func (BigDec) PowerInteger ¶
PowerInteger takes a given decimal to an integer power and returns the result. Non-mutative. Uses square and multiply algorithm for performing the calculation.
func (BigDec) PowerIntegerMut ¶
PowerIntegerMut takes a given decimal to an integer power and returns the result. Mutative. Uses square and multiply algorithm for performing the calculation.
func (BigDec) RoundInt64 ¶
RoundInt64 rounds the decimal using bankers rounding
func (BigDec) SDKDec ¶
SdkDec returns the Sdk.Dec representation of a BigDec. Values in any additional decimal places are truncated.
func (BigDec) SDKDecRoundUp ¶
SDKDecRoundUp returns the Sdk.Dec representation of a BigDec. Round up at precision end. Values in any additional decimal places are truncated.
func (BigDec) TickLog ¶
log_1.0001(x) "tick" base logarithm Formula: log_1.0001(b) = log_2(b) / log_2(1.0001)
func (BigDec) TruncateDec ¶
TruncateDec truncates the decimals from the number and returns a Dec
func (BigDec) TruncateInt ¶
TruncateInt truncates the decimals from the number and returns an Int
func (BigDec) TruncateInt64 ¶
TruncateInt64 truncates the decimals from the number and returns an int64
func (*BigDec) UnmarshalAmino ¶
func (*BigDec) UnmarshalJSON ¶
UnmarshalJSON defines custom decoding scheme
type BigInt ¶
type BigInt struct {
// contains filtered or unexported fields
}
Int wraps big.Int with a 257 bit range bound Checks overflow, underflow and division by zero Exists in range from -(2^256 - 1) to 2^256 - 1
func NewIntFromBigInt ¶
NewIntFromBigInt constructs Int from big.Int. If the provided big.Int is nil, it returns an empty instance. This function panics if the bit length is > 256.
func NewIntFromString ¶
NewIntFromString constructs Int from string
func NewIntFromUint64 ¶
NewIntFromUint64 constructs an Int from a uint64.
func NewIntWithDecimal ¶
NewIntWithDecimal constructs Int with decimal Result value is n*10^dec
func (BigInt) IsNegative ¶
IsNegative returns true if Int is negative
func (BigInt) IsPositive ¶
IsPositive returns true if Int is positive
func (BigInt) MarshalAmino ¶
Override Amino binary serialization by proxying to protobuf.
func (BigInt) MarshalJSON ¶
MarshalJSON defines custom encoding scheme
func (BigInt) MarshalYAML ¶
MarshalYAML returns the YAML representation.
func (*BigInt) UnmarshalAmino ¶
func (*BigInt) UnmarshalJSON ¶
UnmarshalJSON defines custom decoding scheme
type ErrTolerance ¶
type ErrTolerance struct { AdditiveTolerance sdk.Dec MultiplicativeTolerance sdk.Dec RoundingDir RoundingDirection }
ErrTolerance is used to define a compare function, which checks if two ints are within a certain error tolerance of one another, and (optionally) that they are rounding in the correct direction. ErrTolerance.Compare(a, b) returns true iff: * RoundingMode = RoundUp, then b >= a * RoundingMode = RoundDown, then b <= a * |a - b| <= AdditiveTolerance * |a - b| / min(a, b) <= MultiplicativeTolerance
Each check is respectively ignored if the entry is nil. So AdditiveTolerance = sdk.Int{} or sdk.ZeroInt() MultiplicativeTolerance = sdk.Dec{} RoundingDir = RoundUnconstrained. Note that if AdditiveTolerance == 0, then this is equivalent to a standard compare.
func (ErrTolerance) Compare ¶
Compare returns if actual is within errTolerance of expected. returns 0 if it is returns 1 if not, and expected > actual. returns -1 if not, and expected < actual
func (ErrTolerance) CompareBigDec ¶
func (e ErrTolerance) CompareBigDec(expected BigDec, actual BigDec) int
CompareBigDec validates if actual is within errTolerance of expected. returns 0 if it is returns 1 if not, and expected > actual. returns -1 if not, and expected < actual
func (ErrTolerance) EqualCoins ¶
EqualCoins returns true iff the two coins are equal within the ErrTolerance constraints and false otherwise. TODO: move error tolerance functions to a separate file.
type RoundingDirection ¶
type RoundingDirection int
const ( RoundUnconstrained RoundingDirection = 0 RoundUp RoundingDirection = 1 RoundDown RoundingDirection = 2 RoundBankers RoundingDirection = 3 )