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