LaconicNetwork/cosmos-sdk
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

docs(math): update math docs (#19590)

Browse Source
This commit is contained in:
Qt 2024-02-28 23:48:57 +08:00 committed by GitHub
parent e4d97090d8
commit 35c4243da9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 43 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
math/dec.go
View File

@ -10,17 +10,17 @@ import (
"testing"
)
// NOTE: never use new(Dec) or else we will panic unmarshalling into the
// LegacyDec NOTE: never use new(Dec) or else we will panic unmarshalling into the
// nil embedded big.Int
type LegacyDec struct {
i *big.Int
}
const (
// number of decimal places
// LegacyPrecision number of decimal places
LegacyPrecision = 18
// bits required to represent the above precision
// LegacyDecimalPrecisionBits bits required to represent the above precision
// Ceiling[Log2[10^Precision - 1]]
LegacyDecimalPrecisionBits = 60
@ -31,7 +31,7 @@ const (
maxDecBitLen = MaxBitLen + decimalTruncateBits
// max number of iterations in ApproxRoot function
// maxApproxRootIterations max number of iterations in ApproxRoot function
maxApproxRootIterations = 300
)
@ -94,12 +94,12 @@ func precisionMultiplier(prec int64) *big.Int {
return precisionMultipliers[prec]
}
// create a new Dec from integer assuming whole number
// LegacyNewDec create a new Dec from integer assuming whole number
func LegacyNewDec(i int64) LegacyDec {
return LegacyNewDecWithPrec(i, 0)
}
// create a new Dec from integer with decimal place at prec
// LegacyNewDecWithPrec create a new Dec from integer with decimal place at prec
// CONTRACT: prec <= Precision
func LegacyNewDecWithPrec(i, prec int64) LegacyDec {
bi := big.NewInt(i)
@ -108,13 +108,13 @@ func LegacyNewDecWithPrec(i, prec int64) LegacyDec {
}
}
// create a new Dec from big integer assuming whole numbers
// LegacyNewDecFromBigInt create a new Dec from big integer assuming whole numbers
// CONTRACT: prec <= Precision
func LegacyNewDecFromBigInt(i *big.Int) LegacyDec {
return LegacyNewDecFromBigIntWithPrec(i, 0)
}
// create a new Dec from big integer assuming whole numbers
// LegacyNewDecFromBigIntWithPrec create a new Dec from big integer assuming whole numbers
// CONTRACT: prec <= Precision
func LegacyNewDecFromBigIntWithPrec(i *big.Int, prec int64) LegacyDec {
return LegacyDec{
@ -122,13 +122,13 @@ func LegacyNewDecFromBigIntWithPrec(i *big.Int, prec int64) LegacyDec {
}
}
// create a new Dec from big integer assuming whole numbers
// LegacyNewDecFromInt create a new Dec from big integer assuming whole numbers
// CONTRACT: prec <= Precision
func LegacyNewDecFromInt(i Int) LegacyDec {
return LegacyNewDecFromIntWithPrec(i, 0)
}
// create a new Dec from big integer with decimal place at prec
// LegacyNewDecFromIntWithPrec create a new Dec from big integer with decimal place at prec
// CONTRACT: prec <= Precision
func LegacyNewDecFromIntWithPrec(i Int, prec int64) LegacyDec {
return LegacyDec{
@ -136,7 +136,7 @@ func LegacyNewDecFromIntWithPrec(i Int, prec int64) LegacyDec {
}
}
// create a decimal from an input decimal string.
// LegacyNewDecFromStr create a decimal from an input decimal string.
// valid must come in the form:
//
// (-) whole integers (.) decimal integers
@ -201,7 +201,7 @@ func LegacyNewDecFromStr(str string) (LegacyDec, error) {
return LegacyDec{combined}, nil
}
// Decimal from string, panic on error
// LegacyMustNewDecFromStr Decimal from string, panic on error
func LegacyMustNewDecFromStr(s string) LegacyDec {
dec, err := LegacyNewDecFromStr(s)
if err != nil {
@ -266,12 +266,12 @@ func (d LegacyDec) SetInt64(i int64) LegacyDec {
return d
}
// addition
// Add addition
func (d LegacyDec) Add(d2 LegacyDec) LegacyDec {
return d.ImmutOp(LegacyDec.AddMut, d2)
}
// mutable addition
// AddMut mutable addition
func (d LegacyDec) AddMut(d2 LegacyDec) LegacyDec {
d.i.Add(d.i, d2.i)
@ -281,12 +281,12 @@ func (d LegacyDec) AddMut(d2 LegacyDec) LegacyDec {
return d
}
// subtraction
// Sub subtraction
func (d LegacyDec) Sub(d2 LegacyDec) LegacyDec {
return d.ImmutOp(LegacyDec.SubMut, d2)
}
// mutable subtraction
// SubMut mutable subtraction
func (d LegacyDec) SubMut(d2 LegacyDec) LegacyDec {
d.i.Sub(d.i, d2.i)
@ -296,12 +296,12 @@ func (d LegacyDec) SubMut(d2 LegacyDec) LegacyDec {
return d
}
// multiplication
// Mul multiplication
func (d LegacyDec) Mul(d2 LegacyDec) LegacyDec {
return d.ImmutOp(LegacyDec.MulMut, d2)
}
// mutable multiplication
// MulMut mutable multiplication
func (d LegacyDec) MulMut(d2 LegacyDec) LegacyDec {
d.i.Mul(d.i, d2.i)
chopped := chopPrecisionAndRound(d.i)
@ -313,12 +313,12 @@ func (d LegacyDec) MulMut(d2 LegacyDec) LegacyDec {
return d
}
// multiplication truncate
// MulTruncate multiplication truncate
func (d LegacyDec) MulTruncate(d2 LegacyDec) LegacyDec {
return d.ImmutOp(LegacyDec.MulTruncateMut, d2)
}
// mutable multiplication truncage
// MulTruncateMut mutable multiplication truncate
func (d LegacyDec) MulTruncateMut(d2 LegacyDec) LegacyDec {
d.i.Mul(d.i, d2.i)
chopPrecisionAndTruncate(d.i)
@ -329,12 +329,12 @@ func (d LegacyDec) MulTruncateMut(d2 LegacyDec) LegacyDec {
return d
}
// multiplication round up at precision end.
// MulRoundUp multiplication round up at precision end.
func (d LegacyDec) MulRoundUp(d2 LegacyDec) LegacyDec {
return d.ImmutOp(LegacyDec.MulRoundUpMut, d2)
}
// mutable multiplication with round up at precision end.
// MulRoundUpMut mutable multiplication with round up at precision end.
func (d LegacyDec) MulRoundUpMut(d2 LegacyDec) LegacyDec {
d.i.Mul(d.i, d2.i)
chopPrecisionAndRoundUp(d.i)
@ -345,7 +345,7 @@ func (d LegacyDec) MulRoundUpMut(d2 LegacyDec) LegacyDec {
return d
}
// multiplication
// MulInt multiplication
func (d LegacyDec) MulInt(i Int) LegacyDec {
return d.ImmutOpInt(LegacyDec.MulIntMut, i)
}
@ -358,7 +358,7 @@ func (d LegacyDec) MulIntMut(i Int) LegacyDec {
return d
}
// MulInt64 - multiplication with int64
// MulInt64 multiplication with int64
func (d LegacyDec) MulInt64(i int64) LegacyDec {
return d.ImmutOpInt64(LegacyDec.MulInt64Mut, i)
}
@ -372,14 +372,14 @@ func (d LegacyDec) MulInt64Mut(i int64) LegacyDec {
return d
}
// quotient
// Quo quotient
func (d LegacyDec) Quo(d2 LegacyDec) LegacyDec {
return d.ImmutOp(LegacyDec.QuoMut, d2)
}
var squaredPrecisionReuse = new(big.Int).Mul(precisionReuse, precisionReuse)
// mutable quotient
// QuoMut mutable quotient
func (d LegacyDec) QuoMut(d2 LegacyDec) LegacyDec {
// multiply by precision twice
d.i.Mul(d.i, squaredPrecisionReuse)
@ -392,12 +392,12 @@ func (d LegacyDec) QuoMut(d2 LegacyDec) LegacyDec {
return d
}
// quotient truncate
// QuoTruncate quotient truncate
func (d LegacyDec) QuoTruncate(d2 LegacyDec) LegacyDec {
return d.ImmutOp(LegacyDec.QuoTruncateMut, d2)
}
// mutable quotient truncate
// QuoTruncateMut mutable quotient truncate
func (d LegacyDec) QuoTruncateMut(d2 LegacyDec) LegacyDec {
// multiply precision twice
d.i.Mul(d.i, squaredPrecisionReuse)
@ -410,12 +410,12 @@ func (d LegacyDec) QuoTruncateMut(d2 LegacyDec) LegacyDec {
return d
}
// quotient, round up
// QuoRoundUp quotient, round up
func (d LegacyDec) QuoRoundUp(d2 LegacyDec) LegacyDec {
return d.ImmutOp(LegacyDec.QuoRoundupMut, d2)
}
// mutable quotient, round up
// QuoRoundupMut mutable quotient, round up
func (d LegacyDec) QuoRoundupMut(d2 LegacyDec) LegacyDec {
// multiply precision twice
d.i.Mul(d.i, squaredPrecisionReuse)
@ -428,7 +428,7 @@ func (d LegacyDec) QuoRoundupMut(d2 LegacyDec) LegacyDec {
return d
}
// quotient
// QuoInt quotient
func (d LegacyDec) QuoInt(i Int) LegacyDec {
return d.ImmutOpInt(LegacyDec.QuoIntMut, i)
}
@ -438,7 +438,7 @@ func (d LegacyDec) QuoIntMut(i Int) LegacyDec {
return d
}
// QuoInt64 - quotient with int64
// QuoInt64 quotient with int64
func (d LegacyDec) QuoInt64(i int64) LegacyDec {
return d.ImmutOpInt64(LegacyDec.QuoInt64Mut, i)
}
@ -528,12 +528,12 @@ func (d LegacyDec) ApproxSqrt() (LegacyDec, error) {
return d.ApproxRoot(2)
}
// is integer, e.g. decimals are zero
// IsInteger is integer, e.g. decimals are zero
func (d LegacyDec) IsInteger() bool {
return new(big.Int).Rem(d.i, precisionReuse).Sign() == 0
}
// format decimal state
// Format format decimal state
func (d LegacyDec) Format(s fmt.State, verb rune) {
_, err := s.Write([]byte(d.String()))
if err != nil {
@ -756,14 +756,14 @@ func init() {
LegacyMaxSortableDec = LegacyOneDec().Quo(LegacySmallestDec())
}
// ValidSortableDec ensures that a Dec is within the sortable bounds,
// LegacyValidSortableDec 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 LegacyValidSortableDec(dec LegacyDec) bool {
return dec.Abs().LTE(LegacyMaxSortableDec)
}
// SortableDecBytes returns a byte slice representation of a Dec that can be sorted.
// LegacySortableDecBytes 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 LegacySortableDecBytes(dec LegacyDec) []byte {
@ -888,7 +888,7 @@ func (d *LegacyDec) Size() int {
return len(bz)
}
// Override Amino binary serialization by proxying to protobuf.
// MarshalAmino Override Amino binary serialization by proxying to protobuf.
func (d LegacyDec) MarshalAmino() ([]byte, error) { return d.Marshal() }
func (d *LegacyDec) UnmarshalAmino(bz []byte) error { return d.Unmarshal(bz) }
@ -908,7 +908,7 @@ func LegacyDecsEqual(d1s, d2s []LegacyDec) bool {
return true
}
// minimum decimal between two
// LegacyMinDec minimum decimal between two
func LegacyMinDec(d1, d2 LegacyDec) LegacyDec {
if d1.LT(d2) {
return d1
@ -916,7 +916,7 @@ func LegacyMinDec(d1, d2 LegacyDec) LegacyDec {
return d2
}
// maximum decimal between two
// LegacyMaxDec maximum decimal between two
func LegacyMaxDec(d1, d2 LegacyDec) LegacyDec {
if d1.LT(d2) {
return d2
@ -924,7 +924,7 @@ func LegacyMaxDec(d1, d2 LegacyDec) LegacyDec {
return d1
}
// intended to be used with require/assert: require.True(DecEq(...))
// LegacyDecEq intended to be used with require/assert: require.True(DecEq(...))
func LegacyDecEq(t *testing.T, exp, got LegacyDec) (*testing.T, bool, string, string, string) {
t.Helper()
return t, exp.Equal(got), "expected:\t%v\ngot:\t\t%v", exp.String(), got.String()

6
math/int.go
View File

@ -102,7 +102,7 @@ func (i Int) BigInt() *big.Int {
return new(big.Int).Set(i.i)
}
// BigInt converts Int to big.Int, mutative the input
// BigIntMut converts Int to big.Int, mutative the input
func (i Int) BigIntMut() *big.Int {
if i.IsNil() {
return nil
@ -404,7 +404,7 @@ func (i Int) Abs() Int {
return Int{abs(i.i)}
}
// return the minimum of the ints
// MinInt return the minimum of the ints
func MinInt(i1, i2 Int) Int {
return Int{min(i1.BigInt(), i2.BigInt())}
}
@ -517,7 +517,7 @@ func (i *Int) Size() int {
return len(bz)
}
// Override Amino binary serialization by proxying to protobuf.
// MarshalAmino Override Amino binary serialization by proxying to protobuf.
func (i Int) MarshalAmino() ([]byte, error) { return i.Marshal() }
func (i *Int) UnmarshalAmino(bz []byte) error { return i.Unmarshal(bz) }