1// Copyright 2016 The Cockroach Authors.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
12// implied. See the License for the specific language governing
13// permissions and limitations under the License.
14
15/*
16Package apd implements arbitrary-precision decimals.
17
18apd implements much of the decimal specification from the General
19Decimal Arithmetic (http://speleotrove.com/decimal/) description, which
20is refered to here as GDA. This is the same specification implemented by
21pythons decimal module (https://docs.python.org/2/library/decimal.html)
22and GCCs decimal extension.
23
24Features
25
26Panic-free operation. The math/big types don’t return errors, and instead
27panic under some conditions that are documented. This requires users to
28validate the inputs before using them. Meanwhile, we’d like our decimal
29operations to have more failure modes and more input requirements than the
30math/big types, so using that API would be difficult. apd instead returns
31errors when needed.
32
33Support for standard functions. sqrt, ln, pow, etc.
34
35Accurate and configurable precision. Operations will use enough internal
36precision to produce a correct result at the requested precision. Precision
37is set by a "context" structure that accompanies the function arguments,
38as discussed in the next section.
39
40Good performance. Operations will either be fast enough or will produce an
41error if they will be slow. This prevents edge-case operations from consuming
42lots of CPU or memory.
43
44Condition flags and traps. All operations will report whether their
45result is exact, is rounded, is over- or under-flowed, is subnormal
46(https://en.wikipedia.org/wiki/Denormal_number), or is some other
47condition. apd supports traps which will trigger an error on any of these
48conditions. This makes it possible to guarantee exactness in computations,
49if needed.
50
51SQL scan and value methods are implemented. This allows the use of Decimals as
52placeholder parameters and row result Scan destinations.
53
54Usage
55
56apd has two main types. The first is Decimal which holds the values of
57decimals. It is simple and uses a big.Int with an exponent to describe
58values. Most operations on Decimals can’t produce errors as they work
59directly on the underlying big.Int. Notably, however, there are no arithmetic
60operations on Decimals.
61
62The second main type is Context, which is where all arithmetic operations
63are defined. A Context describes the precision, range, and some other
64restrictions during operations. These operations can all produce failures,
65and so return errors.
66
67Context operations, in addition to errors, return a Condition, which is a
68bitfield of flags that occurred during an operation. These include overflow,
69underflow, inexact, rounded, and others. The Traps field of a Context can be
70set which will produce an error if the corresponding flag occurs. An example
71of this is given below.
72
73*/
74package apd
75