Sync upstream

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: ci
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+jobs:
+  ci-job:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go: [ '1.10.x', '1.19', '1.20', '1.21', '1.22', '1.x' ]
+    name: Go ${{ matrix.go }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+      - run: go build .
+      - run: go test -v

.gitignore

@@ -1,2 +1,9 @@
 .git
 *.swp
+
+# IntelliJ
+.idea/
+*.iml
+
+# VS code
+*.code-workspace

CHANGELOG.md

@@ -0,0 +1,76 @@
+## Decimal v1.4.0
+#### BREAKING
+- Drop support for Go version older than 1.10 [#361](/~https://github.com/shopspring/decimal/pull/361)
+
+#### FEATURES
+- Add implementation of natural logarithm [#339](/~https://github.com/shopspring/decimal/pull/339) [#357](/~https://github.com/shopspring/decimal/pull/357)
+- Add improved implementation of power operation [#358](/~https://github.com/shopspring/decimal/pull/358)
+- Add Compare method which forwards calls to Cmp [#346](/~https://github.com/shopspring/decimal/pull/346)
+- Add NewFromBigRat constructor [#288](/~https://github.com/shopspring/decimal/pull/288)
+- Add NewFromUint64 constructor [#352](/~https://github.com/shopspring/decimal/pull/352)
+
+#### ENHANCEMENTS
+- Migrate to Github Actions [#245](/~https://github.com/shopspring/decimal/pull/245) [#340](/~https://github.com/shopspring/decimal/pull/340)
+- Fix examples for RoundDown, RoundFloor, RoundUp, and RoundCeil [#285](/~https://github.com/shopspring/decimal/pull/285) [#328](/~https://github.com/shopspring/decimal/pull/328) [#341](/~https://github.com/shopspring/decimal/pull/341)
+- Use Godoc standard to mark deprecated Equals and StringScaled methods [#342](/~https://github.com/shopspring/decimal/pull/342)
+- Removed unnecessary min function for RescalePair method [#265](/~https://github.com/shopspring/decimal/pull/265)
+- Avoid reallocation of initial slice in MarshalBinary (GobEncode) [#355](/~https://github.com/shopspring/decimal/pull/355)
+- Optimize NumDigits method [#301](/~https://github.com/shopspring/decimal/pull/301) [#356](/~https://github.com/shopspring/decimal/pull/356)
+- Optimize BigInt method [#359](/~https://github.com/shopspring/decimal/pull/359)
+- Support scanning uint64 [#131](/~https://github.com/shopspring/decimal/pull/131) [#364](/~https://github.com/shopspring/decimal/pull/364)
+- Add docs section with alternative libraries [#363](/~https://github.com/shopspring/decimal/pull/363)
+
+#### BUGFIXES
+- Fix incorrect calculation of decimal modulo [#258](/~https://github.com/shopspring/decimal/pull/258) [#317](/~https://github.com/shopspring/decimal/pull/317)
+- Allocate new(big.Int) in Copy method to deeply clone it [#278](/~https://github.com/shopspring/decimal/pull/278)
+- Fix overflow edge case in QuoRem method [#322](/~https://github.com/shopspring/decimal/pull/322)
+
+## Decimal v1.3.1
+
+#### ENHANCEMENTS
+- Reduce memory allocation in case of initialization from big.Int [#252](/~https://github.com/shopspring/decimal/pull/252)
+
+#### BUGFIXES
+- Fix binary marshalling of decimal zero value  [#253](/~https://github.com/shopspring/decimal/pull/253)
+
+## Decimal v1.3.0
+
+#### FEATURES
+- Add NewFromFormattedString initializer [#184](/~https://github.com/shopspring/decimal/pull/184)
+- Add NewNullDecimal initializer [#234](/~https://github.com/shopspring/decimal/pull/234)
+- Add implementation of natural exponent function (Taylor, Hull-Abraham) [#229](/~https://github.com/shopspring/decimal/pull/229)
+- Add RoundUp, RoundDown, RoundCeil, RoundFloor methods [#196](/~https://github.com/shopspring/decimal/pull/196) [#202](/~https://github.com/shopspring/decimal/pull/202) [#220](/~https://github.com/shopspring/decimal/pull/220)
+- Add XML support for NullDecimal [#192](/~https://github.com/shopspring/decimal/pull/192)
+- Add IsInteger method [#179](/~https://github.com/shopspring/decimal/pull/179)
+- Add Copy helper method [#123](/~https://github.com/shopspring/decimal/pull/123)
+- Add InexactFloat64 helper method [#205](/~https://github.com/shopspring/decimal/pull/205)
+- Add CoefficientInt64 helper method [#244](/~https://github.com/shopspring/decimal/pull/244)
+
+#### ENHANCEMENTS
+- Performance optimization of NewFromString init method [#198](/~https://github.com/shopspring/decimal/pull/198)
+- Performance optimization of Abs and Round methods [#240](/~https://github.com/shopspring/decimal/pull/240)
+- Additional tests (CI) for ppc64le architecture [#188](/~https://github.com/shopspring/decimal/pull/188)
+
+#### BUGFIXES
+- Fix rounding in FormatFloat fallback path (roundShortest method, fix taken from Go main repository) [#161](/~https://github.com/shopspring/decimal/pull/161)
+- Add slice range checks to UnmarshalBinary method [#232](/~https://github.com/shopspring/decimal/pull/232)
+
+## Decimal v1.2.0
+
+#### BREAKING
+- Drop support for Go version older than 1.7 [#172](/~https://github.com/shopspring/decimal/pull/172)
+
+#### FEATURES
+- Add NewFromInt and NewFromInt32 initializers [#72](/~https://github.com/shopspring/decimal/pull/72)
+- Add support for Go modules [#157](/~https://github.com/shopspring/decimal/pull/157)
+- Add BigInt, BigFloat helper methods [#171](/~https://github.com/shopspring/decimal/pull/171)
+
+#### ENHANCEMENTS
+- Memory usage optimization [#160](/~https://github.com/shopspring/decimal/pull/160)
+- Updated travis CI golang versions [#156](/~https://github.com/shopspring/decimal/pull/156)
+- Update documentation [#173](/~https://github.com/shopspring/decimal/pull/173)
+- Improve code quality [#174](/~https://github.com/shopspring/decimal/pull/174)
+
+#### BUGFIXES
+- Revert remove insignificant digits [#159](/~https://github.com/shopspring/decimal/pull/159)
+- Remove 15 interval for RoundCash [#166](/~https://github.com/shopspring/decimal/pull/166)

README.md

@@ -1,23 +1,34 @@
 # decimal
 
-[![Build Status](https://travis-ci.org/shopspring/decimal.png?branch=master)](https://travis-ci.org/shopspring/decimal) [![GoDoc](https://godoc.org/github.com/shopspring/decimal?status.svg)](https://godoc.org/github.com/shopspring/decimal) [![Go Report Card](https://goreportcard.com/badge/github.com/shopspring/decimal)](https://goreportcard.com/report/github.com/shopspring/decimal)
+[![ci](/~https://github.com/shopspring/decimal/actions/workflows/ci.yml/badge.svg?branch=master)](/~https://github.com/shopspring/decimal/actions/workflows/ci.yml)
+[![GoDoc](https://godoc.org/github.com/shopspring/decimal?status.svg)](https://godoc.org/github.com/shopspring/decimal) 
+[![Go Report Card](https://goreportcard.com/badge/github.com/shopspring/decimal)](https://goreportcard.com/report/github.com/shopspring/decimal)
 
 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
 
 Run `go get github.com/shopspring/decimal`
 
+## Requirements 
+
+Decimal library requires Go version `>=1.10`
+
+## Documentation
+
+http://godoc.org/github.com/shopspring/decimal
+
+
 ## Usage
 
 ```go
@@ -34,7 +45,7 @@ func main() {
 		panic(err)
 	}
 
-	quantity := decimal.NewFromFloat(3)
+	quantity := decimal.NewFromInt(3)
 
 	fee, _ := decimal.NewFromString(".035")
 	taxRate, _ := decimal.NewFromString(".08875")
@@ -53,21 +64,23 @@ func main() {
 }
 ```
 
-## Documentation
-
-http://godoc.org/github.com/shopspring/decimal
+## Alternative libraries
 
-## Production Usage
+When working with decimal numbers, you might face problems this library is not perfectly suited for. 
+Fortunately, thanks to the wonderful community we have a dozen other libraries that you can choose from.  
+Explore other alternatives to find the one that best fits your needs :)  
 
-* [Spring](https://shopspring.com/), since August 14, 2014.
-* If you are using this in production, please let us know!
+* [cockroachdb/apd](/~https://github.com/cockroachdb/apd) - arbitrary precision, mutable and rich API similar to `big.Int`, more performant than this library 
+* [alpacahq/alpacadecimal](/~https://github.com/alpacahq/alpacadecimal) - high performance, low precision (12 digits), fully compatible API with this library 
+* [govalues/decimal](/~https://github.com/govalues/decimal) - high performance, zero-allocation, low precision (19 digits)
+* [greatcloak/decimal](/~https://github.com/greatcloak/decimal) - fork focusing on billing and e-commerce web application related use cases, includes out-of-the-box BSON marshaling support
 
 ## FAQ
 
 #### 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,

const.go

@@ -0,0 +1,63 @@
+package decimal
+
+import (
+	"strings"
+)
+
+const (
+	strLn10 = "2.302585092994045684017991454684364207601101488628772976033327900967572609677352480235997205089598298341967784042286248633409525465082806756666287369098781689482907208325554680843799894826233198528393505308965377732628846163366222287698219886746543667474404243274365155048934314939391479619404400222105101714174800368808401264708068556774321622835522011480466371565912137345074785694768346361679210180644507064800027750268491674655058685693567342067058113642922455440575892572420824131469568901675894025677631135691929203337658714166023010570308963457207544037084746994016826928280848118428931484852494864487192780967627127577539702766860595249671667418348570442250719796500471495105049221477656763693866297697952211071826454973477266242570942932258279850258550978526538320760672631716430950599508780752371033310119785754733154142180842754386359177811705430982748238504564801909561029929182431823752535770975053956518769751037497088869218020518933950723853920514463419726528728696511086257149219884997874887377134568620916705849807828059751193854445009978131146915934666241071846692310107598438319191292230792503747298650929009880391941702654416816335727555703151596113564846546190897042819763365836983716328982174407366009162177850541779276367731145041782137660111010731042397832521894898817597921798666394319523936855916447118246753245630912528778330963604262982153040874560927760726641354787576616262926568298704957954913954918049209069438580790032763017941503117866862092408537949861264933479354871737451675809537088281067452440105892444976479686075120275724181874989395971643105518848195288330746699317814634930000321200327765654130472621883970596794457943468343218395304414844803701305753674262153675579814770458031413637793236291560128185336498466942261465206459942072917119370602444929358037007718981097362533224548366988505528285966192805098447175198503666680874970496982273220244823343097169111136813588418696549323714996941979687803008850408979618598756579894836445212043698216415292987811742973332588607915912510967187510929248475023930572665446276200923068791518135803477701295593646298412366497023355174586195564772461857717369368404676577047874319780573853271810933883496338813069945569399346101090745616033312247949360455361849123333063704751724871276379140924398331810164737823379692265637682071706935846394531616949411701841938119405416449466111274712819705817783293841742231409930022911502362192186723337268385688273533371925103412930705632544426611429765388301822384091026198582888433587455960453004548370789052578473166283701953392231047527564998119228742789713715713228319641003422124210082180679525276689858180956119208391760721080919923461516952599099473782780648128058792731993893453415320185969711021407542282796298237068941764740642225757212455392526179373652434440560595336591539160312524480149313234572453879524389036839236450507881731359711238145323701508413491122324390927681724749607955799151363982881058285740538000653371655553014196332241918087621018204919492651483892"
+)
+
+var (
+	ln10 = newConstApproximation(strLn10)
+)
+
+type constApproximation struct {
+	exact          Decimal
+	approximations []Decimal
+}
+
+func newConstApproximation(value string) constApproximation {
+	parts := strings.Split(value, ".")
+	coeff, fractional := parts[0], parts[1]
+
+	coeffLen := len(coeff)
+	maxPrecision := len(fractional)
+
+	var approximations []Decimal
+	for p := 1; p < maxPrecision; p *= 2 {
+		r := RequireFromString(value[:coeffLen+p])
+		approximations = append(approximations, r)
+	}
+
+	return constApproximation{
+		RequireFromString(value),
+		approximations,
+	}
+}
+
+// Returns the smallest approximation available that's at least as precise
+// as the passed precision (places after decimal point), i.e. Floor[ log2(precision) ] + 1
+func (c constApproximation) withPrecision(precision int32) Decimal {
+	i := 0
+
+	if precision >= 1 {
+		i++
+	}
+
+	for precision >= 16 {
+		precision /= 16
+		i += 4
+	}
+
+	for precision >= 2 {
+		precision /= 2
+		i++
+	}
+
+	if i >= len(c.approximations) {
+		return c.exact
+	}
+
+	return c.approximations[i]
+}

const_test.go

@@ -0,0 +1,34 @@
+package decimal
+
+import "testing"
+
+func TestConstApproximation(t *testing.T) {
+	for _, testCase := range []struct {
+		Const                 string
+		Precision             int32
+		ExpectedApproximation string
+	}{
+		{"2.3025850929940456840179914546", 0, "2"},
+		{"2.3025850929940456840179914546", 1, "2.3"},
+		{"2.3025850929940456840179914546", 3, "2.302"},
+		{"2.3025850929940456840179914546", 5, "2.302585"},
+		{"2.3025850929940456840179914546", 10, "2.302585092994045"},
+		{"2.3025850929940456840179914546", 100, "2.3025850929940456840179914546"},
+		{"2.3025850929940456840179914546", -1, "2"},
+		{"2.3025850929940456840179914546", -5, "2"},
+		{"3.14159265359", 0, "3"},
+		{"3.14159265359", 1, "3.1"},
+		{"3.14159265359", 2, "3.141"},
+		{"3.14159265359", 4, "3.1415926"},
+		{"3.14159265359", 13, "3.14159265359"},
+	} {
+		ca := newConstApproximation(testCase.Const)
+		expected, _ := NewFromString(testCase.ExpectedApproximation)
+
+		approximation := ca.withPrecision(testCase.Precision)
+
+		if approximation.Cmp(expected) != 0 {
+			t.Errorf("expected approximation %s, got %s - for const with %s precision %d", testCase.ExpectedApproximation, approximation.String(), testCase.Const, testCase.Precision)
+		}
+	}
+}

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 {