From 35c4243da9c8c285a4b65117238dec9b9f7921c8 Mon Sep 17 00:00:00 2001 From: Qt Date: Wed, 28 Feb 2024 23:48:57 +0800 Subject: [PATCH] docs(math): update math docs (#19590) --- math/dec.go | 80 ++++++++++++++++++++++++++--------------------------- math/int.go | 6 ++-- 2 files changed, 43 insertions(+), 43 deletions(-) diff --git a/math/dec.go b/math/dec.go index 30d5ef464f..0ca1cfcb8c 100644 --- a/math/dec.go +++ b/math/dec.go @@ -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() diff --git a/math/int.go b/math/int.go index e08852fea8..5de32cbc37 100644 --- a/math/int.go +++ b/math/int.go @@ -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) }