Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update documentation, clean up package level documentation #173

Merged
merged 3 commits into from
Apr 28, 2020
Merged

Update documentation, clean up package level documentation #173

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cdb7942
Update documentation, clean up package level documentation
mwoss Apr 25, 2020
4173d2c
Add parentheses to NewFromFloat docs
mwoss Apr 26, 2020
710e0d2
Revert remove of docs
mwoss Apr 27, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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,
Expand Down
6 changes: 0 additions & 6 deletions decimal-go.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,6 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Multiprecision decimal numbers.
// For floating-point formatting only; not general purpose.
// Only operations are assign and (binary) left/right shift.
// Can do binary floating point in multiprecision decimal precisely
// because 2 divides 10; cannot do decimal floating point
// in multiprecision binary precisely.
package decimal
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think just adding an extra newline will omit the comments from godoc: Comments that are not adjacent to a top-level declaration are omitted from godoc's output https://blog.golang.org/godoc

It would be good to keep the comments in this file and rounding.go and not have them show up in godoc if we can

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great, I had no idea about that. I will fix it after work. :3


type decimal struct {
Expand Down
44 changes: 23 additions & 21 deletions decimal.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,19 @@
// 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:
//
// 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 (
Expand All @@ -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
Expand All @@ -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)

// fiveDec used in Cash Rounding
Expand Down Expand Up @@ -122,11 +122,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
Expand Down Expand Up @@ -210,7 +212,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.
Expand Down Expand Up @@ -771,13 +773,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)
Expand Down Expand Up @@ -1171,7 +1173,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()
Expand Down
6 changes: 0 additions & 6 deletions rounding.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,6 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Multiprecision decimal numbers.
// For floating-point formatting only; not general purpose.
// Only operations are assign and (binary) left/right shift.
// 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 {
Expand Down