0001 /*
0002 * Portions Copyright 1996-2007 Sun Microsystems, Inc. All Rights Reserved.
0003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004 *
0005 * This code is free software; you can redistribute it and/or modify it
0006 * under the terms of the GNU General Public License version 2 only, as
0007 * published by the Free Software Foundation. Sun designates this
0008 * particular file as subject to the "Classpath" exception as provided
0009 * by Sun in the LICENSE file that accompanied this code.
0010 *
0011 * This code is distributed in the hope that it will be useful, but WITHOUT
0012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014 * version 2 for more details (a copy is included in the LICENSE file that
0015 * accompanied this code).
0016 *
0017 * You should have received a copy of the GNU General Public License version
0018 * 2 along with this work; if not, write to the Free Software Foundation,
0019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020 *
0021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022 * CA 95054 USA or visit www.sun.com if you need additional information or
0023 * have any questions.
0024 */
0025
0026 /*
0027 * Portions Copyright IBM Corporation, 2001. All Rights Reserved.
0028 */
0029
0030 package java.math;
0031
0032 /**
0033 * Immutable, arbitrary-precision signed decimal numbers. A
0034 * {@code BigDecimal} consists of an arbitrary precision integer
0035 * <i>unscaled value</i> and a 32-bit integer <i>scale</i>. If zero
0036 * or positive, the scale is the number of digits to the right of the
0037 * decimal point. If negative, the unscaled value of the number is
0038 * multiplied by ten to the power of the negation of the scale. The
0039 * value of the number represented by the {@code BigDecimal} is
0040 * therefore <tt>(unscaledValue × 10<sup>-scale</sup>)</tt>.
0041 *
0042 * <p>The {@code BigDecimal} class provides operations for
0043 * arithmetic, scale manipulation, rounding, comparison, hashing, and
0044 * format conversion. The {@link #toString} method provides a
0045 * canonical representation of a {@code BigDecimal}.
0046 *
0047 * <p>The {@code BigDecimal} class gives its user complete control
0048 * over rounding behavior. If no rounding mode is specified and the
0049 * exact result cannot be represented, an exception is thrown;
0050 * otherwise, calculations can be carried out to a chosen precision
0051 * and rounding mode by supplying an appropriate {@link MathContext}
0052 * object to the operation. In either case, eight <em>rounding
0053 * modes</em> are provided for the control of rounding. Using the
0054 * integer fields in this class (such as {@link #ROUND_HALF_UP}) to
0055 * represent rounding mode is largely obsolete; the enumeration values
0056 * of the {@code RoundingMode} {@code enum}, (such as {@link
0057 * RoundingMode#HALF_UP}) should be used instead.
0058 *
0059 * <p>When a {@code MathContext} object is supplied with a precision
0060 * setting of 0 (for example, {@link MathContext#UNLIMITED}),
0061 * arithmetic operations are exact, as are the arithmetic methods
0062 * which take no {@code MathContext} object. (This is the only
0063 * behavior that was supported in releases prior to 5.) As a
0064 * corollary of computing the exact result, the rounding mode setting
0065 * of a {@code MathContext} object with a precision setting of 0 is
0066 * not used and thus irrelevant. In the case of divide, the exact
0067 * quotient could have an infinitely long decimal expansion; for
0068 * example, 1 divided by 3. If the quotient has a nonterminating
0069 * decimal expansion and the operation is specified to return an exact
0070 * result, an {@code ArithmeticException} is thrown. Otherwise, the
0071 * exact result of the division is returned, as done for other
0072 * operations.
0073 *
0074 * <p>When the precision setting is not 0, the rules of
0075 * {@code BigDecimal} arithmetic are broadly compatible with selected
0076 * modes of operation of the arithmetic defined in ANSI X3.274-1996
0077 * and ANSI X3.274-1996/AM 1-2000 (section 7.4). Unlike those
0078 * standards, {@code BigDecimal} includes many rounding modes, which
0079 * were mandatory for division in {@code BigDecimal} releases prior
0080 * to 5. Any conflicts between these ANSI standards and the
0081 * {@code BigDecimal} specification are resolved in favor of
0082 * {@code BigDecimal}.
0083 *
0084 * <p>Since the same numerical value can have different
0085 * representations (with different scales), the rules of arithmetic
0086 * and rounding must specify both the numerical result and the scale
0087 * used in the result's representation.
0088 *
0089 *
0090 * <p>In general the rounding modes and precision setting determine
0091 * how operations return results with a limited number of digits when
0092 * the exact result has more digits (perhaps infinitely many in the
0093 * case of division) than the number of digits returned.
0094 *
0095 * First, the
0096 * total number of digits to return is specified by the
0097 * {@code MathContext}'s {@code precision} setting; this determines
0098 * the result's <i>precision</i>. The digit count starts from the
0099 * leftmost nonzero digit of the exact result. The rounding mode
0100 * determines how any discarded trailing digits affect the returned
0101 * result.
0102 *
0103 * <p>For all arithmetic operators , the operation is carried out as
0104 * though an exact intermediate result were first calculated and then
0105 * rounded to the number of digits specified by the precision setting
0106 * (if necessary), using the selected rounding mode. If the exact
0107 * result is not returned, some digit positions of the exact result
0108 * are discarded. When rounding increases the magnitude of the
0109 * returned result, it is possible for a new digit position to be
0110 * created by a carry propagating to a leading {@literal "9"} digit.
0111 * For example, rounding the value 999.9 to three digits rounding up
0112 * would be numerically equal to one thousand, represented as
0113 * 100×10<sup>1</sup>. In such cases, the new {@literal "1"} is
0114 * the leading digit position of the returned result.
0115 *
0116 * <p>Besides a logical exact result, each arithmetic operation has a
0117 * preferred scale for representing a result. The preferred
0118 * scale for each operation is listed in the table below.
0119 *
0120 * <table border>
0121 * <caption top><h3>Preferred Scales for Results of Arithmetic Operations
0122 * </h3></caption>
0123 * <tr><th>Operation</th><th>Preferred Scale of Result</th></tr>
0124 * <tr><td>Add</td><td>max(addend.scale(), augend.scale())</td>
0125 * <tr><td>Subtract</td><td>max(minuend.scale(), subtrahend.scale())</td>
0126 * <tr><td>Multiply</td><td>multiplier.scale() + multiplicand.scale()</td>
0127 * <tr><td>Divide</td><td>dividend.scale() - divisor.scale()</td>
0128 * </table>
0129 *
0130 * These scales are the ones used by the methods which return exact
0131 * arithmetic results; except that an exact divide may have to use a
0132 * larger scale since the exact result may have more digits. For
0133 * example, {@code 1/32} is {@code 0.03125}.
0134 *
0135 * <p>Before rounding, the scale of the logical exact intermediate
0136 * result is the preferred scale for that operation. If the exact
0137 * numerical result cannot be represented in {@code precision}
0138 * digits, rounding selects the set of digits to return and the scale
0139 * of the result is reduced from the scale of the intermediate result
0140 * to the least scale which can represent the {@code precision}
0141 * digits actually returned. If the exact result can be represented
0142 * with at most {@code precision} digits, the representation
0143 * of the result with the scale closest to the preferred scale is
0144 * returned. In particular, an exactly representable quotient may be
0145 * represented in fewer than {@code precision} digits by removing
0146 * trailing zeros and decreasing the scale. For example, rounding to
0147 * three digits using the {@linkplain RoundingMode#FLOOR floor}
0148 * rounding mode, <br>
0149 *
0150 * {@code 19/100 = 0.19 // integer=19, scale=2} <br>
0151 *
0152 * but<br>
0153 *
0154 * {@code 21/110 = 0.190 // integer=190, scale=3} <br>
0155 *
0156 * <p>Note that for add, subtract, and multiply, the reduction in
0157 * scale will equal the number of digit positions of the exact result
0158 * which are discarded. If the rounding causes a carry propagation to
0159 * create a new high-order digit position, an additional digit of the
0160 * result is discarded than when no new digit position is created.
0161 *
0162 * <p>Other methods may have slightly different rounding semantics.
0163 * For example, the result of the {@code pow} method using the
0164 * {@linkplain #pow(int, MathContext) specified algorithm} can
0165 * occasionally differ from the rounded mathematical result by more
0166 * than one unit in the last place, one <i>{@linkplain #ulp() ulp}</i>.
0167 *
0168 * <p>Two types of operations are provided for manipulating the scale
0169 * of a {@code BigDecimal}: scaling/rounding operations and decimal
0170 * point motion operations. Scaling/rounding operations ({@link
0171 * #setScale setScale} and {@link #round round}) return a
0172 * {@code BigDecimal} whose value is approximately (or exactly) equal
0173 * to that of the operand, but whose scale or precision is the
0174 * specified value; that is, they increase or decrease the precision
0175 * of the stored number with minimal effect on its value. Decimal
0176 * point motion operations ({@link #movePointLeft movePointLeft} and
0177 * {@link #movePointRight movePointRight}) return a
0178 * {@code BigDecimal} created from the operand by moving the decimal
0179 * point a specified distance in the specified direction.
0180 *
0181 * <p>For the sake of brevity and clarity, pseudo-code is used
0182 * throughout the descriptions of {@code BigDecimal} methods. The
0183 * pseudo-code expression {@code (i + j)} is shorthand for "a
0184 * {@code BigDecimal} whose value is that of the {@code BigDecimal}
0185 * {@code i} added to that of the {@code BigDecimal}
0186 * {@code j}." The pseudo-code expression {@code (i == j)} is
0187 * shorthand for "{@code true} if and only if the
0188 * {@code BigDecimal} {@code i} represents the same value as the
0189 * {@code BigDecimal} {@code j}." Other pseudo-code expressions
0190 * are interpreted similarly. Square brackets are used to represent
0191 * the particular {@code BigInteger} and scale pair defining a
0192 * {@code BigDecimal} value; for example [19, 2] is the
0193 * {@code BigDecimal} numerically equal to 0.19 having a scale of 2.
0194 *
0195 * <p>Note: care should be exercised if {@code BigDecimal} objects
0196 * are used as keys in a {@link java.util.SortedMap SortedMap} or
0197 * elements in a {@link java.util.SortedSet SortedSet} since
0198 * {@code BigDecimal}'s <i>natural ordering</i> is <i>inconsistent
0199 * with equals</i>. See {@link Comparable}, {@link
0200 * java.util.SortedMap} or {@link java.util.SortedSet} for more
0201 * information.
0202 *
0203 * <p>All methods and constructors for this class throw
0204 * {@code NullPointerException} when passed a {@code null} object
0205 * reference for any input parameter.
0206 *
0207 * @see BigInteger
0208 * @see MathContext
0209 * @see RoundingMode
0210 * @see java.util.SortedMap
0211 * @see java.util.SortedSet
0212 * @author Josh Bloch
0213 * @author Mike Cowlishaw
0214 * @author Joseph D. Darcy
0215 */
0216 public class BigDecimal extends Number implements
0217 Comparable<BigDecimal> {
0218 /**
0219 * The unscaled value of this BigDecimal, as returned by {@link
0220 * #unscaledValue}.
0221 *
0222 * @serial
0223 * @see #unscaledValue
0224 */
0225 private volatile BigInteger intVal;
0226
0227 /**
0228 * The scale of this BigDecimal, as returned by {@link #scale}.
0229 *
0230 * @serial
0231 * @see #scale
0232 */
0233 private int scale = 0; // Note: this may have any value, so
0234 // calculations must be done in longs
0235 /**
0236 * The number of decimal digits in this BigDecimal, or 0 if the
0237 * number of digits are not known (lookaside information). If
0238 * nonzero, the value is guaranteed correct. Use the precision()
0239 * method to obtain and set the value if it might be 0. This
0240 * field is mutable until set nonzero.
0241 *
0242 * @since 1.5
0243 */
0244 private volatile transient int precision = 0;
0245
0246 /**
0247 * Used to store the canonical string representation, if computed.
0248 */
0249 private volatile transient String stringCache = null;
0250
0251 /**
0252 * Sentinel value for {@link #intCompact} indicating the
0253 * significand information is only available from {@code intVal}.
0254 */
0255 private static final long INFLATED = Long.MIN_VALUE;
0256
0257 /**
0258 * If the absolute value of the significand of this BigDecimal is
0259 * less than or equal to {@code Long.MAX_VALUE}, the value can be
0260 * compactly stored in this field and used in computations.
0261 */
0262 private transient long intCompact = INFLATED;
0263
0264 // All 18-digit base ten strings fit into a long; not all 19-digit
0265 // strings will
0266 private static final int MAX_COMPACT_DIGITS = 18;
0267
0268 private static final int MAX_BIGINT_BITS = 62;
0269
0270 /* Appease the serialization gods */
0271 private static final long serialVersionUID = 6108874887143696463L;
0272
0273 // Cache of common small BigDecimal values.
0274 private static final BigDecimal zeroThroughTen[] = {
0275 new BigDecimal(BigInteger.ZERO, 0, 0),
0276 new BigDecimal(BigInteger.ONE, 1, 0),
0277 new BigDecimal(BigInteger.valueOf(2), 2, 0),
0278 new BigDecimal(BigInteger.valueOf(3), 3, 0),
0279 new BigDecimal(BigInteger.valueOf(4), 4, 0),
0280 new BigDecimal(BigInteger.valueOf(5), 5, 0),
0281 new BigDecimal(BigInteger.valueOf(6), 6, 0),
0282 new BigDecimal(BigInteger.valueOf(7), 7, 0),
0283 new BigDecimal(BigInteger.valueOf(8), 8, 0),
0284 new BigDecimal(BigInteger.valueOf(9), 9, 0),
0285 new BigDecimal(BigInteger.TEN, 10, 0), };
0286
0287 // Constants
0288 /**
0289 * The value 0, with a scale of 0.
0290 *
0291 * @since 1.5
0292 */
0293 public static final BigDecimal ZERO = zeroThroughTen[0];
0294
0295 /**
0296 * The value 1, with a scale of 0.
0297 *
0298 * @since 1.5
0299 */
0300 public static final BigDecimal ONE = zeroThroughTen[1];
0301
0302 /**
0303 * The value 10, with a scale of 0.
0304 *
0305 * @since 1.5
0306 */
0307 public static final BigDecimal TEN = zeroThroughTen[10];
0308
0309 // Constructors
0310
0311 /**
0312 * Translates a character array representation of a
0313 * {@code BigDecimal} into a {@code BigDecimal}, accepting the
0314 * same sequence of characters as the {@link #BigDecimal(String)}
0315 * constructor, while allowing a sub-array to be specified.
0316 *
0317 * <p>Note that if the sequence of characters is already available
0318 * within a character array, using this constructor is faster than
0319 * converting the {@code char} array to string and using the
0320 * {@code BigDecimal(String)} constructor .
0321 *
0322 * @param in {@code char} array that is the source of characters.
0323 * @param offset first character in the array to inspect.
0324 * @param len number of characters to consider.
0325 * @throws NumberFormatException if {@code in} is not a valid
0326 * representation of a {@code BigDecimal} or the defined subarray
0327 * is not wholly within {@code in}.
0328 * @since 1.5
0329 */
0330 public BigDecimal(char[] in, int offset, int len) {
0331 // This is the primary string to BigDecimal constructor; all
0332 // incoming strings end up here; it uses explicit (inline)
0333 // parsing for speed and generates at most one intermediate
0334 // (temporary) object (a char[] array).
0335
0336 // use array bounds checking to handle too-long, len == 0,
0337 // bad offset, etc.
0338 try {
0339 // handle the sign
0340 boolean isneg = false; // assume positive
0341 if (in[offset] == '-') {
0342 isneg = true; // leading minus means negative
0343 offset++;
0344 len--;
0345 } else if (in[offset] == '+') { // leading + allowed
0346 offset++;
0347 len--;
0348 }
0349
0350 // should now be at numeric part of the significand
0351 int dotoff = -1; // '.' offset, -1 if none
0352 int cfirst = offset; // record start of integer
0353 long exp = 0; // exponent
0354 if (len > in.length) // protect against huge length
0355 throw new NumberFormatException();
0356 char coeff[] = new char[len]; // integer significand array
0357 char c; // work
0358
0359 for (; len > 0; offset++, len--) {
0360 c = in[offset];
0361 if ((c >= '0' && c <= '9') || Character.isDigit(c)) {
0362 // have digit
0363 coeff[precision] = c;
0364 precision++; // count of digits
0365 continue;
0366 }
0367 if (c == '.') {
0368 // have dot
0369 if (dotoff >= 0) // two dots
0370 throw new NumberFormatException();
0371 dotoff = offset;
0372 continue;
0373 }
0374 // exponent expected
0375 if ((c != 'e') && (c != 'E'))
0376 throw new NumberFormatException();
0377 offset++;
0378 c = in[offset];
0379 len--;
0380 boolean negexp = false;
0381 // optional sign
0382 if (c == '-' || c == '+') {
0383 negexp = (c == '-');
0384 offset++;
0385 c = in[offset];
0386 len--;
0387 }
0388 if (len <= 0) // no exponent digits
0389 throw new NumberFormatException();
0390 // skip leading zeros in the exponent
0391 while (len > 10 && Character.digit(c, 10) == 0) {
0392 offset++;
0393 c = in[offset];
0394 len--;
0395 }
0396 if (len > 10) // too many nonzero exponent digits
0397 throw new NumberFormatException();
0398 // c now holds first digit of exponent
0399 for (;; len--) {
0400 int v;
0401 if (c >= '0' && c <= '9') {
0402 v = c - '0';
0403 } else {
0404 v = Character.digit(c, 10);
0405 if (v < 0) // not a digit
0406 throw new NumberFormatException();
0407 }
0408 exp = exp * 10 + v;
0409 if (len == 1)
0410 break; // that was final character
0411 offset++;
0412 c = in[offset];
0413 }
0414 if (negexp) // apply sign
0415 exp = -exp;
0416 // Next test is required for backwards compatibility
0417 if ((int) exp != exp) // overflow
0418 throw new NumberFormatException();
0419 break; // [saves a test]
0420 }
0421 // here when no characters left
0422 if (precision == 0) // no digits found
0423 throw new NumberFormatException();
0424
0425 if (dotoff >= 0) { // had dot; set scale
0426 scale = precision - (dotoff - cfirst);
0427 // [cannot overflow]
0428 }
0429 if (exp != 0) { // had significant exponent
0430 try {
0431 scale = checkScale(-exp + scale); // adjust
0432 } catch (ArithmeticException e) {
0433 throw new NumberFormatException(
0434 "Scale out of range.");
0435 }
0436 }
0437
0438 // Remove leading zeros from precision (digits count)
0439 int first = 0;
0440 for (; (coeff[first] == '0' || Character.digit(
0441 coeff[first], 10) == 0)
0442 && precision > 1; first++)
0443 precision--;
0444
0445 // Set the significand ..
0446 // Copy significand to exact-sized array, with sign if
0447 // negative
0448 // Later use: BigInteger(coeff, first, precision) for
0449 // both cases, by allowing an extra char at the front of
0450 // coeff.
0451 char quick[];
0452 if (!isneg) {
0453 quick = new char[precision];
0454 System.arraycopy(coeff, first, quick, 0, precision);
0455 } else {
0456 quick = new char[precision + 1];
0457 quick[0] = '-';
0458 System.arraycopy(coeff, first, quick, 1, precision);
0459 }
0460 if (precision <= MAX_COMPACT_DIGITS)
0461 intCompact = Long.parseLong(new String(quick));
0462 else
0463 intVal = new BigInteger(quick);
0464 // System.out.println(" new: " +intVal+" ["+scale+"] "+precision);
0465 } catch (ArrayIndexOutOfBoundsException e) {
0466 throw new NumberFormatException();
0467 } catch (NegativeArraySizeException e) {
0468 throw new NumberFormatException();
0469 }
0470 }
0471
0472 /**
0473 * Translates a character array representation of a
0474 * {@code BigDecimal} into a {@code BigDecimal}, accepting the
0475 * same sequence of characters as the {@link #BigDecimal(String)}
0476 * constructor, while allowing a sub-array to be specified and
0477 * with rounding according to the context settings.
0478 *
0479 * <p>Note that if the sequence of characters is already available
0480 * within a character array, using this constructor is faster than
0481 * converting the {@code char} array to string and using the
0482 * {@code BigDecimal(String)} constructor .
0483 *
0484 * @param in {@code char} array that is the source of characters.
0485 * @param offset first character in the array to inspect.
0486 * @param len number of characters to consider..
0487 * @param mc the context to use.
0488 * @throws ArithmeticException if the result is inexact but the
0489 * rounding mode is {@code UNNECESSARY}.
0490 * @throws NumberFormatException if {@code in} is not a valid
0491 * representation of a {@code BigDecimal} or the defined subarray
0492 * is not wholly within {@code in}.
0493 * @since 1.5
0494 */
0495 public BigDecimal(char[] in, int offset, int len, MathContext mc) {
0496 this (in, offset, len);
0497 if (mc.precision > 0)
0498 roundThis(mc);
0499 }
0500
0501 /**
0502 * Translates a character array representation of a
0503 * {@code BigDecimal} into a {@code BigDecimal}, accepting the
0504 * same sequence of characters as the {@link #BigDecimal(String)}
0505 * constructor.
0506 *
0507 * <p>Note that if the sequence of characters is already available
0508 * as a character array, using this constructor is faster than
0509 * converting the {@code char} array to string and using the
0510 * {@code BigDecimal(String)} constructor .
0511 *
0512 * @param in {@code char} array that is the source of characters.
0513 * @throws NumberFormatException if {@code in} is not a valid
0514 * representation of a {@code BigDecimal}.
0515 * @since 1.5
0516 */
0517 public BigDecimal(char[] in) {
0518 this (in, 0, in.length);
0519 }
0520
0521 /**
0522 * Translates a character array representation of a
0523 * {@code BigDecimal} into a {@code BigDecimal}, accepting the
0524 * same sequence of characters as the {@link #BigDecimal(String)}
0525 * constructor and with rounding according to the context
0526 * settings.
0527 *
0528 * <p>Note that if the sequence of characters is already available
0529 * as a character array, using this constructor is faster than
0530 * converting the {@code char} array to string and using the
0531 * {@code BigDecimal(String)} constructor .
0532 *
0533 * @param in {@code char} array that is the source of characters.
0534 * @param mc the context to use.
0535 * @throws ArithmeticException if the result is inexact but the
0536 * rounding mode is {@code UNNECESSARY}.
0537 * @throws NumberFormatException if {@code in} is not a valid
0538 * representation of a {@code BigDecimal}.
0539 * @since 1.5
0540 */
0541 public BigDecimal(char[] in, MathContext mc) {
0542 this (in, 0, in.length, mc);
0543 }
0544
0545 /**
0546 * Translates the string representation of a {@code BigDecimal}
0547 * into a {@code BigDecimal}. The string representation consists
0548 * of an optional sign, {@code '+'} (<tt> '\u002B'</tt>) or
0549 * {@code '-'} (<tt>'\u002D'</tt>), followed by a sequence of
0550 * zero or more decimal digits ("the integer"), optionally
0551 * followed by a fraction, optionally followed by an exponent.
0552 *
0553 * <p>The fraction consists of a decimal point followed by zero
0554 * or more decimal digits. The string must contain at least one
0555 * digit in either the integer or the fraction. The number formed
0556 * by the sign, the integer and the fraction is referred to as the
0557 * <i>significand</i>.
0558 *
0559 * <p>The exponent consists of the character {@code 'e'}
0560 * (<tt>'\u0065'</tt>) or {@code 'E'} (<tt>'\u0045'</tt>)
0561 * followed by one or more decimal digits. The value of the
0562 * exponent must lie between -{@link Integer#MAX_VALUE} ({@link
0563 * Integer#MIN_VALUE}+1) and {@link Integer#MAX_VALUE}, inclusive.
0564 *
0565 * <p>More formally, the strings this constructor accepts are
0566 * described by the following grammar:
0567 * <blockquote>
0568 * <dl>
0569 * <dt><i>BigDecimalString:</i>
0570 * <dd><i>Sign<sub>opt</sub> Significand Exponent<sub>opt</sub></i>
0571 * <p>
0572 * <dt><i>Sign:</i>
0573 * <dd>{@code +}
0574 * <dd>{@code -}
0575 * <p>
0576 * <dt><i>Significand:</i>
0577 * <dd><i>IntegerPart</i> {@code .} <i>FractionPart<sub>opt</sub></i>
0578 * <dd>{@code .} <i>FractionPart</i>
0579 * <dd><i>IntegerPart</i>
0580 * <p>
0581 * <dt><i>IntegerPart:
0582 * <dd>Digits</i>
0583 * <p>
0584 * <dt><i>FractionPart:
0585 * <dd>Digits</i>
0586 * <p>
0587 * <dt><i>Exponent:
0588 * <dd>ExponentIndicator SignedInteger</i>
0589 * <p>
0590 * <dt><i>ExponentIndicator:</i>
0591 * <dd>{@code e}
0592 * <dd>{@code E}
0593 * <p>
0594 * <dt><i>SignedInteger:
0595 * <dd>Sign<sub>opt</sub> Digits</i>
0596 * <p>
0597 * <dt><i>Digits:
0598 * <dd>Digit
0599 * <dd>Digits Digit</i>
0600 * <p>
0601 * <dt><i>Digit:</i>
0602 * <dd>any character for which {@link Character#isDigit}
0603 * returns {@code true}, including 0, 1, 2 ...
0604 * </dl>
0605 * </blockquote>
0606 *
0607 * <p>The scale of the returned {@code BigDecimal} will be the
0608 * number of digits in the fraction, or zero if the string
0609 * contains no decimal point, subject to adjustment for any
0610 * exponent; if the string contains an exponent, the exponent is
0611 * subtracted from the scale. The value of the resulting scale
0612 * must lie between {@code Integer.MIN_VALUE} and
0613 * {@code Integer.MAX_VALUE}, inclusive.
0614 *
0615 * <p>The character-to-digit mapping is provided by {@link
0616 * java.lang.Character#digit} set to convert to radix 10. The
0617 * String may not contain any extraneous characters (whitespace,
0618 * for example).
0619 *
0620 * <p><b>Examples:</b><br>
0621 * The value of the returned {@code BigDecimal} is equal to
0622 * <i>significand</i> × 10<sup> <i>exponent</i></sup>.
0623 * For each string on the left, the resulting representation
0624 * [{@code BigInteger}, {@code scale}] is shown on the right.
0625 * <pre>
0626 * "0" [0,0]
0627 * "0.00" [0,2]
0628 * "123" [123,0]
0629 * "-123" [-123,0]
0630 * "1.23E3" [123,-1]
0631 * "1.23E+3" [123,-1]
0632 * "12.3E+7" [123,-6]
0633 * "12.0" [120,1]
0634 * "12.3" [123,1]
0635 * "0.00123" [123,5]
0636 * "-1.23E-12" [-123,14]
0637 * "1234.5E-4" [12345,5]
0638 * "0E+7" [0,-7]
0639 * "-0" [0,0]
0640 * </pre>
0641 *
0642 * <p>Note: For values other than {@code float} and
0643 * {@code double} NaN and ±Infinity, this constructor is
0644 * compatible with the values returned by {@link Float#toString}
0645 * and {@link Double#toString}. This is generally the preferred
0646 * way to convert a {@code float} or {@code double} into a
0647 * BigDecimal, as it doesn't suffer from the unpredictability of
0648 * the {@link #BigDecimal(double)} constructor.
0649 *
0650 * @param val String representation of {@code BigDecimal}.
0651 *
0652 * @throws NumberFormatException if {@code val} is not a valid
0653 * representation of a {@code BigDecimal}.
0654 */
0655 public BigDecimal(String val) {
0656 this (val.toCharArray(), 0, val.length());
0657 }
0658
0659 /**
0660 * Translates the string representation of a {@code BigDecimal}
0661 * into a {@code BigDecimal}, accepting the same strings as the
0662 * {@link #BigDecimal(String)} constructor, with rounding
0663 * according to the context settings.
0664 *
0665 * @param val string representation of a {@code BigDecimal}.
0666 * @param mc the context to use.
0667 * @throws ArithmeticException if the result is inexact but the
0668 * rounding mode is {@code UNNECESSARY}.
0669 * @throws NumberFormatException if {@code val} is not a valid
0670 * representation of a BigDecimal.
0671 * @since 1.5
0672 */
0673 public BigDecimal(String val, MathContext mc) {
0674 this (val.toCharArray(), 0, val.length());
0675 if (mc.precision > 0)
0676 roundThis(mc);
0677 }
0678
0679 /**
0680 * Translates a {@code double} into a {@code BigDecimal} which
0681 * is the exact decimal representation of the {@code double}'s
0682 * binary floating-point value. The scale of the returned
0683 * {@code BigDecimal} is the smallest value such that
0684 * <tt>(10<sup>scale</sup> × val)</tt> is an integer.
0685 * <p>
0686 * <b>Notes:</b>
0687 * <ol>
0688 * <li>
0689 * The results of this constructor can be somewhat unpredictable.
0690 * One might assume that writing {@code new BigDecimal(0.1)} in
0691 * Java creates a {@code BigDecimal} which is exactly equal to
0692 * 0.1 (an unscaled value of 1, with a scale of 1), but it is
0693 * actually equal to
0694 * 0.1000000000000000055511151231257827021181583404541015625.
0695 * This is because 0.1 cannot be represented exactly as a
0696 * {@code double} (or, for that matter, as a binary fraction of
0697 * any finite length). Thus, the value that is being passed
0698 * <i>in</i> to the constructor is not exactly equal to 0.1,
0699 * appearances notwithstanding.
0700 *
0701 * <li>
0702 * The {@code String} constructor, on the other hand, is
0703 * perfectly predictable: writing {@code new BigDecimal("0.1")}
0704 * creates a {@code BigDecimal} which is <i>exactly</i> equal to
0705 * 0.1, as one would expect. Therefore, it is generally
0706 * recommended that the {@linkplain #BigDecimal(String)
0707 * <tt>String</tt> constructor} be used in preference to this one.
0708 *
0709 * <li>
0710 * When a {@code double} must be used as a source for a
0711 * {@code BigDecimal}, note that this constructor provides an
0712 * exact conversion; it does not give the same result as
0713 * converting the {@code double} to a {@code String} using the
0714 * {@link Double#toString(double)} method and then using the
0715 * {@link #BigDecimal(String)} constructor. To get that result,
0716 * use the {@code static} {@link #valueOf(double)} method.
0717 * </ol>
0718 *
0719 * @param val {@code double} value to be converted to
0720 * {@code BigDecimal}.
0721 * @throws NumberFormatException if {@code val} is infinite or NaN.
0722 */
0723 public BigDecimal(double val) {
0724 if (Double.isInfinite(val) || Double.isNaN(val))
0725 throw new NumberFormatException("Infinite or NaN");
0726
0727 // Translate the double into sign, exponent and significand, according
0728 // to the formulae in JLS, Section 20.10.22.
0729 long valBits = Double.doubleToLongBits(val);
0730 int sign = ((valBits >> 63) == 0 ? 1 : -1);
0731 int exponent = (int) ((valBits >> 52) & 0x7ffL);
0732 long significand = (exponent == 0 ? (valBits & ((1L << 52) - 1)) << 1
0733 : (valBits & ((1L << 52) - 1)) | (1L << 52));
0734 exponent -= 1075;
0735 // At this point, val == sign * significand * 2**exponent.
0736
0737 /*
0738 * Special case zero to supress nonterminating normalization
0739 * and bogus scale calculation.
0740 */
0741 if (significand == 0) {
0742 intVal = BigInteger.ZERO;
0743 intCompact = 0;
0744 precision = 1;
0745 return;
0746 }
0747
0748 // Normalize
0749 while ((significand & 1) == 0) { // i.e., significand is even
0750 significand >>= 1;
0751 exponent++;
0752 }
0753
0754 // Calculate intVal and scale
0755 intVal = BigInteger.valueOf(sign * significand);
0756 if (exponent < 0) {
0757 intVal = intVal.multiply(BigInteger.valueOf(5).pow(
0758 -exponent));
0759 scale = -exponent;
0760 } else if (exponent > 0) {
0761 intVal = intVal.multiply(BigInteger.valueOf(2)
0762 .pow(exponent));
0763 }
0764 if (intVal.bitLength() <= MAX_BIGINT_BITS) {
0765 intCompact = intVal.longValue();
0766 }
0767 }
0768
0769 /**
0770 * Translates a {@code double} into a {@code BigDecimal}, with
0771 * rounding according to the context settings. The scale of the
0772 * {@code BigDecimal} is the smallest value such that
0773 * <tt>(10<sup>scale</sup> × val)</tt> is an integer.
0774 *
0775 * <p>The results of this constructor can be somewhat unpredictable
0776 * and its use is generally not recommended; see the notes under
0777 * the {@link #BigDecimal(double)} constructor.
0778 *
0779 * @param val {@code double} value to be converted to
0780 * {@code BigDecimal}.
0781 * @param mc the context to use.
0782 * @throws ArithmeticException if the result is inexact but the
0783 * RoundingMode is UNNECESSARY.
0784 * @throws NumberFormatException if {@code val} is infinite or NaN.
0785 * @since 1.5
0786 */
0787 public BigDecimal(double val, MathContext mc) {
0788 this (val);
0789 if (mc.precision > 0)
0790 roundThis(mc);
0791 }
0792
0793 /**
0794 * Translates a {@code BigInteger} into a {@code BigDecimal}.
0795 * The scale of the {@code BigDecimal} is zero.
0796 *
0797 * @param val {@code BigInteger} value to be converted to
0798 * {@code BigDecimal}.
0799 */
0800 public BigDecimal(BigInteger val) {
0801 intVal = val;
0802 if (val.bitLength() <= MAX_BIGINT_BITS) {
0803 intCompact = val.longValue();
0804 }
0805 }
0806
0807 /**
0808 * Translates a {@code BigInteger} into a {@code BigDecimal}
0809 * rounding according to the context settings. The scale of the
0810 * {@code BigDecimal} is zero.
0811 *
0812 * @param val {@code BigInteger} value to be converted to
0813 * {@code BigDecimal}.
0814 * @param mc the context to use.
0815 * @throws ArithmeticException if the result is inexact but the
0816 * rounding mode is {@code UNNECESSARY}.
0817 * @since 1.5
0818 */
0819 public BigDecimal(BigInteger val, MathContext mc) {
0820 intVal = val;
0821 if (mc.precision > 0)
0822 roundThis(mc);
0823 }
0824
0825 /**
0826 * Translates a {@code BigInteger} unscaled value and an
0827 * {@code int} scale into a {@code BigDecimal}. The value of
0828 * the {@code BigDecimal} is
0829 * <tt>(unscaledVal × 10<sup>-scale</sup>)</tt>.
0830 *
0831 * @param unscaledVal unscaled value of the {@code BigDecimal}.
0832 * @param scale scale of the {@code BigDecimal}.
0833 */
0834 public BigDecimal(BigInteger unscaledVal, int scale) {
0835 // Negative scales are now allowed
0836 intVal = unscaledVal;
0837 this .scale = scale;
0838 if (unscaledVal.bitLength() <= MAX_BIGINT_BITS) {
0839 intCompact = unscaledVal.longValue();
0840 }
0841 }
0842
0843 /**
0844 * Translates a {@code BigInteger} unscaled value and an
0845 * {@code int} scale into a {@code BigDecimal}, with rounding
0846 * according to the context settings. The value of the
0847 * {@code BigDecimal} is <tt>(unscaledVal ×
0848 * 10<sup>-scale</sup>)</tt>, rounded according to the
0849 * {@code precision} and rounding mode settings.
0850 *
0851 * @param unscaledVal unscaled value of the {@code BigDecimal}.
0852 * @param scale scale of the {@code BigDecimal}.
0853 * @param mc the context to use.
0854 * @throws ArithmeticException if the result is inexact but the
0855 * rounding mode is {@code UNNECESSARY}.
0856 * @since 1.5
0857 */
0858 public BigDecimal(BigInteger unscaledVal, int scale, MathContext mc) {
0859 intVal = unscaledVal;
0860 this .scale = scale;
0861 if (mc.precision > 0)
0862 roundThis(mc);
0863 }
0864
0865 /**
0866 * Translates an {@code int} into a {@code BigDecimal}. The
0867 * scale of the {@code BigDecimal} is zero.
0868 *
0869 * @param val {@code int} value to be converted to
0870 * {@code BigDecimal}.
0871 * @since 1.5
0872 */
0873 public BigDecimal(int val) {
0874 intCompact = val;
0875 }
0876
0877 /**
0878 * Translates an {@code int} into a {@code BigDecimal}, with
0879 * rounding according to the context settings. The scale of the
0880 * {@code BigDecimal}, before any rounding, is zero.
0881 *
0882 * @param val {@code int} value to be converted to {@code BigDecimal}.
0883 * @param mc the context to use.
0884 * @throws ArithmeticException if the result is inexact but the
0885 * rounding mode is {@code UNNECESSARY}.
0886 * @since 1.5
0887 */
0888 public BigDecimal(int val, MathContext mc) {
0889 intCompact = val;
0890 if (mc.precision > 0)
0891 roundThis(mc);
0892 }
0893
0894 /**
0895 * Translates a {@code long} into a {@code BigDecimal}. The
0896 * scale of the {@code BigDecimal} is zero.
0897 *
0898 * @param val {@code long} value to be converted to {@code BigDecimal}.
0899 * @since 1.5
0900 */
0901 public BigDecimal(long val) {
0902 if (compactLong(val))
0903 intCompact = val;
0904 else
0905 intVal = BigInteger.valueOf(val);
0906 }
0907
0908 /**
0909 * Translates a {@code long} into a {@code BigDecimal}, with
0910 * rounding according to the context settings. The scale of the
0911 * {@code BigDecimal}, before any rounding, is zero.
0912 *
0913 * @param val {@code long} value to be converted to {@code BigDecimal}.
0914 * @param mc the context to use.
0915 * @throws ArithmeticException if the result is inexact but the
0916 * rounding mode is {@code UNNECESSARY}.
0917 * @since 1.5
0918 */
0919 public BigDecimal(long val, MathContext mc) {
0920 if (compactLong(val))
0921 intCompact = val;
0922 else
0923 intVal = BigInteger.valueOf(val);
0924 if (mc.precision > 0)
0925 roundThis(mc);
0926 }
0927
0928 /**
0929 * Trusted internal constructor
0930 */
0931 private BigDecimal(long val, int scale) {
0932 this .intCompact = val;
0933 this .scale = scale;
0934 }
0935
0936 /**
0937 * Trusted internal constructor
0938 */
0939 private BigDecimal(BigInteger intVal, long val, int scale) {
0940 this .intVal = intVal;
0941 this .intCompact = val;
0942 this .scale = scale;
0943 }
0944
0945 // Static Factory Methods
0946
0947 /**
0948 * Translates a {@code long} unscaled value and an
0949 * {@code int} scale into a {@code BigDecimal}. This
0950 * {@literal "static factory method"} is provided in preference to
0951 * a ({@code long}, {@code int}) constructor because it
0952 * allows for reuse of frequently used {@code BigDecimal} values..
0953 *
0954 * @param unscaledVal unscaled value of the {@code BigDecimal}.
0955 * @param scale scale of the {@code BigDecimal}.
0956 * @return a {@code BigDecimal} whose value is
0957 * <tt>(unscaledVal × 10<sup>-scale</sup>)</tt>.
0958 */
0959 public static BigDecimal valueOf(long unscaledVal, int scale) {
0960 if (scale == 0 && unscaledVal >= 0 && unscaledVal <= 10) {
0961 return zeroThroughTen[(int) unscaledVal];
0962 }
0963 if (compactLong(unscaledVal))
0964 return new BigDecimal(unscaledVal, scale);
0965 return new BigDecimal(BigInteger.valueOf(unscaledVal), scale);
0966 }
0967
0968 /**
0969 * Translates a {@code long} value into a {@code BigDecimal}
0970 * with a scale of zero. This {@literal "static factory method"}
0971 * is provided in preference to a ({@code long}) constructor
0972 * because it allows for reuse of frequently used
0973 * {@code BigDecimal} values.
0974 *
0975 * @param val value of the {@code BigDecimal}.
0976 * @return a {@code BigDecimal} whose value is {@code val}.
0977 */
0978 public static BigDecimal valueOf(long val) {
0979 return valueOf(val, 0);
0980 }
0981
0982 /**
0983 * Translates a {@code double} into a {@code BigDecimal}, using
0984 * the {@code double}'s canonical string representation provided
0985 * by the {@link Double#toString(double)} method.
0986 *
0987 * <p><b>Note:</b> This is generally the preferred way to convert
0988 * a {@code double} (or {@code float}) into a
0989 * {@code BigDecimal}, as the value returned is equal to that
0990 * resulting from constructing a {@code BigDecimal} from the
0991 * result of using {@link Double#toString(double)}.
0992 *
0993 * @param val {@code double} to convert to a {@code BigDecimal}.
0994 * @return a {@code BigDecimal} whose value is equal to or approximately
0995 * equal to the value of {@code val}.
0996 * @throws NumberFormatException if {@code val} is infinite or NaN.
0997 * @since 1.5
0998 */
0999 public static BigDecimal valueOf(double val) {
1000 // Reminder: a zero double returns '0.0', so we cannot fastpath
1001 // to use the constant ZERO. This might be important enough to
1002 // justify a factory approach, a cache, or a few private
1003 // constants, later.
1004 return new BigDecimal(Double.toString(val));
1005 }
1006
1007 // Arithmetic Operations
1008 /**
1009 * Returns a {@code BigDecimal} whose value is {@code (this +
1010 * augend)}, and whose scale is {@code max(this.scale(),
1011 * augend.scale())}.
1012 *
1013 * @param augend value to be added to this {@code BigDecimal}.
1014 * @return {@code this + augend}
1015 */
1016 public BigDecimal add(BigDecimal augend) {
1017 BigDecimal arg[] = { this , augend };
1018 matchScale(arg);
1019
1020 long x = arg[0].intCompact;
1021 long y = arg[1].intCompact;
1022
1023 // Might be able to do a more clever check incorporating the
1024 // inflated check into the overflow computation.
1025 if (x != INFLATED && y != INFLATED) {
1026 long sum = x + y;
1027 /*
1028 * If the sum is not an overflowed value, continue to use
1029 * the compact representation. if either of x or y is
1030 * INFLATED, the sum should also be regarded as an
1031 * overflow. See "Hacker's Delight" section 2-12 for
1032 * explanation of the overflow test.
1033 */
1034 if ((((sum ^ x) & (sum ^ y)) >> 63) == 0L) // not overflowed
1035 return BigDecimal.valueOf(sum, arg[0].scale);
1036 }
1037 return new BigDecimal(arg[0].inflate().intVal.add(arg[1]
1038 .inflate().intVal), arg[0].scale);
1039 }
1040
1041 /**
1042 * Returns a {@code BigDecimal} whose value is {@code (this + augend)},
1043 * with rounding according to the context settings.
1044 *
1045 * If either number is zero and the precision setting is nonzero then
1046 * the other number, rounded if necessary, is used as the result.
1047 *
1048 * @param augend value to be added to this {@code BigDecimal}.
1049 * @param mc the context to use.
1050 * @return {@code this + augend}, rounded as necessary.
1051 * @throws ArithmeticException if the result is inexact but the
1052 * rounding mode is {@code UNNECESSARY}.
1053 * @since 1.5
1054 */
1055 public BigDecimal add(BigDecimal augend, MathContext mc) {
1056 if (mc.precision == 0)
1057 return add(augend);
1058 BigDecimal lhs = this ;
1059
1060 // Could optimize if values are compact
1061 this .inflate();
1062 augend.inflate();
1063
1064 // If either number is zero then the other number, rounded and
1065 // scaled if necessary, is used as the result.
1066 {
1067 boolean lhsIsZero = lhs.signum() == 0;
1068 boolean augendIsZero = augend.signum() == 0;
1069
1070 if (lhsIsZero || augendIsZero) {
1071 int preferredScale = Math.max(lhs.scale(), augend
1072 .scale());
1073 BigDecimal result;
1074
1075 // Could use a factory for zero instead of a new object
1076 if (lhsIsZero && augendIsZero)
1077 return new BigDecimal(BigInteger.ZERO, 0,
1078 preferredScale);
1079
1080 result = lhsIsZero ? augend.doRound(mc) : lhs
1081 .doRound(mc);
1082
1083 if (result.scale() == preferredScale)
1084 return result;
1085 else if (result.scale() > preferredScale)
1086 return new BigDecimal(result.intVal,
1087 result.intCompact, result.scale)
1088 .stripZerosToMatchScale(preferredScale);
1089 else { // result.scale < preferredScale
1090 int precisionDiff = mc.precision
1091 - result.precision();
1092 int scaleDiff = preferredScale - result.scale();
1093
1094 if (precisionDiff >= scaleDiff)
1095 return result.setScale(preferredScale); // can achieve target scale
1096 else
1097 return result.setScale(result.scale()
1098 + precisionDiff);
1099 }
1100 }
1101 }
1102
1103 long padding = (long) lhs.scale - augend.scale;
1104 if (padding != 0) { // scales differ; alignment needed
1105 BigDecimal arg[] = preAlign(lhs, augend, padding, mc);
1106 matchScale(arg);
1107 lhs = arg[0];
1108 augend = arg[1];
1109 }
1110
1111 return new BigDecimal(lhs.inflate().intVal
1112 .add(augend.inflate().intVal), lhs.scale).doRound(mc);
1113 }
1114
1115 /**
1116 * Returns an array of length two, the sum of whose entries is
1117 * equal to the rounded sum of the {@code BigDecimal} arguments.
1118 *
1119 * <p>If the digit positions of the arguments have a sufficient
1120 * gap between them, the value smaller in magnitude can be
1121 * condensed into a {@literal "sticky bit"} and the end result will
1122 * round the same way <em>if</em> the precision of the final
1123 * result does not include the high order digit of the small
1124 * magnitude operand.
1125 *
1126 * <p>Note that while strictly speaking this is an optimization,
1127 * it makes a much wider range of additions practical.
1128 *
1129 * <p>This corresponds to a pre-shift operation in a fixed
1130 * precision floating-point adder; this method is complicated by
1131 * variable precision of the result as determined by the
1132 * MathContext. A more nuanced operation could implement a
1133 * {@literal "right shift"} on the smaller magnitude operand so
1134 * that the number of digits of the smaller operand could be
1135 * reduced even though the significands partially overlapped.
1136 */
1137 private BigDecimal[] preAlign(BigDecimal lhs, BigDecimal augend,
1138 long padding, MathContext mc) {
1139 assert padding != 0;
1140 BigDecimal big;
1141 BigDecimal small;
1142
1143 if (padding < 0) { // lhs is big; augend is small
1144 big = lhs;
1145 small = augend;
1146 } else { // lhs is small; augend is big
1147 big = augend;
1148 small = lhs;
1149 }
1150
1151 /*
1152 * This is the estimated scale of an ulp of the result; it
1153 * assumes that the result doesn't have a carry-out on a true
1154 * add (e.g. 999 + 1 => 1000) or any subtractive cancellation
1155 * on borrowing (e.g. 100 - 1.2 => 98.8)
1156 */
1157 long estResultUlpScale = (long) big.scale - big.precision()
1158 + mc.precision;
1159
1160 /*
1161 * The low-order digit position of big is big.scale(). This
1162 * is true regardless of whether big has a positive or
1163 * negative scale. The high-order digit position of small is
1164 * small.scale - (small.precision() - 1). To do the full
1165 * condensation, the digit positions of big and small must be
1166 * disjoint *and* the digit positions of small should not be
1167 * directly visible in the result.
1168 */
1169 long smallHighDigitPos = (long) small.scale - small.precision()
1170 + 1;
1171 if (smallHighDigitPos > big.scale + 2 && // big and small disjoint
1172 smallHighDigitPos > estResultUlpScale + 2) { // small digits not visible
1173 small = BigDecimal.valueOf(small.signum(),
1174 this .checkScale(Math.max(big.scale,
1175 estResultUlpScale) + 3));
1176 }
1177
1178 // Since addition is symmetric, preserving input order in
1179 // returned operands doesn't matter
1180 BigDecimal[] result = { big, small };
1181 return result;
1182 }
1183
1184 /**
1185 * Returns a {@code BigDecimal} whose value is {@code (this -
1186 * subtrahend)}, and whose scale is {@code max(this.scale(),
1187 * subtrahend.scale())}.
1188 *
1189 * @param subtrahend value to be subtracted from this {@code BigDecimal}.
1190 * @return {@code this - subtrahend}
1191 */
1192 public BigDecimal subtract(BigDecimal subtrahend) {
1193 BigDecimal arg[] = { this , subtrahend };
1194 matchScale(arg);
1195
1196 long x = arg[0].intCompact;
1197 long y = arg[1].intCompact;
1198
1199 // Might be able to do a more clever check incorporating the
1200 // inflated check into the overflow computation.
1201 if (x != INFLATED && y != INFLATED) {
1202 long difference = x - y;
1203 /*
1204 * If the difference is not an overflowed value, continue
1205 * to use the compact representation. if either of x or y
1206 * is INFLATED, the difference should also be regarded as
1207 * an overflow. See "Hacker's Delight" section 2-12 for
1208 * explanation of the overflow test.
1209 */
1210 if (((x ^ y) & (difference ^ x)) >> 63 == 0L) // not overflowed
1211 return BigDecimal.valueOf(difference, arg[0].scale);
1212 }
1213 return new BigDecimal(arg[0].inflate().intVal.subtract(arg[1]
1214 .inflate().intVal), arg[0].scale);
1215 }
1216
1217 /**
1218 * Returns a {@code BigDecimal} whose value is {@code (this - subtrahend)},
1219 * with rounding according to the context settings.
1220 *
1221 * If {@code subtrahend} is zero then this, rounded if necessary, is used as the
1222 * result. If this is zero then the result is {@code subtrahend.negate(mc)}.
1223 *
1224 * @param subtrahend value to be subtracted from this {@code BigDecimal}.
1225 * @param mc the context to use.
1226 * @return {@code this - subtrahend}, rounded as necessary.
1227 * @throws ArithmeticException if the result is inexact but the
1228 * rounding mode is {@code UNNECESSARY}.
1229 * @since 1.5
1230 */
1231 public BigDecimal subtract(BigDecimal subtrahend, MathContext mc) {
1232 if (mc.precision == 0)
1233 return subtract(subtrahend);
1234 // share the special rounding code in add()
1235 this .inflate();
1236 subtrahend.inflate();
1237 BigDecimal rhs = new BigDecimal(subtrahend.intVal.negate(),
1238 subtrahend.scale);
1239 rhs.precision = subtrahend.precision;
1240 return add(rhs, mc);
1241 }
1242
1243 /**
1244 * Returns a {@code BigDecimal} whose value is <tt>(this ×
1245 * multiplicand)</tt>, and whose scale is {@code (this.scale() +
1246 * multiplicand.scale())}.
1247 *
1248 * @param multiplicand value to be multiplied by this {@code BigDecimal}.
1249 * @return {@code this * multiplicand}
1250 */
1251 public BigDecimal multiply(BigDecimal multiplicand) {
1252 long x = this .intCompact;
1253 long y = multiplicand.intCompact;
1254 int productScale = checkScale((long) scale + multiplicand.scale);
1255
1256 // Might be able to do a more clever check incorporating the
1257 // inflated check into the overflow computation.
1258 if (x != INFLATED && y != INFLATED) {
1259 /*
1260 * If the product is not an overflowed value, continue
1261 * to use the compact representation. if either of x or y
1262 * is INFLATED, the product should also be regarded as
1263 * an overflow. See "Hacker's Delight" section 2-12 for
1264 * explanation of the overflow test.
1265 */
1266 long product = x * y;
1267 if (!(y != 0L && product / y != x)) // not overflowed
1268 return BigDecimal.valueOf(product, productScale);
1269 }
1270
1271 BigDecimal result = new BigDecimal(this .inflate().intVal
1272 .multiply(multiplicand.inflate().intVal), productScale);
1273 return result;
1274 }
1275
1276 /**
1277 * Returns a {@code BigDecimal} whose value is <tt>(this ×
1278 * multiplicand)</tt>, with rounding according to the context settings.
1279 *
1280 * @param multiplicand value to be multiplied by this {@code BigDecimal}.
1281 * @param mc the context to use.
1282 * @return {@code this * multiplicand}, rounded as necessary.
1283 * @throws ArithmeticException if the result is inexact but the
1284 * rounding mode is {@code UNNECESSARY}.
1285 * @since 1.5
1286 */
1287 public BigDecimal multiply(BigDecimal multiplicand, MathContext mc) {
1288 if (mc.precision == 0)
1289 return multiply(multiplicand);
1290 BigDecimal lhs = this ;
1291 return lhs.inflate().multiply(multiplicand.inflate()).doRound(
1292 mc);
1293 }
1294
1295 /**
1296 * Returns a {@code BigDecimal} whose value is {@code (this /
1297 * divisor)}, and whose scale is as specified. If rounding must
1298 * be performed to generate a result with the specified scale, the
1299 * specified rounding mode is applied.
1300 *
1301 * <p>The new {@link #divide(BigDecimal, int, RoundingMode)} method
1302 * should be used in preference to this legacy method.
1303 *
1304 * @param divisor value by which this {@code BigDecimal} is to be divided.
1305 * @param scale scale of the {@code BigDecimal} quotient to be returned.
1306 * @param roundingMode rounding mode to apply.
1307 * @return {@code this / divisor}
1308 * @throws ArithmeticException if {@code divisor} is zero,
1309 * {@code roundingMode==ROUND_UNNECESSARY} and
1310 * the specified scale is insufficient to represent the result
1311 * of the division exactly.
1312 * @throws IllegalArgumentException if {@code roundingMode} does not
1313 * represent a valid rounding mode.
1314 * @see #ROUND_UP
1315 * @see #ROUND_DOWN
1316 * @see #ROUND_CEILING
1317 * @see #ROUND_FLOOR
1318 * @see #ROUND_HALF_UP
1319 * @see #ROUND_HALF_DOWN
1320 * @see #ROUND_HALF_EVEN
1321 * @see #ROUND_UNNECESSARY
1322 */
1323 public BigDecimal divide(BigDecimal divisor, int scale,
1324 int roundingMode) {
1325 /*
1326 * IMPLEMENTATION NOTE: This method *must* return a new object
1327 * since dropDigits uses divide to generate a value whose
1328 * scale is then modified.
1329 */
1330 if (roundingMode < ROUND_UP || roundingMode > ROUND_UNNECESSARY)
1331 throw new IllegalArgumentException("Invalid rounding mode");
1332 /*
1333 * Rescale dividend or divisor (whichever can be "upscaled" to
1334 * produce correctly scaled quotient).
1335 * Take care to detect out-of-range scales
1336 */
1337 BigDecimal dividend;
1338 if (checkScale((long) scale + divisor.scale) >= this .scale) {
1339 dividend = this .setScale(scale + divisor.scale);
1340 } else {
1341 dividend = this ;
1342 divisor = divisor.setScale(checkScale((long) this .scale
1343 - scale));
1344 }
1345
1346 boolean compact = dividend.intCompact != INFLATED
1347 && divisor.intCompact != INFLATED;
1348 long div = INFLATED;
1349 long rem = INFLATED;
1350 ;
1351 BigInteger q = null, r = null;
1352
1353 if (compact) {
1354 div = dividend.intCompact / divisor.intCompact;
1355 rem = dividend.intCompact % divisor.intCompact;
1356 } else {
1357 // Do the division and return result if it's exact.
1358 BigInteger i[] = dividend.inflate().intVal
1359 .divideAndRemainder(divisor.inflate().intVal);
1360 q = i[0];
1361 r = i[1];
1362 }
1363
1364 // Check for exact result
1365 if (compact) {
1366 if (rem == 0)
1367 return new BigDecimal(div, scale);
1368 } else {
1369 if (r.signum() == 0)
1370 return new BigDecimal(q, scale);
1371 }
1372
1373 if (roundingMode == ROUND_UNNECESSARY) // Rounding prohibited
1374 throw new ArithmeticException("Rounding necessary");
1375
1376 /* Round as appropriate */
1377 int signum = dividend.signum() * divisor.signum(); // Sign of result
1378 boolean increment;
1379 if (roundingMode == ROUND_UP) { // Away from zero
1380 increment = true;
1381 } else if (roundingMode == ROUND_DOWN) { // Towards zero
1382 increment = false;
1383 } else if (roundingMode == ROUND_CEILING) { // Towards +infinity
1384 increment = (signum > 0);
1385 } else if (roundingMode == ROUND_FLOOR) { // Towards -infinity
1386 increment = (signum < 0);
1387 } else { // Remaining modes based on nearest-neighbor determination
1388 int cmpFracHalf;
1389 if (compact) {
1390 cmpFracHalf = longCompareTo(Math.abs(2 * rem), Math
1391 .abs(divisor.intCompact));
1392 } else {
1393 // add(r) here is faster than multiply(2) or shiftLeft(1)
1394 cmpFracHalf = r.add(r).abs().compareTo(
1395 divisor.intVal.abs());
1396 }
1397 if (cmpFracHalf < 0) { // We're closer to higher digit
1398 increment = false;
1399 } else if (cmpFracHalf > 0) { // We're closer to lower digit
1400 increment = true;
1401 } else { // We're dead-center
1402 if (roundingMode == ROUND_HALF_UP)
1403 increment = true;
1404 else if (roundingMode == ROUND_HALF_DOWN)
1405 increment = false;
1406 else { // roundingMode == ROUND_HALF_EVEN
1407 if (compact)
1408 increment = (div & 1L) != 0L;
1409 else
1410 increment = q.testBit(0); // true iff q is odd
1411 }
1412 }
1413 }
1414
1415 if (compact) {
1416 if (increment)
1417 div += signum; // guaranteed not to overflow
1418 return new BigDecimal(div, scale);
1419 } else {
1420 return (increment ? new BigDecimal(q.add(BigInteger
1421 .valueOf(signum)), scale)
1422 : new BigDecimal(q, scale));
1423 }
1424 }
1425
1426 /**
1427 * Returns a {@code BigDecimal} whose value is {@code (this /
1428 * divisor)}, and whose scale is as specified. If rounding must
1429 * be performed to generate a result with the specified scale, the
1430 * specified rounding mode is applied.
1431 *
1432 * @param divisor value by which this {@code BigDecimal} is to be divided.
1433 * @param scale scale of the {@code BigDecimal} quotient to be returned.
1434 * @param roundingMode rounding mode to apply.
1435 * @return {@code this / divisor}
1436 * @throws ArithmeticException if {@code divisor} is zero,
1437 * {@code roundingMode==RoundingMode.UNNECESSARY} and
1438 * the specified scale is insufficient to represent the result
1439 * of the division exactly.
1440 * @since 1.5
1441 */
1442 public BigDecimal divide(BigDecimal divisor, int scale,
1443 RoundingMode roundingMode) {
1444 return divide(divisor, scale, roundingMode.oldMode);
1445 }
1446
1447 /**
1448 * Returns a {@code BigDecimal} whose value is {@code (this /
1449 * divisor)}, and whose scale is {@code this.scale()}. If
1450 * rounding must be performed to generate a result with the given
1451 * scale, the specified rounding mode is applied.
1452 *
1453 * <p>The new {@link #divide(BigDecimal, RoundingMode)} method
1454 * should be used in preference to this legacy method.
1455 *
1456 * @param divisor value by which this {@code BigDecimal} is to be divided.
1457 * @param roundingMode rounding mode to apply.
1458 * @return {@code this / divisor}
1459 * @throws ArithmeticException if {@code divisor==0}, or
1460 * {@code roundingMode==ROUND_UNNECESSARY} and
1461 * {@code this.scale()} is insufficient to represent the result
1462 * of the division exactly.
1463 * @throws IllegalArgumentException if {@code roundingMode} does not
1464 * represent a valid rounding mode.
1465 * @see #ROUND_UP
1466 * @see #ROUND_DOWN
1467 * @see #ROUND_CEILING
1468 * @see #ROUND_FLOOR
1469 * @see #ROUND_HALF_UP
1470 * @see #ROUND_HALF_DOWN
1471 * @see #ROUND_HALF_EVEN
1472 * @see #ROUND_UNNECESSARY
1473 */
1474 public BigDecimal divide(BigDecimal divisor, int roundingMode) {
1475 return this .divide(divisor, scale, roundingMode);
1476 }
1477
1478 /**
1479 * Returns a {@code BigDecimal} whose value is {@code (this /
1480 * divisor)}, and whose scale is {@code this.scale()}. If
1481 * rounding must be performed to generate a result with the given
1482 * scale, the specified rounding mode is applied.
1483 *
1484 * @param divisor value by which this {@code BigDecimal} is to be divided.
1485 * @param roundingMode rounding mode to apply.
1486 * @return {@code this / divisor}
1487 * @throws ArithmeticException if {@code divisor==0}, or
1488 * {@code roundingMode==RoundingMode.UNNECESSARY} and
1489 * {@code this.scale()} is insufficient to represent the result
1490 * of the division exactly.
1491 * @since 1.5
1492 */
1493 public BigDecimal divide(BigDecimal divisor,
1494 RoundingMode roundingMode) {
1495 return this .divide(divisor, scale, roundingMode.oldMode);
1496 }
1497
1498 /**
1499 * Returns a {@code BigDecimal} whose value is {@code (this /
1500 * divisor)}, and whose preferred scale is {@code (this.scale() -
1501 * divisor.scale())}; if the exact quotient cannot be
1502 * represented (because it has a non-terminating decimal
1503 * expansion) an {@code ArithmeticException} is thrown.
1504 *
1505 * @param divisor value by which this {@code BigDecimal} is to be divided.
1506 * @throws ArithmeticException if the exact quotient does not have a
1507 * terminating decimal expansion
1508 * @return {@code this / divisor}
1509 * @since 1.5
1510 * @author Joseph D. Darcy
1511 */
1512 public BigDecimal divide(BigDecimal divisor) {
1513 /*
1514 * Handle zero cases first.
1515 */
1516 if (divisor.signum() == 0) { // x/0
1517 if (this .signum() == 0) // 0/0
1518 throw new ArithmeticException("Division undefined"); // NaN
1519 throw new ArithmeticException("Division by zero");
1520 }
1521
1522 // Calculate preferred scale
1523 int preferredScale = (int) Math.max(Math.min((long) this
1524 .scale()
1525 - divisor.scale(), Integer.MAX_VALUE),
1526 Integer.MIN_VALUE);
1527 if (this .signum() == 0) // 0/y
1528 return new BigDecimal(0, preferredScale);
1529 else {
1530 this .inflate();
1531 divisor.inflate();
1532 /*
1533 * If the quotient this/divisor has a terminating decimal
1534 * expansion, the expansion can have no more than
1535 * (a.precision() + ceil(10*b.precision)/3) digits.
1536 * Therefore, create a MathContext object with this
1537 * precision and do a divide with the UNNECESSARY rounding
1538 * mode.
1539 */
1540 MathContext mc = new MathContext((int) Math.min(this
1541 .precision()
1542 + (long) Math
1543 .ceil(10.0 * divisor.precision() / 3.0),
1544 Integer.MAX_VALUE), RoundingMode.UNNECESSARY);
1545 BigDecimal quotient;
1546 try {
1547 quotient = this .divide(divisor, mc);
1548 } catch (ArithmeticException e) {
1549 throw new ArithmeticException(
1550 "Non-terminating decimal expansion; "
1551 + "no exact representable decimal result.");
1552 }
1553
1554 int quotientScale = quotient.scale();
1555
1556 // divide(BigDecimal, mc) tries to adjust the quotient to
1557 // the desired one by removing trailing zeros; since the
1558 // exact divide method does not have an explicit digit
1559 // limit, we can add zeros too.
1560
1561 if (preferredScale > quotientScale)
1562 return quotient.setScale(preferredScale);
1563
1564 return quotient;
1565 }
1566 }
1567
1568 /**
1569 * Returns a {@code BigDecimal} whose value is {@code (this /
1570 * divisor)}, with rounding according to the context settings.
1571 *
1572 * @param divisor value by which this {@code BigDecimal} is to be divided.
1573 * @param mc the context to use.
1574 * @return {@code this / divisor}, rounded as necessary.
1575 * @throws ArithmeticException if the result is inexact but the
1576 * rounding mode is {@code UNNECESSARY} or
1577 * {@code mc.precision == 0} and the quotient has a
1578 * non-terminating decimal expansion.
1579 * @since 1.5
1580 */
1581 public BigDecimal divide(BigDecimal divisor, MathContext mc) {
1582 if (mc.precision == 0)
1583 return divide(divisor);
1584 BigDecimal lhs = this .inflate(); // left-hand-side
1585 BigDecimal rhs = divisor.inflate(); // right-hand-side
1586 BigDecimal result; // work
1587
1588 long preferredScale = (long) lhs.scale() - rhs.scale();
1589
1590 // Now calculate the answer. We use the existing
1591 // divide-and-round method, but as this rounds to scale we have
1592 // to normalize the values here to achieve the desired result.
1593 // For x/y we first handle y=0 and x=0, and then normalize x and
1594 // y to give x' and y' with the following constraints:
1595 // (a) 0.1 <= x' < 1
1596 // (b) x' <= y' < 10*x'
1597 // Dividing x'/y' with the required scale set to mc.precision then
1598 // will give a result in the range 0.1 to 1 rounded to exactly
1599 // the right number of digits (except in the case of a result of
1600 // 1.000... which can arise when x=y, or when rounding overflows
1601 // The 1.000... case will reduce properly to 1.
1602 if (rhs.signum() == 0) { // x/0
1603 if (lhs.signum() == 0) // 0/0
1604 throw new ArithmeticException("Division undefined"); // NaN
1605 throw new ArithmeticException("Division by zero");
1606 }
1607 if (lhs.signum() == 0) // 0/y
1608 return new BigDecimal(BigInteger.ZERO, (int) Math.max(Math
1609 .min(preferredScale, Integer.MAX_VALUE),
1610 Integer.MIN_VALUE));
1611
1612 BigDecimal xprime = new BigDecimal(lhs.intVal.abs(), lhs
1613 .precision());
1614 BigDecimal yprime = new BigDecimal(rhs.intVal.abs(), rhs
1615 .precision());
1616 // xprime and yprime are now both in range 0.1 through 0.999...
1617 if (mc.roundingMode == RoundingMode.CEILING
1618 || mc.roundingMode == RoundingMode.FLOOR) {
1619 // The floor (round toward negative infinity) and ceil
1620 // (round toward positive infinity) rounding modes are not
1621 // invariant under a sign flip. If xprime/yprime has a
1622 // different sign than lhs/rhs, the rounding mode must be
1623 // changed.
1624 if ((xprime.signum() != lhs.signum())
1625 ^ (yprime.signum() != rhs.signum())) {
1626 mc = new MathContext(
1627 mc.precision,
1628 (mc.roundingMode == RoundingMode.CEILING) ? RoundingMode.FLOOR
1629 : RoundingMode.CEILING);
1630 }
1631 }
1632
1633 if (xprime.compareTo(yprime) > 0) // satisfy constraint (b)
1634 yprime.scale -= 1; // [that is, yprime *= 10]
1635 result = xprime.divide(yprime, mc.precision,
1636 mc.roundingMode.oldMode);
1637 // correct the scale of the result...
1638 result.scale = checkScale((long) yprime.scale - xprime.scale
1639 - (rhs.scale - lhs.scale) + mc.precision);
1640 // apply the sign
1641 if (lhs.signum() != rhs.signum())
1642 result = result.negate();
1643 // doRound, here, only affects 1000000000 case.
1644 result = result.doRound(mc);
1645
1646 if (result.multiply(divisor).compareTo(this ) == 0) {
1647 // Apply preferred scale rules for exact quotients
1648 return result.stripZerosToMatchScale(preferredScale);
1649 } else {
1650 return result;
1651 }
1652 }
1653
1654 /**
1655 * Returns a {@code BigDecimal} whose value is the integer part
1656 * of the quotient {@code (this / divisor)} rounded down. The
1657 * preferred scale of the result is {@code (this.scale() -
1658 * divisor.scale())}.
1659 *
1660 * @param divisor value by which this {@code BigDecimal} is to be divided.
1661 * @return The integer part of {@code this / divisor}.
1662 * @throws ArithmeticException if {@code divisor==0}
1663 * @since 1.5
1664 */
1665 public BigDecimal divideToIntegralValue(BigDecimal divisor) {
1666 // Calculate preferred scale
1667 int preferredScale = (int) Math.max(Math.min((long) this
1668 .scale()
1669 - divisor.scale(), Integer.MAX_VALUE),
1670 Integer.MIN_VALUE);
1671 this .inflate();
1672 divisor.inflate();
1673 if (this .abs().compareTo(divisor.abs()) < 0) {
1674 // much faster when this << divisor
1675 return BigDecimal.valueOf(0, preferredScale);
1676 }
1677
1678 if (this .signum() == 0 && divisor.signum() != 0)
1679 return this .setScale(preferredScale);
1680
1681 // Perform a divide with enough digits to round to a correct
1682 // integer value; then remove any fractional digits
1683
1684 int maxDigits = (int) Math.min(this .precision()
1685 + (long) Math.ceil(10.0 * divisor.precision() / 3.0)
1686 + Math.abs((long) this .scale() - divisor.scale()) + 2,
1687 Integer.MAX_VALUE);
1688
1689 BigDecimal quotient = this .divide(divisor, new MathContext(
1690 maxDigits, RoundingMode.DOWN));
1691 if (quotient.scale > 0) {
1692 quotient = quotient.setScale(0, RoundingMode.DOWN)
1693 .stripZerosToMatchScale(preferredScale);
1694 }
1695
1696 if (quotient.scale < preferredScale) {
1697 // pad with zeros if necessary
1698 quotient = quotient.setScale(preferredScale);
1699 }
1700
1701 return quotient;
1702 }
1703
1704 /**
1705 * Returns a {@code BigDecimal} whose value is the integer part
1706 * of {@code (this / divisor)}. Since the integer part of the
1707 * exact quotient does not depend on the rounding mode, the
1708 * rounding mode does not affect the values returned by this
1709 * method. The preferred scale of the result is
1710 * {@code (this.scale() - divisor.scale())}. An
1711 * {@code ArithmeticException} is thrown if the integer part of
1712 * the exact quotient needs more than {@code mc.precision}
1713 * digits.
1714 *
1715 * @param divisor value by which this {@code BigDecimal} is to be divided.
1716 * @param mc the context to use.
1717 * @return The integer part of {@code this / divisor}.
1718 * @throws ArithmeticException if {@code divisor==0}
1719 * @throws ArithmeticException if {@code mc.precision} {@literal >} 0 and the result
1720 * requires a precision of more than {@code mc.precision} digits.
1721 * @since 1.5
1722 * @author Joseph D. Darcy
1723 */
1724 public BigDecimal divideToIntegralValue(BigDecimal divisor,
1725 MathContext mc) {
1726 if (mc.precision == 0 || // exact result
1727 (this .abs().compareTo(divisor.abs()) < 0)) // zero result
1728 return divideToIntegralValue(divisor);
1729
1730 // Calculate preferred scale
1731 int preferredScale = (int) Math.max(Math.min((long) this
1732 .scale()
1733 - divisor.scale(), Integer.MAX_VALUE),
1734 Integer.MIN_VALUE);
1735
1736 /*
1737 * Perform a normal divide to mc.precision digits. If the
1738 * remainder has absolute value less than the divisor, the
1739 * integer portion of the quotient fits into mc.precision
1740 * digits. Next, remove any fractional digits from the
1741 * quotient and adjust the scale to the preferred value.
1742 */
1743 BigDecimal result = this .divide(divisor, new MathContext(
1744 mc.precision, RoundingMode.DOWN));
1745 int resultScale = result.scale();
1746
1747 if (result.scale() < 0) {
1748 /*
1749 * Result is an integer. See if quotient represents the
1750 * full integer portion of the exact quotient; if it does,
1751 * the computed remainder will be less than the divisor.
1752 */
1753 BigDecimal product = result.multiply(divisor);
1754 // If the quotient is the full integer value,
1755 // |dividend-product| < |divisor|.
1756 if (this .subtract(product).abs().compareTo(divisor.abs()) >= 0) {
1757 throw new ArithmeticException("Division impossible");
1758 }
1759 } else if (result.scale() > 0) {
1760 /*
1761 * Integer portion of quotient will fit into precision
1762 * digits; recompute quotient to scale 0 to avoid double
1763 * rounding and then try to adjust, if necessary.
1764 */
1765 result = result.setScale(0, RoundingMode.DOWN);
1766 }
1767 // else result.scale() == 0;
1768
1769 int precisionDiff;
1770 if ((preferredScale > result.scale())
1771 && (precisionDiff = mc.precision - result.precision()) > 0) {
1772 return result.setScale(result.scale()
1773 + Math.min(precisionDiff, preferredScale
1774 - result.scale));
1775 } else
1776 return result.stripZerosToMatchScale(preferredScale);
1777 }
1778
1779 /**
1780 * Returns a {@code BigDecimal} whose value is {@code (this % divisor)}.
1781 *
1782 * <p>The remainder is given by
1783 * {@code this.subtract(this.divideToIntegralValue(divisor).multiply(divisor))}.
1784 * Note that this is not the modulo operation (the result can be
1785 * negative).
1786 *
1787 * @param divisor value by which this {@code BigDecimal} is to be divided.
1788 * @return {@code this % divisor}.
1789 * @throws ArithmeticException if {@code divisor==0}
1790 * @since 1.5
1791 */
1792 public BigDecimal remainder(BigDecimal divisor) {
1793 BigDecimal divrem[] = this .divideAndRemainder(divisor);
1794 return divrem[1];
1795 }
1796
1797 /**
1798 * Returns a {@code BigDecimal} whose value is {@code (this %
1799 * divisor)}, with rounding according to the context settings.
1800 * The {@code MathContext} settings affect the implicit divide
1801 * used to compute the remainder. The remainder computation
1802 * itself is by definition exact. Therefore, the remainder may
1803 * contain more than {@code mc.getPrecision()} digits.
1804 *
1805 * <p>The remainder is given by
1806 * {@code this.subtract(this.divideToIntegralValue(divisor,
1807 * mc).multiply(divisor))}. Note that this is not the modulo
1808 * operation (the result can be negative).
1809 *
1810 * @param divisor value by which this {@code BigDecimal} is to be divided.
1811 * @param mc the context to use.
1812 * @return {@code this % divisor}, rounded as necessary.
1813 * @throws ArithmeticException if {@code divisor==0}
1814 * @throws ArithmeticException if the result is inexact but the
1815 * rounding mode is {@code UNNECESSARY}, or {@code mc.precision}
1816 * {@literal >} 0 and the result of {@code this.divideToIntgralValue(divisor)} would
1817 * require a precision of more than {@code mc.precision} digits.
1818 * @see #divideToIntegralValue(java.math.BigDecimal, java.math.MathContext)
1819 * @since 1.5
1820 */
1821 public BigDecimal remainder(BigDecimal divisor, MathContext mc) {
1822 BigDecimal divrem[] = this .divideAndRemainder(divisor, mc);
1823 return divrem[1];
1824 }
1825
1826 /**
1827 * Returns a two-element {@code BigDecimal} array containing the
1828 * result of {@code divideToIntegralValue} followed by the result of
1829 * {@code remainder} on the two operands.
1830 *
1831 * <p>Note that if both the integer quotient and remainder are
1832 * needed, this method is faster than using the
1833 * {@code divideToIntegralValue} and {@code remainder} methods
1834 * separately because the division need only be carried out once.
1835 *
1836 * @param divisor value by which this {@code BigDecimal} is to be divided,
1837 * and the remainder computed.
1838 * @return a two element {@code BigDecimal} array: the quotient
1839 * (the result of {@code divideToIntegralValue}) is the initial element
1840 * and the remainder is the final element.
1841 * @throws ArithmeticException if {@code divisor==0}
1842 * @see #divideToIntegralValue(java.math.BigDecimal, java.math.MathContext)
1843 * @see #remainder(java.math.BigDecimal, java.math.MathContext)
1844 * @since 1.5
1845 */
1846 public BigDecimal[] divideAndRemainder(BigDecimal divisor) {
1847 // we use the identity x = i * y + r to determine r
1848 BigDecimal[] result = new BigDecimal[2];
1849
1850 result[0] = this .divideToIntegralValue(divisor);
1851 result[1] = this .subtract(result[0].multiply(divisor));
1852 return result;
1853 }
1854
1855 /**
1856 * Returns a two-element {@code BigDecimal} array containing the
1857 * result of {@code divideToIntegralValue} followed by the result of
1858 * {@code remainder} on the two operands calculated with rounding
1859 * according to the context settings.
1860 *
1861 * <p>Note that if both the integer quotient and remainder are
1862 * needed, this method is faster than using the
1863 * {@code divideToIntegralValue} and {@code remainder} methods
1864 * separately because the division need only be carried out once.
1865 *
1866 * @param divisor value by which this {@code BigDecimal} is to be divided,
1867 * and the remainder computed.
1868 * @param mc the context to use.
1869 * @return a two element {@code BigDecimal} array: the quotient
1870 * (the result of {@code divideToIntegralValue}) is the
1871 * initial element and the remainder is the final element.
1872 * @throws ArithmeticException if {@code divisor==0}
1873 * @throws ArithmeticException if the result is inexact but the
1874 * rounding mode is {@code UNNECESSARY}, or {@code mc.precision}
1875 * {@literal >} 0 and the result of {@code this.divideToIntgralValue(divisor)} would
1876 * require a precision of more than {@code mc.precision} digits.
1877 * @see #divideToIntegralValue(java.math.BigDecimal, java.math.MathContext)
1878 * @see #remainder(java.math.BigDecimal, java.math.MathContext)
1879 * @since 1.5
1880 */
1881 public BigDecimal[] divideAndRemainder(BigDecimal divisor,
1882 MathContext mc) {
1883 if (mc.precision == 0)
1884 return divideAndRemainder(divisor);
1885
1886 BigDecimal[] result = new BigDecimal[2];
1887 BigDecimal lhs = this ;
1888
1889 result[0] = lhs.divideToIntegralValue(divisor, mc);
1890 result[1] = lhs.subtract(result[0].multiply(divisor));
1891 return result;
1892 }
1893
1894 /**
1895 * Returns a {@code BigDecimal} whose value is
1896 * <tt>(this<sup>n</sup>)</tt>, The power is computed exactly, to
1897 * unlimited precision.
1898 *
1899 * <p>The parameter {@code n} must be in the range 0 through
1900 * 999999999, inclusive. {@code ZERO.pow(0)} returns {@link
1901 * #ONE}.
1902 *
1903 * Note that future releases may expand the allowable exponent
1904 * range of this method.
1905 *
1906 * @param n power to raise this {@code BigDecimal} to.
1907 * @return <tt>this<sup>n</sup></tt>
1908 * @throws ArithmeticException if {@code n} is out of range.
1909 * @since 1.5
1910 */
1911 public BigDecimal pow(int n) {
1912 if (n < 0 || n > 999999999)
1913 throw new ArithmeticException("Invalid operation");
1914 // No need to calculate pow(n) if result will over/underflow.
1915 // Don't attempt to support "supernormal" numbers.
1916 int newScale = checkScale((long) scale * n);
1917 this .inflate();
1918 return new BigDecimal(intVal.pow(n), newScale);
1919 }
1920
1921 /**
1922 * Returns a {@code BigDecimal} whose value is
1923 * <tt>(this<sup>n</sup>)</tt>. The current implementation uses
1924 * the core algorithm defined in ANSI standard X3.274-1996 with
1925 * rounding according to the context settings. In general, the
1926 * returned numerical value is within two ulps of the exact
1927 * numerical value for the chosen precision. Note that future
1928 * releases may use a different algorithm with a decreased
1929 * allowable error bound and increased allowable exponent range.
1930 *
1931 * <p>The X3.274-1996 algorithm is:
1932 *
1933 * <ul>
1934 * <li> An {@code ArithmeticException} exception is thrown if
1935 * <ul>
1936 * <li>{@code abs(n) > 999999999}
1937 * <li>{@code mc.precision == 0} and {@code n < 0}
1938 * <li>{@code mc.precision > 0} and {@code n} has more than
1939 * {@code mc.precision} decimal digits
1940 * </ul>
1941 *
1942 * <li> if {@code n} is zero, {@link #ONE} is returned even if
1943 * {@code this} is zero, otherwise
1944 * <ul>
1945 * <li> if {@code n} is positive, the result is calculated via
1946 * the repeated squaring technique into a single accumulator.
1947 * The individual multiplications with the accumulator use the
1948 * same math context settings as in {@code mc} except for a
1949 * precision increased to {@code mc.precision + elength + 1}
1950 * where {@code elength} is the number of decimal digits in
1951 * {@code n}.
1952 *
1953 * <li> if {@code n} is negative, the result is calculated as if
1954 * {@code n} were positive; this value is then divided into one
1955 * using the working precision specified above.
1956 *
1957 * <li> The final value from either the positive or negative case
1958 * is then rounded to the destination precision.
1959 * </ul>
1960 * </ul>
1961 *
1962 * @param n power to raise this {@code BigDecimal} to.
1963 * @param mc the context to use.
1964 * @return <tt>this<sup>n</sup></tt> using the ANSI standard X3.274-1996
1965 * algorithm
1966 * @throws ArithmeticException if the result is inexact but the
1967 * rounding mode is {@code UNNECESSARY}, or {@code n} is out
1968 * of range.
1969 * @since 1.5
1970 */
1971 public BigDecimal pow(int n, MathContext mc) {
1972 if (mc.precision == 0)
1973 return pow(n);
1974 if (n < -999999999 || n > 999999999)
1975 throw new ArithmeticException("Invalid operation");
1976 if (n == 0)
1977 return ONE; // x**0 == 1 in X3.274
1978 this .inflate();
1979 BigDecimal lhs = this ;
1980 MathContext workmc = mc; // working settings
1981 int mag = Math.abs(n); // magnitude of n
1982 if (mc.precision > 0) {
1983
1984 int elength = intLength(mag); // length of n in digits
1985 if (elength > mc.precision) // X3.274 rule
1986 throw new ArithmeticException("Invalid operation");
1987 workmc = new MathContext(mc.precision + elength + 1,
1988 mc.roundingMode);
1989 }
1990 // ready to carry out power calculation...
1991 BigDecimal acc = ONE; // accumulator
1992 boolean seenbit = false; // set once we've seen a 1-bit
1993 for (int i = 1;; i++) { // for each bit [top bit ignored]
1994 mag += mag; // shift left 1 bit
1995 if (mag < 0) { // top bit is set
1996 seenbit = true; // OK, we're off
1997 acc = acc.multiply(lhs, workmc); // acc=acc*x
1998 }
1999 if (i == 31)
2000 break; // that was the last bit
2001 if (seenbit)
2002 acc = acc.multiply(acc, workmc); // acc=acc*acc [square]
2003 // else (!seenbit) no point in squaring ONE
2004 }
2005 // if negative n, calculate the reciprocal using working precision
2006 if (n < 0) // [hence mc.precision>0]
2007 acc = ONE.divide(acc, workmc);
2008 // round to final precision and strip zeros
2009 return acc.doRound(mc);
2010 }
2011
2012 /**
2013 * Returns a {@code BigDecimal} whose value is the absolute value
2014 * of this {@code BigDecimal}, and whose scale is
2015 * {@code this.scale()}.
2016 *
2017 * @return {@code abs(this)}
2018 */
2019 public BigDecimal abs() {
2020 return (signum() < 0 ? negate() : this );
2021 }
2022
2023 /**
2024 * Returns a {@code BigDecimal} whose value is the absolute value
2025 * of this {@code BigDecimal}, with rounding according to the
2026 * context settings.
2027 *
2028 * @param mc the context to use.
2029 * @return {@code abs(this)}, rounded as necessary.
2030 * @throws ArithmeticException if the result is inexact but the
2031 * rounding mode is {@code UNNECESSARY}.
2032 * @since 1.5
2033 */
2034 public BigDecimal abs(MathContext mc) {
2035 return (signum() < 0 ? negate(mc) : plus(mc));
2036 }
2037
2038 /**
2039 * Returns a {@code BigDecimal} whose value is {@code (-this)},
2040 * and whose scale is {@code this.scale()}.
2041 *
2042 * @return {@code -this}.
2043 */
2044 public BigDecimal negate() {
2045 BigDecimal result;
2046 if (intCompact != INFLATED)
2047 result = BigDecimal.valueOf(-intCompact, scale);
2048 else {
2049 result = new BigDecimal(intVal.negate(), scale);
2050 result.precision = precision;
2051 }
2052 return result;
2053 }
2054
2055 /**
2056 * Returns a {@code BigDecimal} whose value is {@code (-this)},
2057 * with rounding according to the context settings.
2058 *
2059 * @param mc the context to use.
2060 * @return {@code -this}, rounded as necessary.
2061 * @throws ArithmeticException if the result is inexact but the
2062 * rounding mode is {@code UNNECESSARY}.
2063 * @since 1.5
2064 */
2065 public BigDecimal negate(MathContext mc) {
2066 return negate().plus(mc);
2067 }
2068
2069 /**
2070 * Returns a {@code BigDecimal} whose value is {@code (+this)}, and whose
2071 * scale is {@code this.scale()}.
2072 *
2073 * <p>This method, which simply returns this {@code BigDecimal}
2074 * is included for symmetry with the unary minus method {@link
2075 * #negate()}.
2076 *
2077 * @return {@code this}.
2078 * @see #negate()
2079 * @since 1.5
2080 */
2081 public BigDecimal plus() {
2082 return this ;
2083 }
2084
2085 /**
2086 * Returns a {@code BigDecimal} whose value is {@code (+this)},
2087 * with rounding according to the context settings.
2088 *
2089 * <p>The effect of this method is identical to that of the {@link
2090 * #round(MathContext)} method.
2091 *
2092 * @param mc the context to use.
2093 * @return {@code this}, rounded as necessary. A zero result will
2094 * have a scale of 0.
2095 * @throws ArithmeticException if the result is inexact but the
2096 * rounding mode is {@code UNNECESSARY}.
2097 * @see #round(MathContext)
2098 * @since 1.5
2099 */
2100 public BigDecimal plus(MathContext mc) {
2101 if (mc.precision == 0) // no rounding please
2102 return this ;
2103 return this .doRound(mc);
2104 }
2105
2106 /**
2107 * Returns the signum function of this {@code BigDecimal}.
2108 *
2109 * @return -1, 0, or 1 as the value of this {@code BigDecimal}
2110 * is negative, zero, or positive.
2111 */
2112 public int signum() {
2113 return (intCompact != INFLATED) ? Long.signum(intCompact)
2114 : intVal.signum();
2115 }
2116
2117 /**
2118 * Returns the <i>scale</i> of this {@code BigDecimal}. If zero
2119 * or positive, the scale is the number of digits to the right of
2120 * the decimal point. If negative, the unscaled value of the
2121 * number is multiplied by ten to the power of the negation of the
2122 * scale. For example, a scale of {@code -3} means the unscaled
2123 * value is multiplied by 1000.
2124 *
2125 * @return the scale of this {@code BigDecimal}.
2126 */
2127 public int scale() {
2128 return scale;
2129 }
2130
2131 /**
2132 * Returns the <i>precision</i> of this {@code BigDecimal}. (The
2133 * precision is the number of digits in the unscaled value.)
2134 *
2135 * <p>The precision of a zero value is 1.
2136 *
2137 * @return the precision of this {@code BigDecimal}.
2138 * @since 1.5
2139 */
2140 public int precision() {
2141 int result = precision;
2142 if (result == 0) {
2143 result = digitLength();
2144 precision = result;
2145 }
2146 return result;
2147 }
2148
2149 /**
2150 * Returns a {@code BigInteger} whose value is the <i>unscaled
2151 * value</i> of this {@code BigDecimal}. (Computes <tt>(this *
2152 * 10<sup>this.scale()</sup>)</tt>.)
2153 *
2154 * @return the unscaled value of this {@code BigDecimal}.
2155 * @since 1.2
2156 */
2157 public BigInteger unscaledValue() {
2158 return this .inflate().intVal;
2159 }
2160
2161 // Rounding Modes
2162
2163 /**
2164 * Rounding mode to round away from zero. Always increments the
2165 * digit prior to a nonzero discarded fraction. Note that this rounding
2166 * mode never decreases the magnitude of the calculated value.
2167 */
2168 public final static int ROUND_UP = 0;
2169
2170 /**
2171 * Rounding mode to round towards zero. Never increments the digit
2172 * prior to a discarded fraction (i.e., truncates). Note that this
2173 * rounding mode never increases the magnitude of the calculated value.
2174 */
2175 public final static int ROUND_DOWN = 1;
2176
2177 /**
2178 * Rounding mode to round towards positive infinity. If the
2179 * {@code BigDecimal} is positive, behaves as for
2180 * {@code ROUND_UP}; if negative, behaves as for
2181 * {@code ROUND_DOWN}. Note that this rounding mode never
2182 * decreases the calculated value.
2183 */
2184 public final static int ROUND_CEILING = 2;
2185
2186 /**
2187 * Rounding mode to round towards negative infinity. If the
2188 * {@code BigDecimal} is positive, behave as for
2189 * {@code ROUND_DOWN}; if negative, behave as for
2190 * {@code ROUND_UP}. Note that this rounding mode never
2191 * increases the calculated value.
2192 */
2193 public final static int ROUND_FLOOR = 3;
2194
2195 /**
2196 * Rounding mode to round towards {@literal "nearest neighbor"}
2197 * unless both neighbors are equidistant, in which case round up.
2198 * Behaves as for {@code ROUND_UP} if the discarded fraction is
2199 * ≥ 0.5; otherwise, behaves as for {@code ROUND_DOWN}. Note
2200 * that this is the rounding mode that most of us were taught in
2201 * grade school.
2202 */
2203 public final static int ROUND_HALF_UP = 4;
2204
2205 /**
2206 * Rounding mode to round towards {@literal "nearest neighbor"}
2207 * unless both neighbors are equidistant, in which case round
2208 * down. Behaves as for {@code ROUND_UP} if the discarded
2209 * fraction is {@literal >} 0.5; otherwise, behaves as for
2210 * {@code ROUND_DOWN}.
2211 */
2212 public final static int ROUND_HALF_DOWN = 5;
2213
2214 /**
2215 * Rounding mode to round towards the {@literal "nearest neighbor"}
2216 * unless both neighbors are equidistant, in which case, round
2217 * towards the even neighbor. Behaves as for
2218 * {@code ROUND_HALF_UP} if the digit to the left of the
2219 * discarded fraction is odd; behaves as for
2220 * {@code ROUND_HALF_DOWN} if it's even. Note that this is the
2221 * rounding mode that minimizes cumulative error when applied
2222 * repeatedly over a sequence of calculations.
2223 */
2224 public final static int ROUND_HALF_EVEN = 6;
2225
2226 /**
2227 * Rounding mode to assert that the requested operation has an exact
2228 * result, hence no rounding is necessary. If this rounding mode is
2229 * specified on an operation that yields an inexact result, an
2230 * {@code ArithmeticException} is thrown.
2231 */
2232 public final static int ROUND_UNNECESSARY = 7;
2233
2234 // Scaling/Rounding Operations
2235
2236 /**
2237 * Returns a {@code BigDecimal} rounded according to the
2238 * {@code MathContext} settings. If the precision setting is 0 then
2239 * no rounding takes place.
2240 *
2241 * <p>The effect of this method is identical to that of the
2242 * {@link #plus(MathContext)} method.
2243 *
2244 * @param mc the context to use.
2245 * @return a {@code BigDecimal} rounded according to the
2246 * {@code MathContext} settings.
2247 * @throws ArithmeticException if the rounding mode is
2248 * {@code UNNECESSARY} and the
2249 * {@code BigDecimal} operation would require rounding.
2250 * @see #plus(MathContext)
2251 * @since 1.5
2252 */
2253 public BigDecimal round(MathContext mc) {
2254 return plus(mc);
2255 }
2256
2257 /**
2258 * Returns a {@code BigDecimal} whose scale is the specified
2259 * value, and whose unscaled value is determined by multiplying or
2260 * dividing this {@code BigDecimal}'s unscaled value by the
2261 * appropriate power of ten to maintain its overall value. If the
2262 * scale is reduced by the operation, the unscaled value must be
2263 * divided (rather than multiplied), and the value may be changed;
2264 * in this case, the specified rounding mode is applied to the
2265 * division.
2266 *
2267 * <p>Note that since BigDecimal objects are immutable, calls of
2268 * this method do <i>not</i> result in the original object being
2269 * modified, contrary to the usual convention of having methods
2270 * named <tt>set<i>X</i></tt> mutate field <i>{@code X}</i>.
2271 * Instead, {@code setScale} returns an object with the proper
2272 * scale; the returned object may or may not be newly allocated.
2273 *
2274 * @param newScale scale of the {@code BigDecimal} value to be returned.
2275 * @param roundingMode The rounding mode to apply.
2276 * @return a {@code BigDecimal} whose scale is the specified value,
2277 * and whose unscaled value is determined by multiplying or
2278 * dividing this {@code BigDecimal}'s unscaled value by the
2279 * appropriate power of ten to maintain its overall value.
2280 * @throws ArithmeticException if {@code roundingMode==UNNECESSARY}
2281 * and the specified scaling operation would require
2282 * rounding.
2283 * @see RoundingMode
2284 * @since 1.5
2285 */
2286 public BigDecimal setScale(int newScale, RoundingMode roundingMode) {
2287 return setScale(newScale, roundingMode.oldMode);
2288 }
2289
2290 /**
2291 * Returns a {@code BigDecimal} whose scale is the specified
2292 * value, and whose unscaled value is determined by multiplying or
2293 * dividing this {@code BigDecimal}'s unscaled value by the
2294 * appropriate power of ten to maintain its overall value. If the
2295 * scale is reduced by the operation, the unscaled value must be
2296 * divided (rather than multiplied), and the value may be changed;
2297 * in this case, the specified rounding mode is applied to the
2298 * division.
2299 *
2300 * <p>Note that since BigDecimal objects are immutable, calls of
2301 * this method do <i>not</i> result in the original object being
2302 * modified, contrary to the usual convention of having methods
2303 * named <tt>set<i>X</i></tt> mutate field <i>{@code X}</i>.
2304 * Instead, {@code setScale} returns an object with the proper
2305 * scale; the returned object may or may not be newly allocated.
2306 *
2307 * <p>The new {@link #setScale(int, RoundingMode)} method should
2308 * be used in preference to this legacy method.
2309 *
2310 * @param newScale scale of the {@code BigDecimal} value to be returned.
2311 * @param roundingMode The rounding mode to apply.
2312 * @return a {@code BigDecimal} whose scale is the specified value,
2313 * and whose unscaled value is determined by multiplying or
2314 * dividing this {@code BigDecimal}'s unscaled value by the
2315 * appropriate power of ten to maintain its overall value.
2316 * @throws ArithmeticException if {@code roundingMode==ROUND_UNNECESSARY}
2317 * and the specified scaling operation would require
2318 * rounding.
2319 * @throws IllegalArgumentException if {@code roundingMode} does not
2320 * represent a valid rounding mode.
2321 * @see #ROUND_UP
2322 * @see #ROUND_DOWN
2323 * @see #ROUND_CEILING
2324 * @see #ROUND_FLOOR
2325 * @see #ROUND_HALF_UP
2326 * @see #ROUND_HALF_DOWN
2327 * @see #ROUND_HALF_EVEN
2328 * @see #ROUND_UNNECESSARY
2329 */
2330 public BigDecimal setScale(int newScale, int roundingMode) {
2331 if (roundingMode < ROUND_UP || roundingMode > ROUND_UNNECESSARY)
2332 throw new IllegalArgumentException("Invalid rounding mode");
2333
2334 if (newScale == this .scale) // easy case
2335 return this ;
2336 if (this .signum() == 0) // zero can have any scale
2337 return BigDecimal.valueOf(0, newScale);
2338 if (newScale > this .scale) {
2339 // [we can use checkScale to assure multiplier is valid]
2340 int raise = checkScale((long) newScale - this .scale);
2341
2342 if (intCompact != INFLATED) {
2343 long scaledResult = longTenToThe(intCompact, raise);
2344 if (scaledResult != INFLATED)
2345 return BigDecimal.valueOf(scaledResult, newScale);
2346 this .inflate();
2347 }
2348
2349 BigDecimal result = new BigDecimal(intVal
2350 .multiply(tenToThe(raise)), newScale);
2351 if (this .precision > 0)
2352 result.precision = this .precision + newScale
2353 - this .scale;
2354 return result;
2355 }
2356 // scale < this.scale
2357 // we cannot perfectly predict the precision after rounding
2358 return divide(ONE, newScale, roundingMode);
2359 }
2360
2361 /**
2362 * Returns a {@code BigDecimal} whose scale is the specified
2363 * value, and whose value is numerically equal to this
2364 * {@code BigDecimal}'s. Throws an {@code ArithmeticException}
2365 * if this is not possible.
2366 *
2367 * <p>This call is typically used to increase the scale, in which
2368 * case it is guaranteed that there exists a {@code BigDecimal}
2369 * of the specified scale and the correct value. The call can
2370 * also be used to reduce the scale if the caller knows that the
2371 * {@code BigDecimal} has sufficiently many zeros at the end of
2372 * its fractional part (i.e., factors of ten in its integer value)
2373 * to allow for the rescaling without changing its value.
2374 *
2375 * <p>This method returns the same result as the two-argument
2376 * versions of {@code setScale}, but saves the caller the trouble
2377 * of specifying a rounding mode in cases where it is irrelevant.
2378 *
2379 * <p>Note that since {@code BigDecimal} objects are immutable,
2380 * calls of this method do <i>not</i> result in the original
2381 * object being modified, contrary to the usual convention of
2382 * having methods named <tt>set<i>X</i></tt> mutate field
2383 * <i>{@code X}</i>. Instead, {@code setScale} returns an
2384 * object with the proper scale; the returned object may or may
2385 * not be newly allocated.
2386 *
2387 * @param newScale scale of the {@code BigDecimal} value to be returned.
2388 * @return a {@code BigDecimal} whose scale is the specified value, and
2389 * whose unscaled value is determined by multiplying or dividing
2390 * this {@code BigDecimal}'s unscaled value by the appropriate
2391 * power of ten to maintain its overall value.
2392 * @throws ArithmeticException if the specified scaling operation would
2393 * require rounding.
2394 * @see #setScale(int, int)
2395 * @see #setScale(int, RoundingMode)
2396 */
2397 public BigDecimal setScale(int newScale) {
2398 return setScale(newScale, ROUND_UNNECESSARY);
2399 }
2400
2401 // Decimal Point Motion Operations
2402
2403 /**
2404 * Returns a {@code BigDecimal} which is equivalent to this one
2405 * with the decimal point moved {@code n} places to the left. If
2406 * {@code n} is non-negative, the call merely adds {@code n} to
2407 * the scale. If {@code n} is negative, the call is equivalent
2408 * to {@code movePointRight(-n)}. The {@code BigDecimal}
2409 * returned by this call has value <tt>(this ×
2410 * 10<sup>-n</sup>)</tt> and scale {@code max(this.scale()+n,
2411 * 0)}.
2412 *
2413 * @param n number of places to move the decimal point to the left.
2414 * @return a {@code BigDecimal} which is equivalent to this one with the
2415 * decimal point moved {@code n} places to the left.
2416 * @throws ArithmeticException if scale overflows.
2417 */
2418 public BigDecimal movePointLeft(int n) {
2419 // Cannot use movePointRight(-n) in case of n==Integer.MIN_VALUE
2420 int newScale = checkScale((long) scale + n);
2421 BigDecimal num;
2422 if (intCompact != INFLATED)
2423 num = BigDecimal.valueOf(intCompact, newScale);
2424 else
2425 num = new BigDecimal(intVal, newScale);
2426 return (num.scale < 0 ? num.setScale(0) : num);
2427 }
2428
2429 /**
2430 * Returns a {@code BigDecimal} which is equivalent to this one
2431 * with the decimal point moved {@code n} places to the right.
2432 * If {@code n} is non-negative, the call merely subtracts
2433 * {@code n} from the scale. If {@code n} is negative, the call
2434 * is equivalent to {@code movePointLeft(-n)}. The
2435 * {@code BigDecimal} returned by this call has value <tt>(this
2436 * × 10<sup>n</sup>)</tt> and scale {@code max(this.scale()-n,
2437 * 0)}.
2438 *
2439 * @param n number of places to move the decimal point to the right.
2440 * @return a {@code BigDecimal} which is equivalent to this one
2441 * with the decimal point moved {@code n} places to the right.
2442 * @throws ArithmeticException if scale overflows.
2443 */
2444 public BigDecimal movePointRight(int n) {
2445 // Cannot use movePointLeft(-n) in case of n==Integer.MIN_VALUE
2446 int newScale = checkScale((long) scale - n);
2447 BigDecimal num;
2448 if (intCompact != INFLATED)
2449 num = BigDecimal.valueOf(intCompact, newScale);
2450 else
2451 num = new BigDecimal(intVal, newScale);
2452 return (num.scale < 0 ? num.setScale(0) : num);
2453 }
2454
2455 /**
2456 * Returns a BigDecimal whose numerical value is equal to
2457 * ({@code this} * 10<sup>n</sup>). The scale of
2458 * the result is {@code (this.scale() - n)}.
2459 *
2460 * @throws ArithmeticException if the scale would be
2461 * outside the range of a 32-bit integer.
2462 *
2463 * @since 1.5
2464 */
2465 public BigDecimal scaleByPowerOfTen(int n) {
2466 this .inflate();
2467 BigDecimal num = new BigDecimal(intVal, checkScale((long) scale
2468 - n));
2469 num.precision = precision;
2470 return num;
2471 }
2472
2473 /**
2474 * Returns a {@code BigDecimal} which is numerically equal to
2475 * this one but with any trailing zeros removed from the
2476 * representation. For example, stripping the trailing zeros from
2477 * the {@code BigDecimal} value {@code 600.0}, which has
2478 * [{@code BigInteger}, {@code scale}] components equals to
2479 * [6000, 1], yields {@code 6E2} with [{@code BigInteger},
2480 * {@code scale}] components equals to [6, -2]
2481 *
2482 * @return a numerically equal {@code BigDecimal} with any
2483 * trailing zeros removed.
2484 * @since 1.5
2485 */
2486 public BigDecimal stripTrailingZeros() {
2487 this .inflate();
2488 return (new BigDecimal(intVal, scale))
2489 .stripZerosToMatchScale(Long.MIN_VALUE);
2490 }
2491
2492 // Comparison Operations
2493
2494 /**
2495 * Compares this {@code BigDecimal} with the specified
2496 * {@code BigDecimal}. Two {@code BigDecimal} objects that are
2497 * equal in value but have a different scale (like 2.0 and 2.00)
2498 * are considered equal by this method. This method is provided
2499 * in preference to individual methods for each of the six boolean
2500 * comparison operators ({@literal <}, ==,
2501 * {@literal >}, {@literal >=}, !=, {@literal <=}). The
2502 * suggested idiom for performing these comparisons is:
2503 * {@code (x.compareTo(y)} <<i>op</i>> {@code 0)}, where
2504 * <<i>op</i>> is one of the six comparison operators.
2505 *
2506 * @param val {@code BigDecimal} to which this {@code BigDecimal} is
2507 * to be compared.
2508 * @return -1, 0, or 1 as this {@code BigDecimal} is numerically
2509 * less than, equal to, or greater than {@code val}.
2510 */
2511 public int compareTo(BigDecimal val) {
2512 if (this .scale == val.scale && this .intCompact != INFLATED
2513 && val.intCompact != INFLATED)
2514 return longCompareTo(this .intCompact, val.intCompact);
2515
2516 // Optimization: would run fine without the next three lines
2517 int sigDiff = signum() - val.signum();
2518 if (sigDiff != 0)
2519 return (sigDiff > 0 ? 1 : -1);
2520
2521 // If the (adjusted) exponents are different we do not need to
2522 // expensively match scales and compare the significands
2523 int aethis = this .precision() - this .scale; // [-1]
2524 int aeval = val.precision() - val.scale; // [-1]
2525 if (aethis < aeval)
2526 return -this .signum();
2527 else if (aethis > aeval)
2528 return this .signum();
2529
2530 // Scale and compare intVals
2531 BigDecimal arg[] = { this , val };
2532 matchScale(arg);
2533 if (arg[0].intCompact != INFLATED
2534 && arg[1].intCompact != INFLATED)
2535 return longCompareTo(arg[0].intCompact, arg[1].intCompact);
2536 return arg[0].inflate().intVal
2537 .compareTo(arg[1].inflate().intVal);
2538 }
2539
2540 /**
2541 * Compares this {@code BigDecimal} with the specified
2542 * {@code Object} for equality. Unlike {@link
2543 * #compareTo(BigDecimal) compareTo}, this method considers two
2544 * {@code BigDecimal} objects equal only if they are equal in
2545 * value and scale (thus 2.0 is not equal to 2.00 when compared by
2546 * this method).
2547 *
2548 * @param x {@code Object} to which this {@code BigDecimal} is
2549 * to be compared.
2550 * @return {@code true} if and only if the specified {@code Object} is a
2551 * {@code BigDecimal} whose value and scale are equal to this
2552 * {@code BigDecimal}'s.
2553 * @see #compareTo(java.math.BigDecimal)
2554 * @see #hashCode
2555 */
2556 public boolean equals(Object x) {
2557 if (!(x instanceof BigDecimal))
2558 return false;
2559 BigDecimal xDec = (BigDecimal) x;
2560 if (scale != xDec.scale)
2561 return false;
2562 if (this .intCompact != INFLATED && xDec.intCompact != INFLATED)
2563 return this .intCompact == xDec.intCompact;
2564 return this .inflate().intVal.equals(xDec.inflate().intVal);
2565 }
2566
2567 /**
2568 * Returns the minimum of this {@code BigDecimal} and
2569 * {@code val}.
2570 *
2571 * @param val value with which the minimum is to be computed.
2572 * @return the {@code BigDecimal} whose value is the lesser of this
2573 * {@code BigDecimal} and {@code val}. If they are equal,
2574 * as defined by the {@link #compareTo(BigDecimal) compareTo}
2575 * method, {@code this} is returned.
2576 * @see #compareTo(java.math.BigDecimal)
2577 */
2578 public BigDecimal min(BigDecimal val) {
2579 return (compareTo(val) <= 0 ? this : val);
2580 }
2581
2582 /**
2583 * Returns the maximum of this {@code BigDecimal} and {@code val}.
2584 *
2585 * @param val value with which the maximum is to be computed.
2586 * @return the {@code BigDecimal} whose value is the greater of this
2587 * {@code BigDecimal} and {@code val}. If they are equal,
2588 * as defined by the {@link #compareTo(BigDecimal) compareTo}
2589 * method, {@code this} is returned.
2590 * @see #compareTo(java.math.BigDecimal)
2591 */
2592 public BigDecimal max(BigDecimal val) {
2593 return (compareTo(val) >= 0 ? this : val);
2594 }
2595
2596 // Hash Function
2597
2598 /**
2599 * Returns the hash code for this {@code BigDecimal}. Note that
2600 * two {@code BigDecimal} objects that are numerically equal but
2601 * differ in scale (like 2.0 and 2.00) will generally <i>not</i>
2602 * have the same hash code.
2603 *
2604 * @return hash code for this {@code BigDecimal}.
2605 * @see #equals(Object)
2606 */
2607 public int hashCode() {
2608 if (intCompact != INFLATED) {
2609 long val2 = (intCompact < 0) ? -intCompact : intCompact;
2610 int temp = (int) (((int) (val2 >>> 32)) * 31 + (val2 & 0xffffffffL));
2611 return 31 * ((intCompact < 0) ? -temp : temp) + scale;
2612 } else
2613 return 31 * intVal.hashCode() + scale;
2614 }
2615
2616 // Format Converters
2617
2618 /**
2619 * Returns the string representation of this {@code BigDecimal},
2620 * using scientific notation if an exponent is needed.
2621 *
2622 * <p>A standard canonical string form of the {@code BigDecimal}
2623 * is created as though by the following steps: first, the
2624 * absolute value of the unscaled value of the {@code BigDecimal}
2625 * is converted to a string in base ten using the characters
2626 * {@code '0'} through {@code '9'} with no leading zeros (except
2627 * if its value is zero, in which case a single {@code '0'}
2628 * character is used).
2629 *
2630 * <p>Next, an <i>adjusted exponent</i> is calculated; this is the
2631 * negated scale, plus the number of characters in the converted
2632 * unscaled value, less one. That is,
2633 * {@code -scale+(ulength-1)}, where {@code ulength} is the
2634 * length of the absolute value of the unscaled value in decimal
2635 * digits (its <i>precision</i>).
2636 *
2637 * <p>If the scale is greater than or equal to zero and the
2638 * adjusted exponent is greater than or equal to {@code -6}, the
2639 * number will be converted to a character form without using
2640 * exponential notation. In this case, if the scale is zero then
2641 * no decimal point is added and if the scale is positive a
2642 * decimal point will be inserted with the scale specifying the
2643 * number of characters to the right of the decimal point.
2644 * {@code '0'} characters are added to the left of the converted
2645 * unscaled value as necessary. If no character precedes the
2646 * decimal point after this insertion then a conventional
2647 * {@code '0'} character is prefixed.
2648 *
2649 * <p>Otherwise (that is, if the scale is negative, or the
2650 * adjusted exponent is less than {@code -6}), the number will be
2651 * converted to a character form using exponential notation. In
2652 * this case, if the converted {@code BigInteger} has more than
2653 * one digit a decimal point is inserted after the first digit.
2654 * An exponent in character form is then suffixed to the converted
2655 * unscaled value (perhaps with inserted decimal point); this
2656 * comprises the letter {@code 'E'} followed immediately by the
2657 * adjusted exponent converted to a character form. The latter is
2658 * in base ten, using the characters {@code '0'} through
2659 * {@code '9'} with no leading zeros, and is always prefixed by a
2660 * sign character {@code '-'} (<tt>'\u002D'</tt>) if the
2661 * adjusted exponent is negative, {@code '+'}
2662 * (<tt>'\u002B'</tt>) otherwise).
2663 *
2664 * <p>Finally, the entire string is prefixed by a minus sign
2665 * character {@code '-'} (<tt>'\u002D'</tt>) if the unscaled
2666 * value is less than zero. No sign character is prefixed if the
2667 * unscaled value is zero or positive.
2668 *
2669 * <p><b>Examples:</b>
2670 * <p>For each representation [<i>unscaled value</i>, <i>scale</i>]
2671 * on the left, the resulting string is shown on the right.
2672 * <pre>
2673 * [123,0] "123"
2674 * [-123,0] "-123"
2675 * [123,-1] "1.23E+3"
2676 * [123,-3] "1.23E+5"
2677 * [123,1] "12.3"
2678 * [123,5] "0.00123"
2679 * [123,10] "1.23E-8"
2680 * [-123,12] "-1.23E-10"
2681 * </pre>
2682 *
2683 * <b>Notes:</b>
2684 * <ol>
2685 *
2686 * <li>There is a one-to-one mapping between the distinguishable
2687 * {@code BigDecimal} values and the result of this conversion.
2688 * That is, every distinguishable {@code BigDecimal} value
2689 * (unscaled value and scale) has a unique string representation
2690 * as a result of using {@code toString}. If that string
2691 * representation is converted back to a {@code BigDecimal} using
2692 * the {@link #BigDecimal(String)} constructor, then the original
2693 * value will be recovered.
2694 *
2695 * <li>The string produced for a given number is always the same;
2696 * it is not affected by locale. This means that it can be used
2697 * as a canonical string representation for exchanging decimal
2698 * data, or as a key for a Hashtable, etc. Locale-sensitive
2699 * number formatting and parsing is handled by the {@link
2700 * java.text.NumberFormat} class and its subclasses.
2701 *
2702 * <li>The {@link #toEngineeringString} method may be used for
2703 * presenting numbers with exponents in engineering notation, and the
2704 * {@link #setScale(int,RoundingMode) setScale} method may be used for
2705 * rounding a {@code BigDecimal} so it has a known number of digits after
2706 * the decimal point.
2707 *
2708 * <li>The digit-to-character mapping provided by
2709 * {@code Character.forDigit} is used.
2710 *
2711 * </ol>
2712 *
2713 * @return string representation of this {@code BigDecimal}.
2714 * @see Character#forDigit
2715 * @see #BigDecimal(java.lang.String)
2716 */
2717 public String toString() {
2718 if (stringCache == null)
2719 stringCache = layoutChars(true);
2720 return stringCache;
2721 }
2722
2723 /**
2724 * Returns a string representation of this {@code BigDecimal},
2725 * using engineering notation if an exponent is needed.
2726 *
2727 * <p>Returns a string that represents the {@code BigDecimal} as
2728 * described in the {@link #toString()} method, except that if
2729 * exponential notation is used, the power of ten is adjusted to
2730 * be a multiple of three (engineering notation) such that the
2731 * integer part of nonzero values will be in the range 1 through
2732 * 999. If exponential notation is used for zero values, a
2733 * decimal point and one or two fractional zero digits are used so
2734 * that the scale of the zero value is preserved. Note that
2735 * unlike the output of {@link #toString()}, the output of this
2736 * method is <em>not</em> guaranteed to recover the same [integer,
2737 * scale] pair of this {@code BigDecimal} if the output string is
2738 * converting back to a {@code BigDecimal} using the {@linkplain
2739 * #BigDecimal(String) string constructor}. The result of this method meets
2740 * the weaker constraint of always producing a numerically equal
2741 * result from applying the string constructor to the method's output.
2742 *
2743 * @return string representation of this {@code BigDecimal}, using
2744 * engineering notation if an exponent is needed.
2745 * @since 1.5
2746 */
2747 public String toEngineeringString() {
2748 return layoutChars(false);
2749 }
2750
2751 /**
2752 * Returns a string representation of this {@code BigDecimal}
2753 * without an exponent field. For values with a positive scale,
2754 * the number of digits to the right of the decimal point is used
2755 * to indicate scale. For values with a zero or negative scale,
2756 * the resulting string is generated as if the value were
2757 * converted to a numerically equal value with zero scale and as
2758 * if all the trailing zeros of the zero scale value were present
2759 * in the result.
2760 *
2761 * The entire string is prefixed by a minus sign character '-'
2762 * (<tt>'\u002D'</tt>) if the unscaled value is less than
2763 * zero. No sign character is prefixed if the unscaled value is
2764 * zero or positive.
2765 *
2766 * Note that if the result of this method is passed to the
2767 * {@linkplain #BigDecimal(String) string constructor}, only the
2768 * numerical value of this {@code BigDecimal} will necessarily be
2769 * recovered; the representation of the new {@code BigDecimal}
2770 * may have a different scale. In particular, if this
2771 * {@code BigDecimal} has a negative scale, the string resulting
2772 * from this method will have a scale of zero when processed by
2773 * the string constructor.
2774 *
2775 * (This method behaves analogously to the {@code toString}
2776 * method in 1.4 and earlier releases.)
2777 *
2778 * @return a string representation of this {@code BigDecimal}
2779 * without an exponent field.
2780 * @since 1.5
2781 * @see #toString()
2782 * @see #toEngineeringString()
2783 */
2784 public String toPlainString() {
2785 BigDecimal bd = this ;
2786 if (bd.scale < 0)
2787 bd = bd.setScale(0);
2788 bd.inflate();
2789 if (bd.scale == 0) // No decimal point
2790 return bd.intVal.toString();
2791 return bd.getValueString(bd.signum(), bd.intVal.abs()
2792 .toString(), bd.scale);
2793 }
2794
2795 /* Returns a digit.digit string */
2796 private String getValueString(int signum, String intString,
2797 int scale) {
2798 /* Insert decimal point */
2799 StringBuilder buf;
2800 int insertionPoint = intString.length() - scale;
2801 if (insertionPoint == 0) { /* Point goes right before intVal */
2802 return (signum < 0 ? "-0." : "0.") + intString;
2803 } else if (insertionPoint > 0) { /* Point goes inside intVal */
2804 buf = new StringBuilder(intString);
2805 buf.insert(insertionPoint, '.');
2806 if (signum < 0)
2807 buf.insert(0, '-');
2808 } else { /* We must insert zeros between point and intVal */
2809 buf = new StringBuilder(3 - insertionPoint
2810 + intString.length());
2811 buf.append(signum < 0 ? "-0." : "0.");
2812 for (int i = 0; i < -insertionPoint; i++)
2813 buf.append('0');
2814 buf.append(intString);
2815 }
2816 return buf.toString();
2817 }
2818
2819 /**
2820 * Converts this {@code BigDecimal} to a {@code BigInteger}.
2821 * This conversion is analogous to a <a
2822 * href="http://java.sun.com/docs/books/jls/second_edition/html/conversions.doc.html#25363"><i>narrowing
2823 * primitive conversion</i></a> from {@code double} to
2824 * {@code long} as defined in the <a
2825 * href="http://java.sun.com/docs/books/jls/html/">Java Language
2826 * Specification</a>: any fractional part of this
2827 * {@code BigDecimal} will be discarded. Note that this
2828 * conversion can lose information about the precision of the
2829 * {@code BigDecimal} value.
2830 * <p>
2831 * To have an exception thrown if the conversion is inexact (in
2832 * other words if a nonzero fractional part is discarded), use the
2833 * {@link #toBigIntegerExact()} method.
2834 *
2835 * @return this {@code BigDecimal} converted to a {@code BigInteger}.
2836 */
2837 public BigInteger toBigInteger() {
2838 // force to an integer, quietly
2839 return this .setScale(0, ROUND_DOWN).inflate().intVal;
2840 }
2841
2842 /**
2843 * Converts this {@code BigDecimal} to a {@code BigInteger},
2844 * checking for lost information. An exception is thrown if this
2845 * {@code BigDecimal} has a nonzero fractional part.
2846 *
2847 * @return this {@code BigDecimal} converted to a {@code BigInteger}.
2848 * @throws ArithmeticException if {@code this} has a nonzero
2849 * fractional part.
2850 * @since 1.5
2851 */
2852 public BigInteger toBigIntegerExact() {
2853 // round to an integer, with Exception if decimal part non-0
2854 return this .setScale(0, ROUND_UNNECESSARY).inflate().intVal;
2855 }
2856
2857 /**
2858 * Converts this {@code BigDecimal} to a {@code long}. This
2859 * conversion is analogous to a <a
2860 * href="http://java.sun.com/docs/books/jls/second_edition/html/conversions.doc.html#25363"><i>narrowing
2861 * primitive conversion</i></a> from {@code double} to
2862 * {@code short} as defined in the <a
2863 * href="http://java.sun.com/docs/books/jls/html/">Java Language
2864 * Specification</a>: any fractional part of this
2865 * {@code BigDecimal} will be discarded, and if the resulting
2866 * "{@code BigInteger}" is too big to fit in a
2867 * {@code long}, only the low-order 64 bits are returned.
2868 * Note that this conversion can lose information about the
2869 * overall magnitude and precision of this {@code BigDecimal} value as well
2870 * as return a result with the opposite sign.
2871 *
2872 * @return this {@code BigDecimal} converted to a {@code long}.
2873 */
2874 public long longValue() {
2875 return (intCompact != INFLATED && scale == 0) ? intCompact
2876 : toBigInteger().longValue();
2877 }
2878
2879 /**
2880 * Converts this {@code BigDecimal} to a {@code long}, checking
2881 * for lost information. If this {@code BigDecimal} has a
2882 * nonzero fractional part or is out of the possible range for a
2883 * {@code long} result then an {@code ArithmeticException} is
2884 * thrown.
2885 *
2886 * @return this {@code BigDecimal} converted to a {@code long}.
2887 * @throws ArithmeticException if {@code this} has a nonzero
2888 * fractional part, or will not fit in a {@code long}.
2889 * @since 1.5
2890 */
2891 public long longValueExact() {
2892 if (intCompact != INFLATED && scale == 0)
2893 return intCompact;
2894 // If more than 19 digits in integer part it cannot possibly fit
2895 if ((precision() - scale) > 19) // [OK for negative scale too]
2896 throw new java.lang.ArithmeticException("Overflow");
2897 // Fastpath zero and < 1.0 numbers (the latter can be very slow
2898 // to round if very small)
2899 if (this .signum() == 0)
2900 return 0;
2901 if ((this .precision() - this .scale) <= 0)
2902 throw new ArithmeticException("Rounding necessary");
2903 // round to an integer, with Exception if decimal part non-0
2904 BigDecimal num = this .setScale(0, ROUND_UNNECESSARY).inflate();
2905 if (num.precision() >= 19) // need to check carefully
2906 LongOverflow.check(num);
2907 return num.intVal.longValue();
2908 }
2909
2910 private static class LongOverflow {
2911 /** BigInteger equal to Long.MIN_VALUE. */
2912 private static final BigInteger LONGMIN = BigInteger
2913 .valueOf(Long.MIN_VALUE);
2914
2915 /** BigInteger equal to Long.MAX_VALUE. */
2916 private static final BigInteger LONGMAX = BigInteger
2917 .valueOf(Long.MAX_VALUE);
2918
2919 public static void check(BigDecimal num) {
2920 if ((num.intVal.compareTo(LONGMIN) < 0)
2921 || (num.intVal.compareTo(LONGMAX) > 0))
2922 throw new java.lang.ArithmeticException("Overflow");
2923 }
2924 }
2925
2926 /**
2927 * Converts this {@code BigDecimal} to an {@code int}. This
2928 * conversion is analogous to a <a
2929 * href="http://java.sun.com/docs/books/jls/second_edition/html/conversions.doc.html#25363"><i>narrowing
2930 * primitive conversion</i></a> from {@code double} to
2931 * {@code short} as defined in the <a
2932 * href="http://java.sun.com/docs/books/jls/html/">Java Language
2933 * Specification</a>: any fractional part of this
2934 * {@code BigDecimal} will be discarded, and if the resulting
2935 * "{@code BigInteger}" is too big to fit in an
2936 * {@code int}, only the low-order 32 bits are returned.
2937 * Note that this conversion can lose information about the
2938 * overall magnitude and precision of this {@code BigDecimal}
2939 * value as well as return a result with the opposite sign.
2940 *
2941 * @return this {@code BigDecimal} converted to an {@code int}.
2942 */
2943 public int intValue() {
2944 return (intCompact != INFLATED && scale == 0) ? (int) intCompact
2945 : toBigInteger().intValue();
2946 }
2947
2948 /**
2949 * Converts this {@code BigDecimal} to an {@code int}, checking
2950 * for lost information. If this {@code BigDecimal} has a
2951 * nonzero fractional part or is out of the possible range for an
2952 * {@code int} result then an {@code ArithmeticException} is
2953 * thrown.
2954 *
2955 * @return this {@code BigDecimal} converted to an {@code int}.
2956 * @throws ArithmeticException if {@code this} has a nonzero
2957 * fractional part, or will not fit in an {@code int}.
2958 * @since 1.5
2959 */
2960 public int intValueExact() {
2961 long num;
2962 num = this .longValueExact(); // will check decimal part
2963 if ((int) num != num)
2964 throw new java.lang.ArithmeticException("Overflow");
2965 return (int) num;
2966 }
2967
2968 /**
2969 * Converts this {@code BigDecimal} to a {@code short}, checking
2970 * for lost information. If this {@code BigDecimal} has a
2971 * nonzero fractional part or is out of the possible range for a
2972 * {@code short} result then an {@code ArithmeticException} is
2973 * thrown.
2974 *
2975 * @return this {@code BigDecimal} converted to a {@code short}.
2976 * @throws ArithmeticException if {@code this} has a nonzero
2977 * fractional part, or will not fit in a {@code short}.
2978 * @since 1.5
2979 */
2980 public short shortValueExact() {
2981 long num;
2982 num = this .longValueExact(); // will check decimal part
2983 if ((short) num != num)
2984 throw new java.lang.ArithmeticException("Overflow");
2985 return (short) num;
2986 }
2987
2988 /**
2989 * Converts this {@code BigDecimal} to a {@code byte}, checking
2990 * for lost information. If this {@code BigDecimal} has a
2991 * nonzero fractional part or is out of the possible range for a
2992 * {@code byte} result then an {@code ArithmeticException} is
2993 * thrown.
2994 *
2995 * @return this {@code BigDecimal} converted to a {@code byte}.
2996 * @throws ArithmeticException if {@code this} has a nonzero
2997 * fractional part, or will not fit in a {@code byte}.
2998 * @since 1.5
2999 */
3000 public byte byteValueExact() {
3001 long num;
3002 num = this .longValueExact(); // will check decimal part
3003 if ((byte) num != num)
3004 throw new java.lang.ArithmeticException("Overflow");
3005 return (byte) num;
3006 }
3007
3008 /**
3009 * Converts this {@code BigDecimal} to a {@code float}.
3010 * This conversion is similar to the <a
3011 * href="http://java.sun.com/docs/books/jls/second_edition/html/conversions.doc.html#25363"><i>narrowing
3012 * primitive conversion</i></a> from {@code double} to
3013 * {@code float} defined in the <a
3014 * href="http://java.sun.com/docs/books/jls/html/">Java Language
3015 * Specification</a>: if this {@code BigDecimal} has too great a
3016 * magnitude to represent as a {@code float}, it will be
3017 * converted to {@link Float#NEGATIVE_INFINITY} or {@link
3018 * Float#POSITIVE_INFINITY} as appropriate. Note that even when
3019 * the return value is finite, this conversion can lose
3020 * information about the precision of the {@code BigDecimal}
3021 * value.
3022 *
3023 * @return this {@code BigDecimal} converted to a {@code float}.
3024 */
3025 public float floatValue() {
3026 if (scale == 0 && intCompact != INFLATED)
3027 return (float) intCompact;
3028 // Somewhat inefficient, but guaranteed to work.
3029 return Float.parseFloat(this .toString());
3030 }
3031
3032 /**
3033 * Converts this {@code BigDecimal} to a {@code double}.
3034 * This conversion is similar to the <a
3035 * href="http://java.sun.com/docs/books/jls/second_edition/html/conversions.doc.html#25363"><i>narrowing
3036 * primitive conversion</i></a> from {@code double} to
3037 * {@code float} as defined in the <a
3038 * href="http://java.sun.com/docs/books/jls/html/">Java Language
3039 * Specification</a>: if this {@code BigDecimal} has too great a
3040 * magnitude represent as a {@code double}, it will be
3041 * converted to {@link Double#NEGATIVE_INFINITY} or {@link
3042 * Double#POSITIVE_INFINITY} as appropriate. Note that even when
3043 * the return value is finite, this conversion can lose
3044 * information about the precision of the {@code BigDecimal}
3045 * value.
3046 *
3047 * @return this {@code BigDecimal} converted to a {@code double}.
3048 */
3049 public double doubleValue() {
3050 if (scale == 0 && intCompact != INFLATED)
3051 return (double) intCompact;
3052 // Somewhat inefficient, but guaranteed to work.
3053 return Double.parseDouble(this .toString());
3054 }
3055
3056 /**
3057 * Returns the size of an ulp, a unit in the last place, of this
3058 * {@code BigDecimal}. An ulp of a nonzero {@code BigDecimal}
3059 * value is the positive distance between this value and the
3060 * {@code BigDecimal} value next larger in magnitude with the
3061 * same number of digits. An ulp of a zero value is numerically
3062 * equal to 1 with the scale of {@code this}. The result is
3063 * stored with the same scale as {@code this} so the result
3064 * for zero and nonzero values is equal to {@code [1,
3065 * this.scale()]}.
3066 *
3067 * @return the size of an ulp of {@code this}
3068 * @since 1.5
3069 */
3070 public BigDecimal ulp() {
3071 return BigDecimal.valueOf(1, this .scale());
3072 }
3073
3074 // Private "Helper" Methods
3075
3076 /**
3077 * Lay out this {@code BigDecimal} into a {@code char[]} array.
3078 * The Java 1.2 equivalent to this was called {@code getValueString}.
3079 *
3080 * @param sci {@code true} for Scientific exponential notation;
3081 * {@code false} for Engineering
3082 * @return string with canonical string representation of this
3083 * {@code BigDecimal}
3084 */
3085 private String layoutChars(boolean sci) {
3086 if (scale == 0) // zero scale is trivial
3087 return (intCompact != INFLATED) ? Long.toString(intCompact)
3088 : intVal.toString();
3089
3090 // Get the significand as an absolute value
3091 char coeff[];
3092 if (intCompact != INFLATED)
3093 coeff = Long.toString(Math.abs(intCompact)).toCharArray();
3094 else
3095 coeff = intVal.abs().toString().toCharArray();
3096
3097 // Construct a buffer, with sufficient capacity for all cases.
3098 // If E-notation is needed, length will be: +1 if negative, +1
3099 // if '.' needed, +2 for "E+", + up to 10 for adjusted exponent.
3100 // Otherwise it could have +1 if negative, plus leading "0.00000"
3101 StringBuilder buf = new StringBuilder(coeff.length + 14);
3102 if (signum() < 0) // prefix '-' if negative
3103 buf.append('-');
3104 long adjusted = -(long) scale + (coeff.length - 1);
3105 if ((scale >= 0) && (adjusted >= -6)) { // plain number
3106 int pad = scale - coeff.length; // count of padding zeros
3107 if (pad >= 0) { // 0.xxx form
3108 buf.append('0');
3109 buf.append('.');
3110 for (; pad > 0; pad--) {
3111 buf.append('0');
3112 }
3113 buf.append(coeff);
3114 } else { // xx.xx form
3115 buf.append(coeff, 0, -pad);
3116 buf.append('.');
3117 buf.append(coeff, -pad, scale);
3118 }
3119 } else { // E-notation is needed
3120 if (sci) { // Scientific notation
3121 buf.append(coeff[0]); // first character
3122 if (coeff.length > 1) { // more to come
3123 buf.append('.');
3124 buf.append(coeff, 1, coeff.length - 1);
3125 }
3126 } else { // Engineering notation
3127 int sig = (int) (adjusted % 3);
3128 if (sig < 0)
3129 sig += 3; // [adjusted was negative]
3130 adjusted -= sig; // now a multiple of 3
3131 sig++;
3132 if (signum() == 0) {
3133 switch (sig) {
3134 case 1:
3135 buf.append('0'); // exponent is a multiple of three
3136 break;
3137 case 2:
3138 buf.append("0.00");
3139 adjusted += 3;
3140 break;
3141 case 3:
3142 buf.append("0.0");
3143 adjusted += 3;
3144 break;
3145 default:
3146 throw new AssertionError(
3147 "Unexpected sig value " + sig);
3148 }
3149 } else if (sig >= coeff.length) { // significand all in integer
3150 buf.append(coeff, 0, coeff.length);
3151 // may need some zeros, too
3152 for (int i = sig - coeff.length; i > 0; i--)
3153 buf.append('0');
3154 } else { // xx.xxE form
3155 buf.append(coeff, 0, sig);
3156 buf.append('.');
3157 buf.append(coeff, sig, coeff.length - sig);
3158 }
3159 }
3160 if (adjusted != 0) { // [!sci could have made 0]
3161 buf.append('E');
3162 if (adjusted > 0) // force sign for positive
3163 buf.append('+');
3164 buf.append(adjusted);
3165 }
3166 }
3167 return buf.toString();
3168 }
3169
3170 /**
3171 * Return 10 to the power n, as a {@code BigInteger}.
3172 *
3173 * @param n the power of ten to be returned (>=0)
3174 * @return a {@code BigInteger} with the value (10<sup>n</sup>)
3175 */
3176 private static BigInteger tenToThe(int n) {
3177 if (n < TENPOWERS.length) // use value from constant array
3178 return TENPOWERS[n];
3179 // BigInteger.pow is slow, so make 10**n by constructing a
3180 // BigInteger from a character string (still not very fast)
3181 char tenpow[] = new char[n + 1];
3182 tenpow[0] = '1';
3183 for (int i = 1; i <= n; i++)
3184 tenpow[i] = '0';
3185 return new BigInteger(tenpow);
3186 }
3187
3188 private static BigInteger TENPOWERS[] = { BigInteger.ONE,
3189 BigInteger.valueOf(10), BigInteger.valueOf(100),
3190 BigInteger.valueOf(1000), BigInteger.valueOf(10000),
3191 BigInteger.valueOf(100000), BigInteger.valueOf(1000000),
3192 BigInteger.valueOf(10000000),
3193 BigInteger.valueOf(100000000),
3194 BigInteger.valueOf(1000000000) };
3195
3196 /**
3197 * Compute val * 10 ^ n; return this product if it is
3198 * representable as a long, INFLATED otherwise.
3199 */
3200 private static long longTenToThe(long val, int n) {
3201 // System.err.print("\tval " + val + "\t power " + n + "\tresult ");
3202 if (n >= 0 && n < thresholds.length) {
3203 if (Math.abs(val) <= thresholds[n][0]) {
3204 // System.err.println(val * thresholds[n][1]);
3205 return val * thresholds[n][1];
3206 }
3207 }
3208 // System.err.println(INFLATED);
3209 return INFLATED;
3210 }
3211
3212 private static long thresholds[][] = { { Long.MAX_VALUE, 1L }, // 0
3213 { Long.MAX_VALUE / 10L, 10L }, // 1
3214 { Long.MAX_VALUE / 100L, 100L }, // 2
3215 { Long.MAX_VALUE / 1000L, 1000L }, // 3
3216 { Long.MAX_VALUE / 10000L, 10000L }, // 4
3217 { Long.MAX_VALUE / 100000L, 100000L }, // 5
3218 { Long.MAX_VALUE / 1000000L, 1000000L }, // 6
3219 { Long.MAX_VALUE / 10000000L, 10000000L }, // 7
3220 { Long.MAX_VALUE / 100000000L, 100000000L }, // 8
3221 { Long.MAX_VALUE / 1000000000L, 1000000000L }, // 9
3222 { Long.MAX_VALUE / 10000000000L, 10000000000L }, // 10
3223 { Long.MAX_VALUE / 100000000000L, 100000000000L }, // 11
3224 { Long.MAX_VALUE / 1000000000000L, 1000000000000L },// 12
3225 { Long.MAX_VALUE / 100000000000000L, 10000000000000L },// 13
3226 };
3227
3228 private static boolean compactLong(long val) {
3229 return (val != Long.MIN_VALUE);
3230 }
3231
3232 /**
3233 * Assign appropriate BigInteger to intVal field if intVal is
3234 * null, i.e. the compact representation is in use.
3235 */
3236 private BigDecimal inflate() {
3237 if (intVal == null)
3238 intVal = BigInteger.valueOf(intCompact);
3239 return this ;
3240 }
3241
3242 /**
3243 * Match the scales of two {@code BigDecimal}s to align their
3244 * least significant digits.
3245 *
3246 * <p>If the scales of val[0] and val[1] differ, rescale
3247 * (non-destructively) the lower-scaled {@code BigDecimal} so
3248 * they match. That is, the lower-scaled reference will be
3249 * replaced by a reference to a new object with the same scale as
3250 * the other {@code BigDecimal}.
3251 *
3252 * @param val array of two elements referring to the two
3253 * {@code BigDecimal}s to be aligned.
3254 */
3255 private static void matchScale(BigDecimal[] val) {
3256 if (val[0].scale < val[1].scale)
3257 val[0] = val[0].setScale(val[1].scale);
3258 else if (val[1].scale < val[0].scale)
3259 val[1] = val[1].setScale(val[0].scale);
3260 }
3261
3262 /**
3263 * Reconstitute the {@code BigDecimal} instance from a stream (that is,
3264 * deserialize it).
3265 *
3266 * @param s the stream being read.
3267 */
3268 private void readObject(java.io.ObjectInputStream s)
3269 throws java.io.IOException, ClassNotFoundException {
3270 // Read in all fields
3271 s.defaultReadObject();
3272 // validate possibly bad fields
3273 if (intVal == null) {
3274 String message = "BigDecimal: null intVal in stream";
3275 throw new java.io.StreamCorruptedException(message);
3276 // [all values of scale are now allowed]
3277 }
3278 // Set intCompact to uninitialized value; could also see if the
3279 // intVal was small enough to fit as a compact value.
3280 intCompact = INFLATED;
3281 }
3282
3283 /**
3284 * Serialize this {@code BigDecimal} to the stream in question
3285 *
3286 * @param s the stream to serialize to.
3287 */
3288 private void writeObject(java.io.ObjectOutputStream s)
3289 throws java.io.IOException {
3290 // Must inflate to maintain compatible serial form.
3291 this .inflate();
3292
3293 // Write proper fields
3294 s.defaultWriteObject();
3295 }
3296
3297 /**
3298 * Returns the length of this {@code BigDecimal}, in decimal digits.
3299 *
3300 * Notes:
3301 *<ul>
3302 * <li> This is performance-critical; most operations where a
3303 * context is supplied will need at least one call to this
3304 * method.
3305 *
3306 * <li> This should be a method on BigInteger; the call to this
3307 * method in precision() can then be replaced with the
3308 * term: intVal.digitLength(). It could also be called
3309 * precision() in BigInteger.
3310 *
3311 * Better still -- the precision lookaside could be moved to
3312 * BigInteger, too.
3313 *
3314 * <li> This could/should use MutableBigIntegers directly for the
3315 * reduction loop.
3316 *<ul>
3317 * @return the length of the unscaled value, in decimal digits
3318 */
3319 private int digitLength() {
3320 if (intCompact != INFLATED
3321 && Math.abs(intCompact) <= Integer.MAX_VALUE)
3322 return intLength(Math.abs((int) intCompact));
3323 if (signum() == 0) // 0 is one decimal digit
3324 return 1;
3325 this .inflate();
3326 // we have a nonzero magnitude
3327 BigInteger work = intVal;
3328 int digits = 0; // counter
3329 for (; work.mag.length > 1;) {
3330 // here when more than one integer in the magnitude; divide
3331 // by a billion (reduce by 9 digits) and try again
3332 work = work.divide(TENPOWERS[9]);
3333 digits += 9;
3334 if (work.signum() == 0) // the division was exact
3335 return digits; // (a power of a billion)
3336 }
3337 // down to a simple nonzero integer
3338 digits += intLength(work.mag[0]);
3339 // System.out.println("digitLength... "+this+" -> "+digits);
3340 return digits;
3341 }
3342
3343 private static int[] ilogTable = { 0, 9, 99, 999, 9999, 99999,
3344 999999, 9999999, 99999999, 999999999, Integer.MAX_VALUE };
3345
3346 /**
3347 * Returns the length of an unsigned {@code int}, in decimal digits.
3348 * @param i the {@code int} (treated as unsigned)
3349 * @return the length of the unscaled value, in decimal digits
3350 */
3351 private int intLength(int x) {
3352 int digits;
3353 if (x < 0) { // 'negative' is 10 digits unsigned
3354 return 10;
3355 } else { // positive integer
3356 if (x <= 9)
3357 return 1;
3358 // "Hacker's Delight" section 11-4
3359 for (int i = -1;; i++) {
3360 if (x <= ilogTable[i + 1])
3361 return i + 1;
3362 }
3363 }
3364 }
3365
3366 /**
3367 * Remove insignificant trailing zeros from this
3368 * {@code BigDecimal} until the preferred scale is reached or no
3369 * more zeros can be removed. If the preferred scale is less than
3370 * Integer.MIN_VALUE, all the trailing zeros will be removed.
3371 *
3372 * {@code BigInteger} assistance could help, here?
3373 *
3374 * <p>WARNING: This method should only be called on new objects as
3375 * it mutates the value fields.
3376 *
3377 * @return this {@code BigDecimal} with a scale possibly reduced
3378 * to be closed to the preferred scale.
3379 */
3380 private BigDecimal stripZerosToMatchScale(long preferredScale) {
3381 boolean compact = (intCompact != INFLATED);
3382 this .inflate();
3383 BigInteger qr[]; // quotient-remainder pair
3384 while (intVal.abs().compareTo(BigInteger.TEN) >= 0
3385 && scale > preferredScale) {
3386 if (intVal.testBit(0))
3387 break; // odd number cannot end in 0
3388 qr = intVal.divideAndRemainder(BigInteger.TEN);
3389 if (qr[1].signum() != 0)
3390 break; // non-0 remainder
3391 intVal = qr[0];
3392 scale = checkScale((long) scale - 1); // could Overflow
3393 if (precision > 0) // adjust precision if known
3394 precision--;
3395 }
3396 if (compact)
3397 intCompact = intVal.longValue();
3398 return this ;
3399 }
3400
3401 /**
3402 * Check a scale for Underflow or Overflow. If this BigDecimal is
3403 * uninitialized or initialized and nonzero, throw an exception if
3404 * the scale is out of range. If this is zero, saturate the scale
3405 * to the extreme value of the right sign if the scale is out of
3406 * range.
3407 *
3408 * @param val The new scale.
3409 * @throws ArithmeticException (overflow or underflow) if the new
3410 * scale is out of range.
3411 * @return validated scale as an int.
3412 */
3413 private int checkScale(long val) {
3414 if ((int) val != val) {
3415 if ((this .intCompact != INFLATED && this .intCompact != 0)
3416 || (this .intVal != null && this .signum() != 0)
3417 || (this .intVal == null && this .intCompact == INFLATED)) {
3418 if (val > Integer.MAX_VALUE)
3419 throw new ArithmeticException("Underflow");
3420 if (val < Integer.MIN_VALUE)
3421 throw new ArithmeticException("Overflow");
3422 } else {
3423 return (val > Integer.MAX_VALUE) ? Integer.MAX_VALUE
3424 : Integer.MIN_VALUE;
3425 }
3426 }
3427 return (int) val;
3428 }
3429
3430 /**
3431 * Round an operand; used only if digits > 0. Does not change
3432 * {@code this}; if rounding is needed a new {@code BigDecimal}
3433 * is created and returned.
3434 *
3435 * @param mc the context to use.
3436 * @throws ArithmeticException if the result is inexact but the
3437 * rounding mode is {@code UNNECESSARY}.
3438 */
3439 private BigDecimal roundOp(MathContext mc) {
3440 BigDecimal rounded = doRound(mc);
3441 return rounded;
3442 }
3443
3444 /** Round this BigDecimal according to the MathContext settings;
3445 * used only if precision {@literal >} 0.
3446 *
3447 * <p>WARNING: This method should only be called on new objects as
3448 * it mutates the value fields.
3449 *
3450 * @param mc the context to use.
3451 * @throws ArithmeticException if the rounding mode is
3452 * {@code RoundingMode.UNNECESSARY} and the
3453 * {@code BigDecimal} operation would require rounding.
3454 */
3455 private void roundThis(MathContext mc) {
3456 BigDecimal rounded = doRound(mc);
3457 if (rounded == this ) // wasn't rounded
3458 return;
3459 this .intVal = rounded.intVal;
3460 this .intCompact = rounded.intCompact;
3461 this .scale = rounded.scale;
3462 this .precision = rounded.precision;
3463 }
3464
3465 /**
3466 * Returns a {@code BigDecimal} rounded according to the
3467 * MathContext settings; used only if {@code mc.precision > 0}.
3468 * Does not change {@code this}; if rounding is needed a new
3469 * {@code BigDecimal} is created and returned.
3470 *
3471 * @param mc the context to use.
3472 * @return a {@code BigDecimal} rounded according to the MathContext
3473 * settings. May return this, if no rounding needed.
3474 * @throws ArithmeticException if the rounding mode is
3475 * {@code RoundingMode.UNNECESSARY} and the
3476 * result is inexact.
3477 */
3478 private BigDecimal doRound(MathContext mc) {
3479 this .inflate();
3480 if (precision == 0) {
3481 if (mc.roundingMax != null
3482 && intVal.compareTo(mc.roundingMax) < 0
3483 && intVal.compareTo(mc.roundingMin) > 0)
3484 return this ; // no rounding needed
3485 precision(); // find it
3486 }
3487 int drop = precision - mc.precision; // digits to discard
3488 if (drop <= 0) // we fit
3489 return this ;
3490 BigDecimal rounded = dropDigits(mc, drop);
3491 // we need to double-check, in case of the 999=>1000 case
3492 return rounded.doRound(mc);
3493 }
3494
3495 /**
3496 * Removes digits from the significand of a {@code BigDecimal},
3497 * rounding according to the MathContext settings. Does not
3498 * change {@code this}; a new {@code BigDecimal} is always
3499 * created and returned.
3500 *
3501 * <p>Actual rounding is carried out, as before, by the divide
3502 * method, as this minimized code changes. It might be more
3503 * efficient in most cases to move rounding to here, so we can do
3504 * a round-to-length rather than round-to-scale.
3505 *
3506 * @param mc the context to use.
3507 * @param drop the number of digits to drop, must be {@literal >} 0
3508 * @return a {@code BigDecimal} rounded according to the MathContext
3509 * settings. May return {@code this}, if no rounding needed.
3510 * @throws ArithmeticException if the rounding mode is
3511 * {@code RoundingMode.UNNECESSARY} and the
3512 * result is inexact.
3513 */
3514 private BigDecimal dropDigits(MathContext mc, int drop) {
3515 // here if we need to round; make the divisor = 10**drop)
3516 // [calculating the BigInteger here saves setScale later]
3517 BigDecimal divisor = new BigDecimal(tenToThe(drop), 0);
3518
3519 // divide to same scale to force round to length
3520 BigDecimal rounded = this .divide(divisor, scale,
3521 mc.roundingMode.oldMode);
3522 rounded.scale = checkScale((long) rounded.scale - drop); // adjust the scale
3523 return rounded;
3524 }
3525
3526 private static int longCompareTo(long x, long y) {
3527 return (x < y) ? -1 : (x == y) ? 0 : 1;
3528 }
3529
3530 /*
3531 * Internal printing routine
3532 */
3533 private static void print(String name, BigDecimal bd) {
3534 System.err
3535 .format(
3536 "%s:\tintCompact %d\tintVal %d\tscale %d\tprecision %d%n",
3537 name, bd.intCompact, bd.intVal, bd.scale,
3538 bd.precision);
3539 }
3540
3541 /**
3542 * Check internal invariants of this BigDecimal. These invariants
3543 * include:
3544 *
3545 * <ul>
3546 *
3547 * <li>The object must be initialized; either intCompact must not be
3548 * INFLATED or intVal is non-null. Both of these conditions may
3549 * be true.
3550 *
3551 * <li>If both intCompact and intVal and set, their values must be
3552 * consistent.
3553 *
3554 * <li>If precision is nonzero, it must have the right value.
3555 * </ul>
3556 */
3557 private BigDecimal audit() {
3558 // Check precision
3559 if (precision > 0) {
3560 if (precision != digitLength()) {
3561 print("audit", this );
3562 throw new AssertionError("precision mismatch");
3563 }
3564 }
3565
3566 if (intCompact == INFLATED) {
3567 if (intVal == null) {
3568 print("audit", this );
3569 throw new AssertionError("null intVal");
3570 }
3571 } else {
3572 if (intVal != null) {
3573 long val = intVal.longValue();
3574 if (val != intCompact) {
3575 print("audit", this );
3576 throw new AssertionError(
3577 "Inconsistent state, intCompact="
3578 + intCompact + "\t intVal=" + val);
3579 }
3580 }
3581 }
3582 return this;
3583 }
3584 }
|