1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
|
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* Decimal floating point library for Java
*
* <p>Another floating point class. This one is built using radix 10000 which is 10<sup>4</sup>, so
* its almost decimal.
*
* <p>The design goals here are:
*
* <ol>
* <li>Decimal math, or close to it
* <li>Settable precision (but no mix between numbers using different settings)
* <li>Portability. Code should be keep as portable as possible.
* <li>Performance
* <li>Accuracy - Results should always be +/- 1 ULP for basic algebraic operation
* <li>Comply with IEEE 854-1987 as much as possible. (See IEEE 854-1987 notes below)
* </ol>
*
* <p>Trade offs:
*
* <ol>
* <li>Memory foot print. I'm using more memory than necessary to represent numbers to get better
* performance.
* <li>Digits are bigger, so rounding is a greater loss. So, if you really need 12 decimal digits,
* better use 4 base 10000 digits there can be one partially filled.
* </ol>
*
* <p>Numbers are represented in the following form:
*
* <pre>
* n = sign × mant × (radix)<sup>exp</sup>;</p>
* </pre>
*
* where sign is ±1, mantissa represents a fractional number between zero and one. mant[0] is
* the least significant digit. exp is in the range of -32767 to 32768
*
* <p>IEEE 854-1987 Notes and differences
*
* <p>IEEE 854 requires the radix to be either 2 or 10. The radix here is 10000, so that requirement
* is not met, but it is possible that a subclassed can be made to make it behave as a radix 10
* number. It is my opinion that if it looks and behaves as a radix 10 number then it is one and
* that requirement would be met.
*
* <p>The radix of 10000 was chosen because it should be faster to operate on 4 decimal digits at
* once instead of one at a time. Radix 10 behavior can be realized by add an additional rounding
* step to ensure that the number of decimal digits represented is constant.
*
* <p>The IEEE standard specifically leaves out internal data encoding, so it is reasonable to
* conclude that such a subclass of this radix 10000 system is merely an encoding of a radix 10
* system.
*
* <p>IEEE 854 also specifies the existence of "sub-normal" numbers. This class does not contain any
* such entities. The most significant radix 10000 digit is always non-zero. Instead, we support
* "gradual underflow" by raising the underflow flag for numbers less with exponent less than
* expMin, but don't flush to zero until the exponent reaches MIN_EXP-digits. Thus the smallest
* number we can represent would be: 1E(-(MIN_EXP-digits-1)∗4), eg, for digits=5,
* MIN_EXP=-32767, that would be 1e-131092.
*
* <p>IEEE 854 defines that the implied radix point lies just to the right of the most significant
* digit and to the left of the remaining digits. This implementation puts the implied radix point
* to the left of all digits including the most significant one. The most significant digit here is
* the one just to the right of the radix point. This is a fine detail and is really only a matter
* of definition. Any side effects of this can be rendered invisible by a subclass.
*/
package org.apache.commons.math3.dfp;
|