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