/* Generated from 'BigDecimal.nrx' 8 Sep 2000 11:10:50 [v2.00] */ /* Options: Binary Comments Crossref Format Java Logo Strictargs Strictcase Trace2 Verbose3 */ package com.ibm.icu.math; import java.math.BigInteger; import com.ibm.icu.lang.UCharacter; /* ------------------------------------------------------------------ */ /* BigDecimal -- Decimal arithmetic for Java */ /* ------------------------------------------------------------------ */ /* Copyright IBM Corporation, 1996-2010. All Rights Reserved. */ /* */ /* The BigDecimal class provides immutable arbitrary-precision */ /* floating point (including integer) decimal numbers. */ /* */ /* As the numbers are decimal, there is an exact correspondence */ /* between an instance of a BigDecimal object and its String */ /* representation; the BigDecimal class provides direct conversions */ /* to and from String and character array objects, and well as */ /* conversions to and from the Java primitive types (which may not */ /* be exact). */ /* ------------------------------------------------------------------ */ /* Notes: */ /* */ /* 1. A BigDecimal object is never changed in value once constructed; */ /* this avoids the need for locking. Note in particular that the */ /* mantissa array may be shared between many BigDecimal objects, */ /* so that once exposed it must not be altered. */ /* */ /* 2. This class looks at MathContext class fields directly (for */ /* performance). It must not and does not change them. */ /* */ /* 3. Exponent checking is delayed until finish(), as we know */ /* intermediate calculations cannot cause 31-bit overflow. */ /* [This assertion depends on MAX_DIGITS in MathContext.] */ /* */ /* 4. Comments for the public API now follow the javadoc conventions. */ /* The NetRexx -comments option is used to pass these comments */ /* through to the generated Java code (with -format, if desired). */ /* */ /* 5. System.arraycopy is faster than explicit loop as follows */ /* Mean length 4: equal */ /* Mean length 8: x2 */ /* Mean length 16: x3 */ /* Mean length 24: x4 */ /* From prior experience, we expect mean length a little below 8, */ /* but arraycopy is still the one to use, in general, until later */ /* measurements suggest otherwise. */ /* */ /* 6. 'DMSRCN' referred to below is the original (1981) IBM S/370 */ /* assembler code implementation of the algorithms below; it is */ /* now called IXXRCN and is available with the OS/390 and VM/ESA */ /* operating systems. */ /* ------------------------------------------------------------------ */ /* Change History: */ /* 1997.09.02 Initial version (derived from netrexx.lang classes) */ /* 1997.09.12 Add lostDigits checking */ /* 1997.10.06 Change mantissa to a byte array */ /* 1997.11.22 Rework power [did not prepare arguments, etc.] */ /* 1997.12.13 multiply did not prepare arguments */ /* 1997.12.14 add did not prepare and align arguments correctly */ /* 1998.05.02 0.07 packaging changes suggested by Sun and Oracle */ /* 1998.05.21 adjust remainder operator finalization */ /* 1998.06.04 rework to pass MathContext to finish() and round() */ /* 1998.06.06 change format to use round(); support rounding modes */ /* 1998.06.25 rename to BigDecimal and begin merge */ /* zero can now have trailing zeros (i.e., exp\=0) */ /* 1998.06.28 new methods: movePointXxxx, scale, toBigInteger */ /* unscaledValue, valueof */ /* 1998.07.01 improve byteaddsub to allow array reuse, etc. */ /* 1998.07.01 make null testing explicit to avoid JIT bug [Win32] */ /* 1998.07.07 scaled division [divide(BigDecimal, int, int)] */ /* 1998.07.08 setScale, faster equals */ /* 1998.07.11 allow 1E6 (no sign) ; new double/float conversion */ /* 1998.10.12 change package to com.ibm.icu.math */ /* 1998.12.14 power operator no longer rounds RHS [to match ANSI] */ /* add toBigDecimal() and BigDecimal(java.math.BigDecimal) */ /* 1998.12.29 improve byteaddsub by using table lookup */ /* 1999.02.04 lostdigits=0 behaviour rounds instead of digits+1 guard */ /* 1999.02.05 cleaner code for BigDecimal(char[]) */ /* 1999.02.06 add javadoc comments */ /* 1999.02.11 format() changed from 7 to 2 method form */ /* 1999.03.05 null pointer checking is no longer explicit */ /* 1999.03.05 simplify; changes from discussion with J. Bloch: */ /* null no longer permitted for MathContext; drop boolean, */ /* byte, char, float, short constructor, deprecate double */ /* constructor, no blanks in string constructor, add */ /* offset and length version of char[] constructor; */ /* add valueOf(double); drop booleanValue, charValue; */ /* add ...Exact versions of remaining convertors */ /* 1999.03.13 add toBigIntegerExact */ /* 1999.03.13 1.00 release to IBM Centre for Java Technology */ /* 1999.05.27 1.01 correct 0-0.2 bug under scaled arithmetic */ /* 1999.06.29 1.02 constructors should not allow exponent > 9 digits */ /* 1999.07.03 1.03 lost digits should not be checked if digits=0 */ /* 1999.07.06 lost digits Exception message changed */ /* 1999.07.10 1.04 more work on 0-0.2 (scaled arithmetic) */ /* 1999.07.17 improve messages from pow method */ /* 1999.08.08 performance tweaks */ /* 1999.08.15 fastpath in multiply */ /* 1999.11.05 1.05 fix problem in intValueExact [e.g., 5555555555] */ /* 1999.12.22 1.06 remove multiply fastpath, and improve performance */ /* 2000.01.01 copyright update [Y2K has arrived] */ /* 2000.06.18 1.08 no longer deprecate BigDecimal(double) */ /* ------------------------------------------------------------------ */ /** * The BigDecimal class implements immutable arbitrary-precision decimal numbers. The methods of the * BigDecimal class provide operations for fixed and floating point arithmetic, comparison, format * conversions, and hashing. *

* As the numbers are decimal, there is an exact correspondence between an instance of a BigDecimal object * and its String representation; the BigDecimal class provides direct conversions to and from * String and character array (char[]) objects, as well as conversions to and from the Java * primitive types (which may not be exact) and BigInteger. *

* In the descriptions of constructors and methods in this documentation, the value of a BigDecimal number * object is shown as the result of invoking the toString() method on the object. The internal * representation of a decimal number is neither defined nor exposed, and is not permitted to affect the result of any * operation. *

* The floating point arithmetic provided by this class is defined by the ANSI X3.274-1996 standard, and is also * documented at http://www2.hursley.ibm.com/decimal
* [This URL will change.] * *

Operator methods

*

* Operations on BigDecimal numbers are controlled by a {@link MathContext} object, which provides the * context (precision and other information) for the operation. Methods that can take a MathContext * parameter implement the standard arithmetic operators for BigDecimal objects and are known as * operator methods. The default settings provided by the constant {@link MathContext#DEFAULT} (digits=9, * form=SCIENTIFIC, lostDigits=false, roundingMode=ROUND_HALF_UP) perform general-purpose floating point * arithmetic to nine digits of precision. The MathContext parameter must not be null. *

* Each operator method also has a version provided which does not take a MathContext parameter. For this * version of each method, the context settings used are digits=0, * form=PLAIN, lostDigits=false, roundingMode=ROUND_HALF_UP; these settings perform fixed point arithmetic with * unlimited precision, as defined for the original BigDecimal class in Java 1.1 and Java 1.2. *

* For monadic operators, only the optional MathContext parameter is present; the operation acts upon the * current object. *

* For dyadic operators, a BigDecimal parameter is always present; it must not be null. The * operation acts with the current object being the left-hand operand and the BigDecimal parameter being * the right-hand operand. *

* For example, adding two BigDecimal objects referred to by the names award and * extra could be written as any of: *

* * award.add(extra) *
award.add(extra, MathContext.DEFAULT) *
award.add(extra, acontext) *
*

* (where acontext is a MathContext object), which would return a BigDecimal * object whose value is the result of adding award and extra under the appropriate context * settings. *

* When a BigDecimal operator method is used, a set of rules define what the result will be (and, by * implication, how the result would be represented as a character string). These rules are defined in the BigDecimal * arithmetic documentation (see the URL above), but in summary: *