Skip to content

Migrating from shopspring

This page describes how to move from shopspring/decimal v1.6.0 to udecimal. Most method names are the same. The main differences are that udecimal returns errors where shopspring panics, keeps at most 19 decimal places, truncates instead of rounding, and accepts fewer input formats.

The examples and the API mapping are tested against both libraries.

Behavior differences

Division by zero

Div, Mod and QuoRem return an error when the divisor is zero, where shopspring panics. To panic instead, use MustDiv, MustMod or MustQuoRem.

func() {
    defer func() { fmt.Println("shopspring:", recover()) }()
    decimal.NewFromInt(1).Div(decimal.Zero)
}()

_, err := udecimal.MustParse("1").Div(udecimal.Zero)
fmt.Println("udecimal:  ", err)
// Output:
// shopspring: decimal division by 0
// udecimal:   can't divide by zero

Decimal places

shopspring keeps every digit of its input. udecimal's Parse returns an error for more than 19 decimal places, or truncates them in ParseModeTrunc.

a, err := decimal.NewFromString("0.12345678901234567890123")
fmt.Println("shopspring:", a, err)

b, err := udecimal.Parse("0.12345678901234567890123")
fmt.Println("udecimal:  ", b, err)
// Output:
// shopspring: 0.12345678901234567890123 <nil>
// udecimal:   0 precision out of range. Only support maximum 19 digits after the decimal point

Input formats

shopspring's NewFromString also accepts exponents (1e5, 1.5E-3) and a decimal point without a digit on one side (.5, 1.). udecimal's Parse returns ErrInvalidFormat for these. shopspring's Scan also removes the quotes from a quoted string such as "1.5"; udecimal's Scan returns an error.

for _, s := range []string{"1e5", ".5", "1."} {
    a, aErr := decimal.NewFromString(s)
    b, bErr := udecimal.Parse(s)
    fmt.Printf("%-4s shopspring: %v %v, udecimal: %v %v\n", s, a, aErr, b, bErr)
}
// Output:
// 1e5  shopspring: 100000 <nil>, udecimal: 0 invalid format: can't parse '1e5'
// .5   shopspring: 0.5 <nil>, udecimal: 0 invalid format: can't parse '.5'
// 1.   shopspring: 1 <nil>, udecimal: 0 invalid format: can't parse '1.'

Division

shopspring's Div rounds the quotient half away from zero to DivisionPrecision decimal places, 16 by default. udecimal's Div keeps 19 decimal places and truncates the rest.

// shopspring's DivisionPrecision is 16 by default
fmt.Println("shopspring:", decimal.NewFromInt(2).Div(decimal.NewFromInt(3)))

q, _ := udecimal.MustParse("2").Div(udecimal.MustParse("3"))
fmt.Println("udecimal:  ", q)
// Output:
// shopspring: 0.6666666666666667
// udecimal:   0.6666666666666666666

Multiplication

shopspring's Mul is exact. udecimal's Mul keeps at most 19 decimal places and truncates the rest.

fmt.Println("shopspring:", decimal.RequireFromString("0.1234567890123456789").Mul(decimal.RequireFromString("0.1")))
fmt.Println("udecimal:  ", udecimal.MustParse("0.1234567890123456789").Mul(udecimal.MustParse("0.1")))
// Output:
// shopspring: 0.01234567890123456789
// udecimal:   0.0123456789012345678

StringFixed

shopspring's StringFixed(2) rounds to 2 decimal places. udecimal's StringFixed only pads with zeros, so round the value first if it has more decimal places.

fmt.Println("shopspring:", decimal.RequireFromString("1.235").StringFixed(2))
fmt.Println("udecimal:  ", udecimal.MustParse("1.235").StringFixed(2))
fmt.Println("udecimal:  ", udecimal.MustParse("1.235").RoundHAZ(2).StringFixed(2))
// Output:
// shopspring: 1.24
// udecimal:   1.235
// udecimal:   1.24

PowInt32

For 0^0, shopspring returns an error and udecimal returns 1. For a negative exponent, shopspring keeps PowPrecisionNegativeExponent decimal places, 16 by default, and udecimal keeps 19. For a positive exponent, shopspring is exact and udecimal keeps 19 decimal places.

