diff --git a/README.md b/README.md index ac5fe9b..b70f901 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,15 @@ Arbitrary-precision fixed-point decimal numbers in go. -NOTE: can "only" represent numbers with a maximum of 2^31 digits after the decimal point. +_Note:_ Decimal library can "only" represent numbers with a maximum of 2^31 digits after the decimal point. ## Features - * the zero-value is 0, and is safe to use without initialization - * addition, subtraction, multiplication with no loss of precision - * division with specified precision - * database/sql serialization/deserialization - * json and xml serialization/deserialization + * The zero-value is 0, and is safe to use without initialization + * Addition, subtraction, multiplication with no loss of precision + * Division with specified precision + * Database/sql serialization/deserialization + * JSON and XML serialization/deserialization ## Install @@ -70,8 +70,8 @@ http://godoc.org/github.com/shopspring/decimal #### Why don't you just use float64? -Because float64s (or any binary floating point type, actually) can't represent -numbers such as 0.1 exactly. +Because float64 (or any binary floating point type, actually) can't represent +numbers such as `0.1` exactly. Consider this code: http://play.golang.org/p/TQBd4yJe6B You might expect that it prints out `10`, but it actually prints `9.999999999999831`. Over time, diff --git a/decimal-go.go b/decimal-go.go index e08a15c..9958d69 100644 --- a/decimal-go.go +++ b/decimal-go.go @@ -8,6 +8,7 @@ // Can do binary floating point in multiprecision decimal precisely // because 2 divides 10; cannot do decimal floating point // in multiprecision binary precisely. + package decimal type decimal struct { diff --git a/decimal.go b/decimal.go index 4badeb5..801c1a0 100644 --- a/decimal.go +++ b/decimal.go @@ -1,11 +1,5 @@ // Package decimal implements an arbitrary precision fixed-point decimal. // -// To use as part of a struct: -// -// type Struct struct { -// Number Decimal -// } -// // The zero-value of a Decimal is 0, as you would expect. // // The best way to create a new Decimal is to use decimal.NewFromString, ex: @@ -13,8 +7,13 @@ // n, err := decimal.NewFromString("-123.4567") // n.String() // output: "-123.4567" // -// NOTE: This can "only" represent numbers with a maximum of 2^31 digits -// after the decimal point. +// To use Decimal as part of a struct: +// +// type Struct struct { +// Number Decimal +// } +// +// Note: This can "only" represent numbers with a maximum of 2^31 digits after the decimal point. package decimal import ( @@ -32,14 +31,14 @@ import ( // // Example: // -// d1 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(3) +// d1 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(3)) // d1.String() // output: "0.6666666666666667" -// d2 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(30000) +// d2 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(30000)) // d2.String() // output: "0.0000666666666667" -// d3 := decimal.NewFromFloat(20000).Div(decimal.NewFromFloat(3) +// d3 := decimal.NewFromFloat(20000).Div(decimal.NewFromFloat(3)) // d3.String() // output: "6666.6666666666666667" // decimal.DivisionPrecision = 3 -// d4 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(3) +// d4 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(3)) // d4.String() // output: "0.667" // var DivisionPrecision = 16 @@ -53,6 +52,7 @@ var DivisionPrecision = 16 var MarshalJSONWithoutQuotes = false // Zero constant, to make computations faster. +// Zero should never be compared with == or != directly, please use decimal.Equal or decimal.Cmp instead. var Zero = New(0, 1) var zeroInt = big.NewInt(0) @@ -119,11 +119,13 @@ func NewFromBigInt(value *big.Int, exp int32) Decimal { } // NewFromString returns a new Decimal from a string representation. +// Trailing zeroes are not trimmed. // // Example: // // d, err := NewFromString("-123.45") // d2, err := NewFromString(".0001") +// d3, err := NewFromString("1.47000") // func NewFromString(value string) (Decimal, error) { originalInput := value @@ -207,7 +209,7 @@ func NewFromFloat(value float64) Decimal { return newFromFloat(value, math.Float64bits(value), &float64info) } -// NewFromFloat converts a float32 to Decimal. +// NewFromFloat32 converts a float32 to Decimal. // // The converted number will contain the number of significant digits that can be // represented in a float with reliable roundtrip. @@ -767,13 +769,13 @@ func (d Decimal) StringFixed(places int32) string { // // Example: // -// NewFromFloat(0).StringFixed(2) // output: "0.00" -// NewFromFloat(0).StringFixed(0) // output: "0" -// NewFromFloat(5.45).StringFixed(0) // output: "5" -// NewFromFloat(5.45).StringFixed(1) // output: "5.4" -// NewFromFloat(5.45).StringFixed(2) // output: "5.45" -// NewFromFloat(5.45).StringFixed(3) // output: "5.450" -// NewFromFloat(545).StringFixed(-1) // output: "550" +// NewFromFloat(0).StringFixedBank(2) // output: "0.00" +// NewFromFloat(0).StringFixedBank(0) // output: "0" +// NewFromFloat(5.45).StringFixedBank(0) // output: "5" +// NewFromFloat(5.45).StringFixedBank(1) // output: "5.4" +// NewFromFloat(5.45).StringFixedBank(2) // output: "5.45" +// NewFromFloat(5.45).StringFixedBank(3) // output: "5.450" +// NewFromFloat(545).StringFixedBank(-1) // output: "540" // func (d Decimal) StringFixedBank(places int32) string { rounded := d.RoundBank(places) @@ -1167,7 +1169,7 @@ func Avg(first Decimal, rest ...Decimal) Decimal { return sum.Div(count) } -// Rescale two decimals to common exponential value (minimal exp of both decimals) +// RescalePair rescales two decimals to common exponential value (minimal exp of both decimals) func RescalePair(d1 Decimal, d2 Decimal) (Decimal, Decimal) { d1.ensureInitialized() d2.ensureInitialized() diff --git a/rounding.go b/rounding.go index fdd74ea..8008f55 100644 --- a/rounding.go +++ b/rounding.go @@ -8,6 +8,7 @@ // Can do binary floating point in multiprecision decimal precisely // because 2 divides 10; cannot do decimal floating point // in multiprecision binary precisely. + package decimal type floatInfo struct {