Merge branch 'master' into kardianos-decomposer

ericlagergren · Jun 25, 2019 · be32067 · be32067
2 parents 3627411 + cc8cbe2
commit be32067
Show file tree

Hide file tree

Showing 12 changed files with 446 additions and 357 deletions.
diff --git a/.gitignore b/.gitignore
@@ -19,28 +19,40 @@ _cgo_export.*
 
 _testmain.go
 
+# Artifacts, profiles, etc.
 *.exe
 *.test
 *.prof
-
 *.tags
-
 .git
 *.swp
 *.txt
 *.tags
-old.*
+tags
 *.test
 *.out
+*.zip
+*.gz
+
+# Internal
 literature/
 j/
-*.txt
-fuzz/
+
+# Fuzzing
+fuzz/**/corpus
+fuzz/**/crashers
+fuzz/**/suppressions
+
+# Benchmark artifacts
 benchmarks/decbench
 *.xml
 *.class
-*.gz
+.idea/
+benchmarks/regen.go
+
+# Development
 internal/nat/
+
+# Testing
 x.bash
-tags
-*.decTest
+*.decTest
diff --git a/README.md b/README.md
@@ -1,24 +1,37 @@
 # decimal [![Build Status](https://travis-ci.org/ericlagergren/decimal.png?branch=master)](https://travis-ci.org/ericlagergren/decimal) [![GoDoc](https://godoc.org/github.com/ericlagergren/decimal?status.svg)](https://godoc.org/github.com/ericlagergren/decimal)
 