_, err := decimal.Zero.PowInt32(0)
fmt.Println("shopspring:", err)

one, err := udecimal.Zero.PowInt32(0)
fmt.Println("udecimal:  ", one, err)

// a negative exponent: shopspring keeps PowPrecisionNegativeExponent (16) digits after the decimal point
a, _ := decimal.NewFromInt(3).PowInt32(-1)
b, _ := udecimal.MustParse("3").PowInt32(-1)
fmt.Println("shopspring:", a)
fmt.Println("udecimal:  ", b)
// Output:
// shopspring: cannot represent undefined value of 0**0
// udecimal:   1 <nil>
// shopspring: 0.3333333333333333
// udecimal:   0.3333333333333333333

Rounding method names

Round is RoundHAZ (half away from zero), Truncate and RoundDown are Trunc, and RoundUp is RoundAwayFromZero. udecimal also has RoundHTZ (half toward zero).

a := decimal.RequireFromString("-1.225")
fmt.Println("shopspring:", a.Round(2), a.RoundBank(2), a.Truncate(2))

b := udecimal.MustParse("-1.225")
fmt.Println("udecimal:  ", b.RoundHAZ(2), b.RoundBank(2), b.Trunc(2))
// Output:
// shopspring: -1.23 -1.22 -1.22
// udecimal:   -1.23 -1.22 -1.22

NullDecimal encoding

udecimal's NullDecimal implements only Scan and Value. shopspring's also implements MarshalJSON, UnmarshalJSON, MarshalText and UnmarshalText, so a NullDecimal field is encoded differently in JSON:

type row struct {
    A decimal.NullDecimal
    B udecimal.NullDecimal
}

b, _ := json.Marshal(row{})
fmt.Println(string(b))
// Output:
// {"A":null,"B":{"Decimal":"0","Valid":false}}

Binary encoding

Both libraries implement MarshalBinary and UnmarshalBinary, but the byte layouts differ, and udecimal returns invalid binary data for shopspring's output. Text, JSON and database/sql values are plain decimal strings in both libraries and can be exchanged if they have at most 19 decimal places, at most 200 characters and no exponent.

Package settings

shopspring's package variables and their udecimal equivalents:

  • DivisionPrecision: SetDefaultPrecision sets the number of decimal places for every operation and for parsing, not only for Div.
  • MarshalJSONWithoutQuotes: none. MarshalJSON always writes a quoted string, and UnmarshalJSON accepts both forms.
  • TrimTrailingZeros: none. String always removes trailing zeros; use StringFixed for a fixed number of decimal places.
  • PowPrecisionNegativeExponent: none. PowInt32 uses the default precision for negative exponents too.
  • UseScientificNotation: none. udecimal doesn't read or write scientific notation.
  • MaxDecodeExponent: none. udecimal doesn't accept exponents, and input is limited to 200 characters.
  • ExpMaxIterations: none. udecimal has no exponential functions.

API mapping

Creating values

shopspring udecimal Note
NewFromString Parse returns an error for more than 19 decimal places and for some formats shopspring accepts
RequireFromString MustParse
NewFromInt NewFromInt64(v, 0) returns an error
NewFromInt32 NewFromInt64(int64(v), 0)
NewFromUint64 NewFromUint64(v, 0) returns an error
New NewFromInt64(value, uint8(-exp)) for exp from 0 down to −19
NewFromFloat NewFromFloat64 returns an error
Zero Zero
NewNullDecimal NullDecimal{Decimal: d, Valid: true}
NewFromFloat32 no equivalent NewFromFloat64(float64(f)) gives the float64 digits: 0.10000000149011612 for float32(0.1), where shopspring gives 0.1
NewFromFloatWithExponent no equivalent NewFromFloat64, then a rounding method
NewFromBigInt no equivalent
NewFromBigRat no equivalent
NewFromBigFloat no equivalent
NewFromFormattedString no equivalent remove the formatting, then Parse

Arithmetic

