Documentation ¶
Overview ¶
Package math implements custom Cosmos SDK math types used for arithmetic operations. Signed and unsigned integer types utilize Golang's standard library big integers types, having a maximum bit length of 256 bits.
Index ¶
- Constants
- Variables
- func FormatDec(v string) (string, error)
- func FormatInt(v string) (string, error)
- func IntEq(t *testing.T, exp, got Int) (*testing.T, bool, string, string, string)
- func LegacyDecApproxEq(t *testing.T, d1, d2, tol LegacyDec) (*testing.T, bool, string, string, string)
- func LegacyDecEq(t *testing.T, exp, got LegacyDec) (*testing.T, bool, string, string, string)
- func LegacyDecsEqual(d1s, d2s []LegacyDec) bool
- func LegacySortableDecBytes(dec LegacyDec) []byte
- func LegacyValidSortableDec(dec LegacyDec) bool
- func Max[T constraints.Ordered](a, b T, rest ...T) T
- func Min[T constraints.Ordered](a, b T, rest ...T) T
- func UintOverflow(i *big.Int) error
- type Int
- func MaxInt(i, i2 Int) Int
- func MinInt(i1, i2 Int) Int
- func NewInt(n int64) Int
- func NewIntFromBigInt(i *big.Int) Int
- func NewIntFromBigIntMut(i *big.Int) Int
- func NewIntFromString(s string) (res Int, ok bool)
- func NewIntFromUint64(n uint64) Int
- func NewIntWithDecimal(n int64, dec int) Int
- func OneInt() Int
- func ZeroInt() Int
- func (i Int) Abs() Int
- func (i Int) Add(i2 Int) (res Int)
- func (i Int) AddRaw(i2 int64) Int
- func (i Int) BigInt() *big.Int
- func (i Int) BigIntMut() *big.Int
- func (i Int) Equal(i2 Int) bool
- func (i Int) GT(i2 Int) bool
- func (i Int) GTE(i2 Int) bool
- func (i Int) Int64() int64
- func (i Int) IsInt64() bool
- func (i Int) IsNegative() bool
- func (i Int) IsNil() bool
- func (i Int) IsPositive() bool
- func (i Int) IsUint64() bool
- func (i Int) IsZero() bool
- func (i Int) LT(i2 Int) bool
- func (i Int) LTE(i2 Int) bool
- func (i Int) Marshal() ([]byte, error)
- func (i Int) MarshalAmino() ([]byte, error)
- func (i Int) MarshalJSON() ([]byte, error)
- func (i *Int) MarshalTo(data []byte) (n int, err error)
- func (i Int) MarshalYAML() (interface{}, error)
- func (i Int) Mod(i2 Int) Int
- func (i Int) ModRaw(i2 int64) Int
- func (i Int) Mul(i2 Int) (res Int)
- func (i Int) MulRaw(i2 int64) Int
- func (i Int) Neg() (res Int)
- func (i Int) Quo(i2 Int) (res Int)
- func (i Int) QuoRaw(i2 int64) Int
- func (i Int) SafeAdd(i2 Int) (res Int, err error)
- func (i Int) SafeMod(i2 Int) (res Int, err error)
- func (i Int) SafeMul(i2 Int) (res Int, err error)
- func (i Int) SafeQuo(i2 Int) (res Int, err error)
- func (i Int) SafeSub(i2 Int) (res Int, err error)
- func (i Int) Sign() int
- func (i *Int) Size() int
- func (i Int) String() string
- func (i Int) Sub(i2 Int) (res Int)
- func (i Int) SubRaw(i2 int64) Int
- func (i Int) ToLegacyDec() LegacyDec
- func (i Int) Uint64() uint64
- func (i *Int) Unmarshal(data []byte) error
- func (i *Int) UnmarshalAmino(bz []byte) error
- func (i *Int) UnmarshalJSON(bz []byte) error
- type LegacyDec
- func LegacyMaxDec(d1, d2 LegacyDec) LegacyDec
- func LegacyMinDec(d1, d2 LegacyDec) LegacyDec
- func LegacyMustNewDecFromStr(s string) LegacyDec
- func LegacyNewDec(i int64) LegacyDec
- func LegacyNewDecFromBigInt(i *big.Int) LegacyDec
- func LegacyNewDecFromBigIntWithPrec(i *big.Int, prec int64) LegacyDec
- func LegacyNewDecFromInt(i Int) LegacyDec
- func LegacyNewDecFromIntWithPrec(i Int, prec int64) LegacyDec
- func LegacyNewDecFromStr(str string) (LegacyDec, error)
- func LegacyNewDecWithPrec(i, prec int64) LegacyDec
- func LegacyOneDec() LegacyDec
- func LegacySmallestDec() LegacyDec
- func LegacyZeroDec() LegacyDec
- func (d LegacyDec) Abs() LegacyDec
- func (d LegacyDec) AbsMut() LegacyDec
- func (d LegacyDec) Add(d2 LegacyDec) LegacyDec
- func (d LegacyDec) AddMut(d2 LegacyDec) LegacyDec
- func (d LegacyDec) ApproxRoot(root uint64) (guess LegacyDec, err error)
- func (d LegacyDec) ApproxSqrt() (LegacyDec, error)
- func (d LegacyDec) BigInt() *big.Int
- func (d LegacyDec) BigIntMut() *big.Int
- func (d LegacyDec) Ceil() LegacyDec
- func (d LegacyDec) Clone() LegacyDec
- func (d LegacyDec) Equal(d2 LegacyDec) bool
- func (d LegacyDec) Float64() (float64, error)
- func (d LegacyDec) Format(s fmt.State, verb rune)
- func (d LegacyDec) GT(d2 LegacyDec) bool
- func (d LegacyDec) GTE(d2 LegacyDec) bool
- func (d LegacyDec) ImmutOp(op func(LegacyDec, LegacyDec) LegacyDec, d2 LegacyDec) LegacyDec
- func (d LegacyDec) ImmutOpInt(op func(LegacyDec, Int) LegacyDec, d2 Int) LegacyDec
- func (d LegacyDec) ImmutOpInt64(op func(LegacyDec, int64) LegacyDec, d2 int64) LegacyDec
- func (d LegacyDec) IsInteger() bool
- func (d LegacyDec) IsNegative() bool
- func (d LegacyDec) IsNil() bool
- func (d LegacyDec) IsPositive() bool
- func (d LegacyDec) IsZero() bool
- func (d LegacyDec) LT(d2 LegacyDec) bool
- func (d LegacyDec) LTE(d2 LegacyDec) bool
- func (d LegacyDec) Marshal() ([]byte, error)
- func (d LegacyDec) MarshalAmino() ([]byte, error)
- func (d LegacyDec) MarshalJSON() ([]byte, error)
- func (d *LegacyDec) MarshalTo(data []byte) (n int, err error)
- func (d LegacyDec) MarshalYAML() (interface{}, error)
- func (d LegacyDec) Mul(d2 LegacyDec) LegacyDec
- func (d LegacyDec) MulInt(i Int) LegacyDec
- func (d LegacyDec) MulInt64(i int64) LegacyDec
- func (d LegacyDec) MulInt64Mut(i int64) LegacyDec
- func (d LegacyDec) MulIntMut(i Int) LegacyDec
- func (d LegacyDec) MulMut(d2 LegacyDec) LegacyDec
- func (d LegacyDec) MulRoundUp(d2 LegacyDec) LegacyDec
- func (d LegacyDec) MulRoundUpMut(d2 LegacyDec) LegacyDec
- func (d LegacyDec) MulTruncate(d2 LegacyDec) LegacyDec
- func (d LegacyDec) MulTruncateMut(d2 LegacyDec) LegacyDec
- func (d LegacyDec) MustFloat64() float64
- func (d LegacyDec) Neg() LegacyDec
- func (d LegacyDec) NegMut() LegacyDec
- func (d LegacyDec) Power(power uint64) LegacyDec
- func (d LegacyDec) PowerMut(power uint64) LegacyDec
- func (d LegacyDec) Quo(d2 LegacyDec) LegacyDec
- func (d LegacyDec) QuoInt(i Int) LegacyDec
- func (d LegacyDec) QuoInt64(i int64) LegacyDec
- func (d LegacyDec) QuoInt64Mut(i int64) LegacyDec
- func (d LegacyDec) QuoIntMut(i Int) LegacyDec
- func (d LegacyDec) QuoMut(d2 LegacyDec) LegacyDec
- func (d LegacyDec) QuoRoundUp(d2 LegacyDec) LegacyDec
- func (d LegacyDec) QuoRoundupMut(d2 LegacyDec) LegacyDec
- func (d LegacyDec) QuoTruncate(d2 LegacyDec) LegacyDec
- func (d LegacyDec) QuoTruncateMut(d2 LegacyDec) LegacyDec
- func (d LegacyDec) RoundInt() Int
- func (d LegacyDec) RoundInt64() int64
- func (d LegacyDec) Set(d2 LegacyDec) LegacyDec
- func (d LegacyDec) SetInt64(i int64) LegacyDec
- func (d *LegacyDec) Size() int
- func (d LegacyDec) String() string
- func (d LegacyDec) Sub(d2 LegacyDec) LegacyDec
- func (d LegacyDec) SubMut(d2 LegacyDec) LegacyDec
- func (d LegacyDec) TruncateDec() LegacyDec
- func (d LegacyDec) TruncateInt() Int
- func (d LegacyDec) TruncateInt64() int64
- func (d *LegacyDec) Unmarshal(data []byte) error
- func (d *LegacyDec) UnmarshalAmino(bz []byte) error
- func (d *LegacyDec) UnmarshalJSON(bz []byte) error
- type Uint
- func (u Uint) Add(u2 Uint) Uint
- func (u Uint) AddUint64(u2 uint64) Uint
- func (u Uint) BigInt() *big.Int
- func (u Uint) BigIntMut() *big.Int
- func (u Uint) Decr() Uint
- func (u Uint) Equal(u2 Uint) bool
- func (u Uint) GT(u2 Uint) bool
- func (u Uint) GTE(u2 Uint) bool
- func (u Uint) Incr() Uint
- func (u Uint) IsNil() bool
- func (u Uint) IsZero() bool
- func (u Uint) LT(u2 Uint) bool
- func (u Uint) LTE(u2 Uint) bool
- func (u Uint) Marshal() ([]byte, error)
- func (u Uint) MarshalAmino() ([]byte, error)
- func (u Uint) MarshalJSON() ([]byte, error)
- func (u *Uint) MarshalTo(data []byte) (n int, err error)
- func (u Uint) Mod(u2 Uint) Uint
- func (u Uint) Mul(u2 Uint) (res Uint)
- func (u Uint) MulUint64(u2 uint64) (res Uint)
- func (u Uint) Quo(u2 Uint) (res Uint)
- func (u Uint) QuoUint64(u2 uint64) Uint
- func (u *Uint) Size() int
- func (u Uint) String() string
- func (u Uint) Sub(u2 Uint) Uint
- func (u Uint) SubUint64(u2 uint64) Uint
- func (u Uint) Uint64() uint64
- func (u *Uint) Unmarshal(data []byte) error
- func (u *Uint) UnmarshalAmino(bz []byte) error
- func (u *Uint) UnmarshalJSON(bz []byte) error
Constants ¶
const ( // number of decimal places LegacyPrecision = 18 // bits required to represent the above precision // Ceiling[Log2[10^Precision - 1]] LegacyDecimalPrecisionBits = 60 )
const MaxBitLen = 256
MaxBitLen defines the maximum bit length supported bit Int and Uint types.
Variables ¶
var ( ErrLegacyEmptyDecimalStr = errors.New("decimal string cannot be empty") ErrLegacyInvalidDecimalLength = errors.New("invalid decimal length") ErrLegacyInvalidDecimalStr = errors.New("invalid decimal string") )
Decimal errors
var ( // ErrIntOverflow is the error returned when an integer overflow occurs ErrIntOverflow = errors.New("integer overflow") // ErrDivideByZero is the error returned when a divide by zero occurs ErrDivideByZero = errors.New("divide by zero") )
Integer errors
Functions ¶
func FormatDec ¶
FormatDec formats a decimal (as encoded in protobuf) into a value-rendered string following ADR-050. This function operates with string manipulation (instead of manipulating the sdk.Dec object).
func FormatInt ¶
FormatInt formats an integer (encoded as in protobuf) into a value-rendered string following ADR-050. This function operates with string manipulation (instead of manipulating the int or math.Int object).
func IntEq ¶
intended to be used with require/assert: require.True(IntEq(...))
func LegacyDecApproxEq ¶
func LegacyDecEq ¶
intended to be used with require/assert: require.True(DecEq(...))
func LegacyDecsEqual ¶
test if two decimal arrays are equal
func LegacySortableDecBytes ¶
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 LegacyValidSortableDec ¶
ValidSortableDec ensures that a Dec is within the sortable bounds, a Dec can't have a precision of less than 10^-18. Max sortable decimal was set to the reciprocal of SmallestDec.
func Max ¶
func Max[T constraints.Ordered](a, b T, rest ...T) T
func Min ¶
func Min[T constraints.Ordered](a, b T, rest ...T) T
Types ¶
type Int ¶
type Int struct {
// contains filtered or unexported fields
}
Int wraps big.Int with a 256 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. Note, the caller can safely mutate the argument after this function returns.
func NewIntFromBigIntMut ¶ added in v1.2.0
NewIntFromBigIntMut 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. Note, this function mutate the argument.
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 (Int) BigIntMut ¶ added in v1.2.0
BigInt converts Int to big.Int, mutative the input
func (Int) GTE ¶
GTE returns true if receiver Int is greater than or equal to the parameter Int.
func (Int) Int64 ¶
Int64 converts Int to int64 Panics if the value is out of range
func (Int) LTE ¶
LTE returns true if first Int is less than or equal to second
func (Int) Marshal ¶
Marshal implements the gogo proto custom type interface.
func (Int) MarshalAmino ¶
Override Amino binary serialization by proxying to protobuf.
func (Int) MarshalJSON ¶
MarshalJSON defines custom encoding scheme
func (*Int) MarshalTo ¶
MarshalTo implements the gogo proto custom type interface.
func (Int) MarshalYAML ¶
MarshalYAML returns the YAML representation.
func (Int) ModRaw ¶
ModRaw returns remainder after dividing with int64
func (Int) SafeAdd ¶ added in v1.3.0
SafeAdd adds Int from another and returns an error if overflow
func (Int) SafeMod ¶ added in v1.3.0
SafeMod returns remainder after dividing with Int and returns an error if division by zero
func (Int) SafeMul ¶ added in v1.3.0
SafeMul multiples Int from another and returns an error if overflow
func (Int) SafeQuo ¶ added in v1.3.0
SafeQuo divides Int with Int and returns an error if division by zero
func (Int) SafeSub ¶ added in v1.3.0
SafeSub subtracts Int from another and returns an error if overflow or underflow
func (Int) ToLegacyDec ¶ added in v1.1.0
ToLegacyDec converts Int to LegacyDec
func (Int) Uint64 ¶
Uint64 converts Int to uint64 Panics if the value is out of range
func (*Int) Unmarshal ¶
Unmarshal implements the gogo proto custom type interface.
type LegacyDec ¶
type LegacyDec struct {
// contains filtered or unexported fields
}
NOTE: never use new(Dec) or else we will panic unmarshalling into the nil embedded big.Int
var LegacyMaxSortableDec LegacyDec
LegacyMaxSortableDec is the largest Dec that can be passed into SortableDecBytes() Its negative form is the least Dec that can be passed in.
func LegacyMustNewDecFromStr ¶
Decimal from string, panic on error
func LegacyNewDec ¶
create a new Dec from integer assuming whole number
func LegacyNewDecFromBigInt ¶
create a new Dec from big integer assuming whole numbers CONTRACT: prec <= Precision
func LegacyNewDecFromBigIntWithPrec ¶
create a new Dec from big integer assuming whole numbers CONTRACT: prec <= Precision
func LegacyNewDecFromInt ¶
create a new Dec from big integer assuming whole numbers CONTRACT: prec <= Precision
func LegacyNewDecFromIntWithPrec ¶
create a new Dec from big integer with decimal place at prec CONTRACT: prec <= Precision
func LegacyNewDecFromStr ¶
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 LegacyNewDecWithPrec ¶
create a new Dec from integer with decimal place at prec CONTRACT: prec <= Precision
func (LegacyDec) 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 (LegacyDec) 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 (LegacyDec) BigInt ¶
BigInt returns a copy of the underlying big.Int.
func (LegacyDec) BigIntMut ¶ added in v1.3.0
BigIntMut converts LegacyDec to big.Int, mutative the input
func (LegacyDec) Ceil ¶
Ceil returns the smallest integer value (as a decimal) that is greater than or equal to the given decimal.
func (LegacyDec) Float64 ¶
Float64 returns the float64 representation of a Dec. Will return the error if the conversion failed.
func (LegacyDec) ImmutOp ¶
func (LegacyDec) ImmutOpInt ¶
func (LegacyDec) ImmutOpInt64 ¶
func (LegacyDec) Marshal ¶
Marshal implements the gogo proto custom type interface.
func (LegacyDec) MarshalAmino ¶
Override Amino binary serialization by proxying to protobuf.
func (LegacyDec) MarshalJSON ¶
MarshalJSON marshals the decimal
func (*LegacyDec) MarshalTo ¶
MarshalTo implements the gogo proto custom type interface.
func (LegacyDec) MarshalYAML ¶
MarshalYAML returns the YAML representation.
func (LegacyDec) MulInt64 ¶
MulInt64 - multiplication with int64
func (LegacyDec) MulRoundUp ¶ added in v1.1.0
multiplication round up at precision end.
func (LegacyDec) MulRoundUpMut ¶ added in v1.1.0
mutable multiplication with round up at precision end.
func (LegacyDec) MulTruncate ¶
multiplication truncate
func (LegacyDec) MulTruncateMut ¶
mutable multiplication truncage
func (LegacyDec) MustFloat64 ¶
MustFloat64 returns the float64 representation of a Dec. Would panic if the conversion failed.
func (LegacyDec) Power ¶
Power returns a the result of raising to a positive integer power
func (LegacyDec) QuoInt64 ¶
QuoInt64 - quotient with int64
func (LegacyDec) QuoRoundUp ¶
quotient, round up
func (LegacyDec) QuoRoundupMut ¶
mutable quotient, round up
func (LegacyDec) QuoTruncate ¶
quotient truncate
func (LegacyDec) QuoTruncateMut ¶
mutable quotient truncate
func (LegacyDec) RoundInt ¶
RoundInt round the decimal using bankers rounding
func (LegacyDec) RoundInt64 ¶
RoundInt64 rounds the decimal using bankers rounding
func (*LegacyDec) Size ¶
Size implements the gogo proto custom type interface.
func (LegacyDec) TruncateDec ¶
TruncateDec truncates the decimals from the number and returns a Dec
func (LegacyDec) TruncateInt ¶
TruncateInt truncates the decimals from the number and returns an Int
func (LegacyDec) TruncateInt64 ¶
TruncateInt64 truncates the decimals from the number and returns an int64
func (*LegacyDec) Unmarshal ¶
Unmarshal implements the gogo proto custom type interface.
type Uint ¶
type Uint struct {
// contains filtered or unexported fields
}
Uint wraps integer with 256 bit range bound Checks overflow, underflow and division by zero Exists in range from 0 to 2^256-1
func NewUintFromBigInt ¶
NewUintFromBigInt constructs Uint from big.Int Panics if i is negative or wider than 256 bits
func NewUintFromString ¶
NewUintFromString constructs Uint from string Panics if parsed s is negative or wider than 256 bits
func ParseUint ¶
ParseUint reads a string-encoded Uint value and return a Uint.
func RelativePow ¶
RelativePow raises x to the power of n, where x (and the result, z) are scaled by factor b for example, RelativePow(210, 2, 100) = 441 (2.1^2 = 4.41)
func (Uint) AddUint64 ¶
Add convert uint64 and add it to Uint
func (Uint) BigIntMut ¶ added in v1.2.0
BigInt converts Uint to big.Int, mutative the input
func (Uint) Decr ¶
Decr decrements the Uint by one. Decr will panic if the Uint is zero.
func (Uint) GT ¶
GT returns true if first Uint is greater than second
func (Uint) GTE ¶
GTE returns true if first Uint is greater than second
func (Uint) LTE ¶
LTE returns true if first Uint is lesser than or equal to the second
func (Uint) Marshal ¶
Marshal implements the gogo proto custom type interface.
func (Uint) MarshalAmino ¶
Override Amino binary serialization by proxying to protobuf.
func (Uint) MarshalJSON ¶
MarshalJSON defines custom encoding scheme
func (*Uint) MarshalTo ¶
MarshalTo implements the gogo proto custom type interface.
func (Uint) Mod ¶
Mod returns remainder after dividing with Uint Panics if u2 is zero
func (Uint) Uint64 ¶
Uint64 converts Uint to uint64 Panics if the value is out of range
func (*Uint) Unmarshal ¶
Unmarshal implements the gogo proto custom type interface.