-`decimal` is a high-performance, arbitrary precision, floating-point decimal
-library implementing the [General Decimal Arithmetic](http://speleotrove.com/decimal/) specification.
+`decimal` implements arbitrary precision, decimal floating-point numbers, per 
+the [General Decimal Arithmetic](http://speleotrove.com/decimal/) specification.
 
 ## Features
 
- * Zero-values are safe to use without initialization.
- * Multiple operating modes (GDA, Go) to fit your use cases.
+ * Useful zero values.
+   The zero value of a `decimal.Big` is 0, just like `math/big`.
+
+ * Multiple operating modes.
+   Different operating modes allow you to tailor the package's behavior to your
+   needs. The GDA mode strictly implements the GDA specification, while the Go
+   mode implements familiar Go idioms.
+
  * High performance.
- * A math library with elementary and trigonometric functions, continued fractions,
-   and more.
+   `decimal` is consistently one of the fastest arbitrary-precision decimal 
+   floating-point libraries, regardless of language.
+
+ * An extensive math library.
+   The `math/` subpackage implements elementary and trigonometric functions,
+   continued fractions, and more.
+
  * A familiar, idiomatic API.
+   `decimal`'s API follows `math/big`'s API, so there isn't a steep learning 
+   curve.
 
 ## Installation
 
 `go get github.com/ericlagergren/decimal`
 
 ## Documentation
 
-[Godoc](http://godoc.org/github.com/ericlagergren/decimal)
+[GoDoc](http://godoc.org/github.com/ericlagergren/decimal)
 
 ## Versioning
 
@@ -28,4 +41,4 @@ library implementing the [General Decimal Arithmetic](http://speleotrove.com/dec
 
 ## License
 
-The [BSD 3-clause](https://github.com/ericlagergren/decimal/blob/master/LICENSE)
+[BSD 3-clause](https://github.com/ericlagergren/decimal/blob/master/LICENSE)
diff --git a/benchmarks/doc.go b/benchmarks/doc.go
@@ -29,18 +29,18 @@
 //
 //    |    Program (version)                 | 9 digits | 19 digits | 38 digits | 100 digits | average |
 //    |--------------------------------------|----------|-----------|-----------|------------|---------|
-//    | go-inf/inf[8]                        | 0.241    | 0.537     | 1.12      | 3.01       | 1.227   |
-//    | ericlagergren/decimal[1] (mode Go)   | 0.142    | 0.639     | 1.46      | 4.16       | 1.60    |
-//    | Python decimal[5] (Python 3.7.3)     | 0.38     | 0.791     | 1.77      | 6.21       | 2.29    |
-//    | JDK BigDecimal[4] (Java 1.8, warm)   | 0.156    | 0.717     | 1.957     | 7.252      | 2.52    |
-//    | ericlagergren/decimal[1] (mode GDA)  | 0.204    | 0.953     | 2.37      | 8.40       | 2.98    |
-//    | JDK BigDecimal[4] (Java 1.8, cold)   | 0.532    | 1.638     | 3.413     | 7.747      | 3.332   |
-//    | shopspring/decimal[7] decimal        | 0.83     | 1.78      | 4.00      | 10.90      | 4.37    |
-//    | cockroachdb/apd[2]                   | 1.54     | 7.50      | 43.6      | 237.00     | 72.41   |
+//    | go-inf/inf[8]                        | 0.0912   | 0.201     | 0.426     | 1.280      | 0.499   |
+//    | ericlagergren/decimal[1] (mode Go)   | 0.0477   | 0.234     | 0.522     | 1.690      | 0.623   |
+//    | Python decimal[5] (Python 3.7.3)     | 0.143    | 0.322     | 0.657     | 2.325      | 0.862   |
+//    | JDK BigDecimal[4] (Java 1.8, warm)   | 0.0570   | 0.196     | 0.721     | 3.060      | 1.008   |
+//    | ericlagergren/decimal[1] (mode GDA)  | 0.0510   | 0.333     | 0.922     | 3.550      | 1.214   |
+//    | JDK BigDecimal[4] (Java 1.8, cold)   | 0.302    | 0.854     | 1.308     | 3.100      | 1.391   |
+//    | shopspring/decimal[7] decimal        | 0.289    | 0.700     | 1.490     | 4.120      | 1.649   |
+//    | cockroachdb/apd[2]                   | 0.564    | 2.410     | 10.000    | 78.300     | 22.818  |
 //    | Python decimal[6] (Python 2.7.10)    | 31.81    | 74.502    | 161.71    | 460.00     | 182.00  |
-//    | float64                              | 0.125    | -         | -         | -          | -       |
+//    | float64                              | 0.0557   | -         | -         | -          | -       |
 //    | double (C LLVM 10.0.1 -O3)           | 0.0589   | -         | -         | -          | -       |
-//    | apmckinlay/dnum[3]                   | 0.078    | -         | -         | -          | -       |
+//    | apmckinlay/dnum[3]                   | 0.0456   | -         | -         | -          | -       |
 //    | float (Python 2.7.10, 3.7.3)         | 0.0923   | -         | -         | -          | -       |
 //
 // Mandelbrot

diff --git a/benchmarks/mandelbrot_test.go b/benchmarks/mandelbrot_test.go
@@ -11,9 +11,10 @@ const mbrotiters = 10000000
 var two = decimal.New(2, 0)
 
 func BenchmarkMandelbrot_float64(b *testing.B) {
+	const x0, y0 = 0.222, 0.333
+
 	var lf float64
 	for i := 0; i < b.N; i++ {
-		x0, y0 := 0.222, 0.333
 		x, y := x0, y0
 		xx, yy := x*x, y*y
 		for j := 0; j < mbrotiters; j++ {
@@ -24,6 +25,7 @@ func BenchmarkMandelbrot_float64(b *testing.B) {
 			xx = x * x
 			yy = y * y
 		}
+		lf = x
 	}
 	gf = lf
 }
@@ -42,15 +44,15 @@ func BenchmarkMandelbrot_decimal_Go_38(b *testing.B) { benchMbrotGo(b, 38) }
 
 func benchMbrotGDA(b *testing.B, prec int) {
 	var (
-		ls  *decimal.Big
+		r   *decimal.Big
 		ctx = decimal.Context{Precision: prec, OperatingMode: decimal.GDA}
 		x0  = decimal.WithContext(ctx).SetMantScale(222, 3)
 		y0  = decimal.WithContext(ctx).SetMantScale(333, 3)
 	)
 	for i := 0; i < b.N; i++ {
-		ls = mbrotGDA(x0, y0, ctx, prec)
+		r = mbrotGDA(x0, y0, ctx, prec)
 	}
-	gs = ls
+	gdec = r
 }
 
 func mbrotGDA(x0, y0 *decimal.Big, ctx decimal.Context, prec int) *decimal.Big {
@@ -73,15 +75,15 @@ func mbrotGDA(x0, y0 *decimal.Big, ctx decimal.Context, prec int) *decimal.Big {
 
 func benchMbrotGo(b *testing.B, prec int) {
 	var (
-		ls  *decimal.Big
+		r   *decimal.Big
 		ctx = decimal.Context{Precision: prec, OperatingMode: decimal.GDA}
 		x0  = decimal.WithContext(ctx).SetMantScale(222, 3)
 		y0  = decimal.WithContext(ctx).SetMantScale(333, 3)
 	)
 	for i := 0; i < b.N; i++ {
-		ls = mbrotGo(x0, y0, ctx, prec)
+		r = mbrotGo(x0, y0, ctx, prec)
 	}
-	gs = ls
+	gdec = r
 }
 
 func mbrotGo(x0, y0 *decimal.Big, ctx decimal.Context, prec int) *decimal.Big {