shopspring udecimal Note
Add Add
Sub Sub
Mul Mul keeps at most 19 decimal places
Div Div returns an error; keeps 19 decimal places, truncated
DivRound Div, then RoundHAZ(p) the same result for p below 19
Mod Mod returns an error
QuoRem QuoRem no precision argument: the quotient is an integer, as with shopspring's precision 0; returns an error
PowInt32 PowInt32 differs at 0^0 and in precision
Sqrt Sqrt keeps 19 decimal places; shopspring keeps DivisionPrecision (16 by default)
Neg Neg
Abs Abs
Pow no equivalent PowInt32 for an integer exponent, PowToIntPart for the integer part of a Decimal exponent
PowWithPrecision no equivalent
PowBigInt no equivalent PowInt32
SqrtRound no equivalent Sqrt, then a rounding method
Root no equivalent
RootRound no equivalent
Ln no equivalent
ExpTaylor no equivalent
ExpHullAbrham no equivalent
Sin no equivalent
Cos no equivalent
Tan no equivalent
Atan no equivalent
Shift no equivalent Mul by a power of ten

Comparison

shopspring udecimal Note
Cmp Cmp
Compare Cmp
Equal Equal
Equals Equal deprecated in shopspring
GreaterThan GreaterThan
GreaterThanOrEqual GreaterThanOrEqual
LessThan LessThan
LessThanOrEqual LessThanOrEqual
IsZero IsZero
IsNegative IsNeg
IsPositive IsPos
Sign Sign
IsInteger no equivalent d.Equal(d.Trunc(0))

Rounding

shopspring udecimal Note
Round RoundHAZ half away from zero
RoundBank RoundBank half to even
RoundUp RoundAwayFromZero
RoundDown Trunc
Truncate Trunc
Floor Floor
Ceil Ceil
RoundCeil no equivalent Ceil rounds to an integer only
RoundFloor no equivalent Floor rounds to an integer only
RoundCash no equivalent

Conversion

shopspring udecimal Note
String String both drop trailing zeros
StringFixed StringFixed pads with zeros and doesn't round; see above
StringFixedBank RoundBank(p).StringFixed(p)
StringFixedCash no equivalent
StringScaled no equivalent
ScientificNotationString no equivalent
IntPart Int64 returns an error when the integer part doesn't fit in an int64
InexactFloat64 InexactFloat64
Float64 no equivalent InexactFloat64, without the exactness flag
Exponent -Prec() Prec is the number of decimal places
BigInt no equivalent
BigFloat no equivalent
Rat no equivalent
Coefficient no equivalent ToHiLo returns the 128-bit coefficient
CoefficientInt64 no equivalent
NumDigits no equivalent
Copy no equivalent values are immutable, so assign instead
Normalize no equivalent
Format no equivalent fmt prints a Decimal with String

Aggregates

shopspring udecimal Note
Avg Avg keeps 19 decimal places, like Div
Max Max
Min Min
Sum no equivalent Add in a loop
RescalePair no equivalent

Encoding

shopspring udecimal Note
MarshalJSON MarshalJSON always a quoted string
UnmarshalJSON UnmarshalJSON
MarshalText MarshalText
UnmarshalText UnmarshalText
MarshalBinary MarshalBinary a different byte layout
UnmarshalBinary UnmarshalBinary can't read shopspring's bytes
Scan Scan doesn't accept a quoted string
Value Value both store the string form
NullDecimal.Scan Scan
NullDecimal.Value Value
NullDecimal.MarshalJSON no equivalent encoded as a struct in JSON
NullDecimal.UnmarshalJSON no equivalent
NullDecimal.MarshalText no equivalent
NullDecimal.UnmarshalText no equivalent
NullDecimal.MarshalBSONValue no equivalent
NullDecimal.UnmarshalBSONValue no equivalent
NullDecimal.EncodeSpanner no equivalent
NullDecimal.DecodeSpanner no equivalent
GobEncode no equivalent
GobDecode no equivalent
MarshalBSONValue no equivalent
UnmarshalBSONValue no equivalent
EncodeSpanner no equivalent
DecodeSpanner no equivalent