Better doc

cosmos · Oct 27, 2024 · c28f9e8 · c28f9e8
1 parent 2213555
commit c28f9e8
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 15 deletions.
diff --git a/math/dec.go b/math/dec.go
@@ -11,6 +11,15 @@ import (
 
 var _ customProtobufType = &Dec{}
 
+const (
+	// MaxExponent is the highest exponent supported. Exponents near this range will
+	// perform very slowly (many seconds per operation).
+	MaxExponent = apd.MaxExponent
+	// MinExponent is the lowest exponent supported with the same limitations as
+	// MaxExponent.
+	MinExponent = apd.MinExponent
+)
+
 // Dec is a wrapper struct around apd.Decimal that does no mutation of apd.Decimal's when performing
 // arithmetic, instead creating a new apd.Decimal for every operation ensuring usage is safe.
 //
@@ -21,13 +30,6 @@ type Dec struct {
 	dec apd.Decimal
 }
 
-// constants for more convenient intent behind dec.Cmp values.
-const (
-	GreaterThan = 1
-	LessThan    = -1
-	EqualTo     = 0
-)
-
 const mathCodespace = "math"
 
 var (
@@ -42,8 +44,8 @@ var (
 // https://github.com/cosmos/cosmos-sdk/issues/7773#issuecomment-725006142
 var dec128Context = apd.Context{
 	Precision:   34,
-	MaxExponent: apd.MaxExponent,
-	MinExponent: apd.MinExponent,
+	MaxExponent: MaxExponent,
+	MinExponent: MinExponent,
 	Traps:       apd.DefaultTraps,
 }
 
@@ -96,6 +98,8 @@ func NewDecFromInt64(x int64) Dec {
 
 // NewDecWithExp creates a Dec from a coefficient and exponent, calculated as coeff * 10^exp.
 // Useful for precise decimal representations.
+// Although this method can be used with a higher than maximum exponent or lower than minimum exponent, further arithmetic
+// or other method may fail.
 //
 // Example:
 // - NewDecWithExp(123, -2) -> Dec representing 1.23.

diff --git a/math/dec_test.go b/math/dec_test.go
@@ -83,6 +83,22 @@ func TestNewDecFromString(t *testing.T) {
 			src: "-1.23e4",
 			exp: NewDecWithExp(-123, 2),
 		},
+		"exceed max exp 11E+1000000": {
+			src:    "11E+1000000",
+			expErr: ErrInvalidDec,
+		},
+		"exceed min exp 11E-1000000": {
+			src:    "11E-1000000",
+			expErr: ErrInvalidDec,
+		},
+		"exceed max exp 1E100001": {
+			src:    "1E100001",
+			expErr: ErrInvalidDec,
+		},
+		"exceed min exp 1E-100001": {
+			src:    "1E-100001",
+			expErr: ErrInvalidDec,
+		},
 		"empty string": {
 			src:    "",
 			expErr: ErrInvalidDec,
@@ -1298,8 +1314,9 @@ func must[T any](r T, err error) T {
 func TestMarshalUnmarshal(t *testing.T) {
 	t.Skip("not supported, yet")
 	specs := map[string]struct {
-		x   Dec
-		exp string
+		x      Dec
+		exp    string
+		expErr error
 	}{
 		"No trailing zeros": {
 			x:   NewDecFromInt64(123456),
@@ -1374,8 +1391,8 @@ func TestMarshalUnmarshal(t *testing.T) {
 			exp: "1E+100000",
 		},
 		"1.1e100000": {
-			x:   NewDecWithExp(11, 100_000),
-			exp: "1.1E+100001",
+			x:      NewDecWithExp(11, 100_000),
+			expErr: ErrInvalidDec,
 		},
 		"1.e100000": {
 			x:   NewDecWithExp(1, 100_000),
@@ -1384,8 +1401,12 @@ func TestMarshalUnmarshal(t *testing.T) {
 	}
 	for name, spec := range specs {
 		t.Run(name, func(t *testing.T) {
-			marshaled, err := spec.x.Marshal()
-			require.NoError(t, err)
+			marshaled, gotErr := spec.x.Marshal()
+			if spec.expErr != nil {
+				require.ErrorIs(t, gotErr, spec.expErr)
+				return
+			}
+			require.NoError(t, gotErr)
 			unmarshalled := new(Dec)
 			require.NoError(t, unmarshalled.Unmarshal(marshaled))
 			assert.Equal(t, spec.exp, unmarshalled.dec.Text('E'))