Merge pull request #103 from nvanbenschoten/nvanbenschoten/bigInt2

apd: embed small coefficient values in Decimal struct

.github/workflows/go.yml

@@ -15,8 +15,6 @@ jobs:
     strategy:
       matrix:
         go:
-          - '1.11'
-          - '1.12'
           - '1.13'
           - '1.14'
           - '1.15'
@@ -38,11 +36,12 @@ jobs:
         run: go test -v ./...
 
       - name: 'Vet'
-        run: go vet ./...
+        # -unsafeptr=false is needed because of the noescape function in bigint.go.
+        run: go vet -unsafeptr=false ./...
 
       - name: 'Staticcheck'
         # staticcheck requires go1.14.
-        if: ${{ matrix.go != '1.11' && matrix.go != '1.12' && matrix.go != '1.13' }}
+        if: ${{ matrix.go != '1.13' }}
         run: |
           go get honnef.co/go/tools/cmd/staticcheck
           staticcheck ./...

README.md

@@ -12,13 +12,17 @@ apd is an arbitrary-precision decimal package for Go.
 - **Good performance**. Operations will either be fast enough or will produce an error if they will be slow. This prevents edge-case operations from consuming lots of CPU or memory.
 - **Condition flags and traps**. All operations will report whether their result is exact, is rounded, is over- or under-flowed, is [subnormal](https://en.wikipedia.org/wiki/Denormal_number), or is some other condition. `apd` supports traps which will trigger an error on any of these conditions. This makes it possible to guarantee exactness in computations, if needed.
 
-`apd` has two main types. The first is [`Decimal`](https://godoc.org/github.com/cockroachdb/apd#Decimal) which holds the values of decimals. It is simple and uses a `big.Int` with an exponent to describe values. Most operations on `Decimal`s can’t produce errors as they work directly on the underlying `big.Int`. Notably, however, there are no arithmetic operations on `Decimal`s.
+`apd` has three main types.
 
-The second main type is [`Context`](https://godoc.org/github.com/cockroachdb/apd#Context), which is where all arithmetic operations are defined. A `Context` describes the precision, range, and some other restrictions during operations. These operations can all produce failures, and so return errors.
+The first is [`BigInt`](https://godoc.org/github.com/cockroachdb/apd#BigInt) which is a wrapper around `big.Int` that exposes an identical API while reducing memory allocations. `BigInt` does so by using an inline array to back the `big.Int`'s variable-length value when the integer's absolute value is sufficiently small. `BigInt` also contains fast-paths that allow it to perform basic arithmetic directly on this inline array, only falling back to `big.Int` when the arithmetic gets complex or takes place on large values.
+
+The second is [`Decimal`](https://godoc.org/github.com/cockroachdb/apd#Decimal) which holds the values of decimals. It is simple and uses a `BigInt` with an exponent to describe values. Most operations on `Decimal`s can’t produce errors as they work directly on the underlying `big.Int`. Notably, however, there are no arithmetic operations on `Decimal`s.
+
+The third main type is [`Context`](https://godoc.org/github.com/cockroachdb/apd#Context), which is where all arithmetic operations are defined. A `Context` describes the precision, range, and some other restrictions during operations. These operations can all produce failures, and so return errors.
 
 `Context` operations, in addition to errors, return a [`Condition`](https://godoc.org/github.com/cockroachdb/apd#Condition), which is a bitfield of flags that occurred during an operation. These include overflow, underflow, inexact, rounded, and others. The `Traps` field of a `Context` can be set which will produce an error if the corresponding flag occurs. An example of this is given below.
 
 See the [examples](https://godoc.org/github.com/cockroachdb/apd#pkg-examples) for some operations that were previously difficult to perform in Go.
 
 ## Documentation
-https://pkg.go.dev/github.com/cockroachdb/apd/v2?tab=doc
+https://pkg.go.dev/github.com/cockroachdb/apd/v3?tab=doc