12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 /*
27 * Portions Copyright IBM Corporation, 2001. All Rights Reserved.
28 */
29
30 package java.math;
31
32 /**
33 * Immutable, arbitrary-precision signed decimal numbers. A
34 * {@code BigDecimal} consists of an arbitrary precision integer
35 * <i>unscaled value</i> and a 32-bit integer <i>scale</i>. If zero
36 * or positive, the scale is the number of digits to the right of the
37 * decimal point. If negative, the unscaled value of the number is
38 * multiplied by ten to the power of the negation of the scale. The
39 * value of the number represented by the {@code BigDecimal} is
40 * therefore <tt>(unscaledValue × 10<sup>-scale</sup>)</tt>.
41 *
42 * <p>The {@code BigDecimal} class provides operations for
43 * arithmetic, scale manipulation, rounding, comparison, hashing, and
44 * format conversion. The {@link #toString} method provides a
45 * canonical representation of a {@code BigDecimal}.
46 *
47 * <p>The {@code BigDecimal} class gives its user complete control
48 * over rounding behavior. If no rounding mode is specified and the
49 * exact result cannot be represented, an exception is thrown;
50 * otherwise, calculations can be carried out to a chosen precision
51 * and rounding mode by supplying an appropriate {@link MathContext}
212 * @author Josh Bloch
213 * @author Mike Cowlishaw
214 * @author Joseph D. Darcy
215 */
216 public class BigDecimal extends Number implements Comparable<BigDecimal> {
217 /**
218 * The unscaled value of this BigDecimal, as returned by {@link
219 * #unscaledValue}.
220 *
221 * @serial
222 * @see #unscaledValue
223 */
224 private volatile BigInteger intVal;
225
226 /**
227 * The scale of this BigDecimal, as returned by {@link #scale}.
228 *
229 * @serial
230 * @see #scale
231 */
232 private int scale = 0; // Note: this may have any value, so
233 // calculations must be done in longs
234 /**
235 * The number of decimal digits in this BigDecimal, or 0 if the
236 * number of digits are not known (lookaside information). If
237 * nonzero, the value is guaranteed correct. Use the precision()
238 * method to obtain and set the value if it might be 0. This
239 * field is mutable until set nonzero.
240 *
241 * @since 1.5
242 */
243 private volatile transient int precision = 0;
244
245 /**
246 * Used to store the canonical string representation, if computed.
247 */
248 private volatile transient String stringCache = null;
249
250 /**
251 * Sentinel value for {@link #intCompact} indicating the
252 * significand information is only available from {@code intVal}.
253 */
254 private static final long INFLATED = Long.MIN_VALUE;
255
256 /**
257 * If the absolute value of the significand of this BigDecimal is
258 * less than or equal to {@code Long.MAX_VALUE}, the value can be
259 * compactly stored in this field and used in computations.
260 */
261 private transient long intCompact = INFLATED;
262
263 // All 18-digit base ten strings fit into a long; not all 19-digit
264 // strings will
265 private static final int MAX_COMPACT_DIGITS = 18;
266
267 private static final int MAX_BIGINT_BITS = 62;
268
269 /* Appease the serialization gods */
270 private static final long serialVersionUID = 6108874887143696463L;
271
272 // Cache of common small BigDecimal values.
273 private static final BigDecimal zeroThroughTen[] = {
274 new BigDecimal(BigInteger.ZERO, 0, 0),
275 new BigDecimal(BigInteger.ONE, 1, 0),
276 new BigDecimal(BigInteger.valueOf(2), 2, 0),
277 new BigDecimal(BigInteger.valueOf(3), 3, 0),
278 new BigDecimal(BigInteger.valueOf(4), 4, 0),
279 new BigDecimal(BigInteger.valueOf(5), 5, 0),
280 new BigDecimal(BigInteger.valueOf(6), 6, 0),
281 new BigDecimal(BigInteger.valueOf(7), 7, 0),
282 new BigDecimal(BigInteger.valueOf(8), 8, 0),
283 new BigDecimal(BigInteger.valueOf(9), 9, 0),
284 new BigDecimal(BigInteger.TEN, 10, 0),
285 };
286
287 // Constants
288 /**
289 * The value 0, with a scale of 0.
290 *
291 * @since 1.5
292 */
293 public static final BigDecimal ZERO =
294 zeroThroughTen[0];
295
296 /**
297 * The value 1, with a scale of 0.
298 *
299 * @since 1.5
300 */
301 public static final BigDecimal ONE =
302 zeroThroughTen[1];
303
304 /**
305 * The value 10, with a scale of 0.
306 *
307 * @since 1.5
308 */
309 public static final BigDecimal TEN =
310 zeroThroughTen[10];
311
312 // Constructors
313
314 /**
315 * Translates a character array representation of a
316 * {@code BigDecimal} into a {@code BigDecimal}, accepting the
317 * same sequence of characters as the {@link #BigDecimal(String)}
318 * constructor, while allowing a sub-array to be specified.
319 *
320 * <p>Note that if the sequence of characters is already available
321 * within a character array, using this constructor is faster than
322 * converting the {@code char} array to string and using the
323 * {@code BigDecimal(String)} constructor .
324 *
325 * @param in {@code char} array that is the source of characters.
326 * @param offset first character in the array to inspect.
327 * @param len number of characters to consider.
328 * @throws NumberFormatException if {@code in} is not a valid
329 * representation of a {@code BigDecimal} or the defined subarray
330 * is not wholly within {@code in}.
331 * @since 1.5
332 */
333 public BigDecimal(char[] in, int offset, int len) {
334 // This is the primary string to BigDecimal constructor; all
335 // incoming strings end up here; it uses explicit (inline)
336 // parsing for speed and generates at most one intermediate
337 // (temporary) object (a char[] array).
338
339 // use array bounds checking to handle too-long, len == 0,
340 // bad offset, etc.
341 try {
342 // handle the sign
343 boolean isneg = false; // assume positive
344 if (in[offset] == '-') {
345 isneg = true; // leading minus means negative
346 offset++;
347 len--;
348 } else if (in[offset] == '+') { // leading + allowed
349 offset++;
350 len--;
351 }
352
353 // should now be at numeric part of the significand
354 int dotoff = -1; // '.' offset, -1 if none
355 int cfirst = offset; // record start of integer
356 long exp = 0; // exponent
357 if (len > in.length) // protect against huge length
358 throw new NumberFormatException();
359 char coeff[] = new char[len]; // integer significand array
360 char c; // work
361
362 for (; len > 0; offset++, len--) {
363 c = in[offset];
364 if ((c >= '0' && c <= '9') || Character.isDigit(c)) {
365 // have digit
366 coeff[precision] = c;
367 precision++; // count of digits
368 continue;
369 }
370 if (c == '.') {
371 // have dot
372 if (dotoff >= 0) // two dots
373 throw new NumberFormatException();
374 dotoff = offset;
375 continue;
376 }
377 // exponent expected
378 if ((c != 'e') && (c != 'E'))
379 throw new NumberFormatException();
380 offset++;
381 c = in[offset];
382 len--;
383 boolean negexp = false;
384 // optional sign
385 if (c == '-' || c == '+') {
386 negexp = (c == '-');
387 offset++;
388 c = in[offset];
389 len--;
390 }
391 if (len <= 0) // no exponent digits
392 throw new NumberFormatException();
393 // skip leading zeros in the exponent
394 while (len > 10 && Character.digit(c, 10) == 0) {
395 offset++;
396 c = in[offset];
397 len--;
398 }
399 if (len > 10) // too many nonzero exponent digits
400 throw new NumberFormatException();
401 // c now holds first digit of exponent
402 for (;; len--) {
403 int v;
404 if (c >= '0' && c <= '9') {
405 v = c - '0';
406 } else {
407 v = Character.digit(c, 10);
408 if (v < 0) // not a digit
409 throw new NumberFormatException();
410 }
411 exp = exp * 10 + v;
412 if (len == 1)
413 break; // that was final character
414 offset++;
415 c = in[offset];
416 }
417 if (negexp) // apply sign
418 exp = -exp;
419 // Next test is required for backwards compatibility
420 if ((int)exp != exp) // overflow
421 throw new NumberFormatException();
422 break; // [saves a test]
423 }
424 // here when no characters left
425 if (precision == 0) // no digits found
426 throw new NumberFormatException();
427
428 if (dotoff >= 0) { // had dot; set scale
429 scale = precision - (dotoff - cfirst);
430 // [cannot overflow]
431 }
432 if (exp != 0) { // had significant exponent
433 try {
434 scale = checkScale(-exp + scale); // adjust
435 } catch (ArithmeticException e) {
436 throw new NumberFormatException("Scale out of range.");
437 }
438 }
439
440 // Remove leading zeros from precision (digits count)
441 int first = 0;
442 for (; (coeff[first] == '0' || Character.digit(coeff[first], 10) == 0) &&
443 precision > 1;
444 first++)
445 precision--;
446
447 // Set the significand ..
448 // Copy significand to exact-sized array, with sign if
449 // negative
450 // Later use: BigInteger(coeff, first, precision) for
451 // both cases, by allowing an extra char at the front of
452 // coeff.
453 char quick[];
454 if (!isneg) {
455 quick = new char[precision];
456 System.arraycopy(coeff, first, quick, 0, precision);
457 } else {
458 quick = new char[precision+1];
459 quick[0] = '-';
460 System.arraycopy(coeff, first, quick, 1, precision);
461 }
462 if (precision <= MAX_COMPACT_DIGITS)
463 intCompact = Long.parseLong(new String(quick));
464 else
465 intVal = new BigInteger(quick);
466 // System.out.println(" new: " +intVal+" ["+scale+"] "+precision);
467 } catch (ArrayIndexOutOfBoundsException e) {
468 throw new NumberFormatException();
469 } catch (NegativeArraySizeException e) {
470 throw new NumberFormatException();
471 }
472 }
473
474 /**
475 * Translates a character array representation of a
476 * {@code BigDecimal} into a {@code BigDecimal}, accepting the
477 * same sequence of characters as the {@link #BigDecimal(String)}
478 * constructor, while allowing a sub-array to be specified and
479 * with rounding according to the context settings.
480 *
481 * <p>Note that if the sequence of characters is already available
482 * within a character array, using this constructor is faster than
483 * converting the {@code char} array to string and using the
484 * {@code BigDecimal(String)} constructor .
485 *
486 * @param in {@code char} array that is the source of characters.
487 * @param offset first character in the array to inspect.
488 * @param len number of characters to consider..
489 * @param mc the context to use.
490 * @throws ArithmeticException if the result is inexact but the
491 * rounding mode is {@code UNNECESSARY}.
744 intVal = BigInteger.ZERO;
745 intCompact = 0;
746 precision = 1;
747 return;
748 }
749
750 // Normalize
751 while((significand & 1) == 0) { // i.e., significand is even
752 significand >>= 1;
753 exponent++;
754 }
755
756 // Calculate intVal and scale
757 intVal = BigInteger.valueOf(sign*significand);
758 if (exponent < 0) {
759 intVal = intVal.multiply(BigInteger.valueOf(5).pow(-exponent));
760 scale = -exponent;
761 } else if (exponent > 0) {
762 intVal = intVal.multiply(BigInteger.valueOf(2).pow(exponent));
763 }
764 if (intVal.bitLength() <= MAX_BIGINT_BITS) {
765 intCompact = intVal.longValue();
766 }
767 }
768
769 /**
770 * Translates a {@code double} into a {@code BigDecimal}, with
771 * rounding according to the context settings. The scale of the
772 * {@code BigDecimal} is the smallest value such that
773 * <tt>(10<sup>scale</sup> × val)</tt> is an integer.
774 *
775 * <p>The results of this constructor can be somewhat unpredictable
776 * and its use is generally not recommended; see the notes under
777 * the {@link #BigDecimal(double)} constructor.
778 *
779 * @param val {@code double} value to be converted to
780 * {@code BigDecimal}.
781 * @param mc the context to use.
782 * @throws ArithmeticException if the result is inexact but the
783 * RoundingMode is UNNECESSARY.
784 * @throws NumberFormatException if {@code val} is infinite or NaN.
785 * @since 1.5
786 */
787 public BigDecimal(double val, MathContext mc) {
788 this(val);
789 if (mc.precision > 0)
790 roundThis(mc);
791 }
792
793 /**
794 * Translates a {@code BigInteger} into a {@code BigDecimal}.
795 * The scale of the {@code BigDecimal} is zero.
796 *
797 * @param val {@code BigInteger} value to be converted to
798 * {@code BigDecimal}.
799 */
800 public BigDecimal(BigInteger val) {
801 intVal = val;
802 if (val.bitLength() <= MAX_BIGINT_BITS) {
803 intCompact = val.longValue();
804 }
805 }
806
807 /**
808 * Translates a {@code BigInteger} into a {@code BigDecimal}
809 * rounding according to the context settings. The scale of the
810 * {@code BigDecimal} is zero.
811 *
812 * @param val {@code BigInteger} value to be converted to
813 * {@code BigDecimal}.
814 * @param mc the context to use.
815 * @throws ArithmeticException if the result is inexact but the
816 * rounding mode is {@code UNNECESSARY}.
817 * @since 1.5
818 */
819 public BigDecimal(BigInteger val, MathContext mc) {
820 intVal = val;
821 if (mc.precision > 0)
822 roundThis(mc);
823 }
824
825 /**
826 * Translates a {@code BigInteger} unscaled value and an
827 * {@code int} scale into a {@code BigDecimal}. The value of
828 * the {@code BigDecimal} is
829 * <tt>(unscaledVal × 10<sup>-scale</sup>)</tt>.
830 *
831 * @param unscaledVal unscaled value of the {@code BigDecimal}.
832 * @param scale scale of the {@code BigDecimal}.
833 */
834 public BigDecimal(BigInteger unscaledVal, int scale) {
835 // Negative scales are now allowed
836 intVal = unscaledVal;
837 this.scale = scale;
838 if (unscaledVal.bitLength() <= MAX_BIGINT_BITS) {
839 intCompact = unscaledVal.longValue();
840 }
841 }
842
843 /**
844 * Translates a {@code BigInteger} unscaled value and an
845 * {@code int} scale into a {@code BigDecimal}, with rounding
846 * according to the context settings. The value of the
847 * {@code BigDecimal} is <tt>(unscaledVal ×
848 * 10<sup>-scale</sup>)</tt>, rounded according to the
849 * {@code precision} and rounding mode settings.
850 *
851 * @param unscaledVal unscaled value of the {@code BigDecimal}.
852 * @param scale scale of the {@code BigDecimal}.
853 * @param mc the context to use.
854 * @throws ArithmeticException if the result is inexact but the
855 * rounding mode is {@code UNNECESSARY}.
856 * @since 1.5
857 */
858 public BigDecimal(BigInteger unscaledVal, int scale, MathContext mc) {
859 intVal = unscaledVal;
860 this.scale = scale;
861 if (mc.precision > 0)
862 roundThis(mc);
863 }
864
865 /**
866 * Translates an {@code int} into a {@code BigDecimal}. The
867 * scale of the {@code BigDecimal} is zero.
868 *
869 * @param val {@code int} value to be converted to
870 * {@code BigDecimal}.
871 * @since 1.5
872 */
873 public BigDecimal(int val) {
874 intCompact = val;
875 }
876
877 /**
878 * Translates an {@code int} into a {@code BigDecimal}, with
879 * rounding according to the context settings. The scale of the
882 * @param val {@code int} value to be converted to {@code BigDecimal}.
883 * @param mc the context to use.
884 * @throws ArithmeticException if the result is inexact but the
885 * rounding mode is {@code UNNECESSARY}.
886 * @since 1.5
887 */
888 public BigDecimal(int val, MathContext mc) {
889 intCompact = val;
890 if (mc.precision > 0)
891 roundThis(mc);
892 }
893
894 /**
895 * Translates a {@code long} into a {@code BigDecimal}. The
896 * scale of the {@code BigDecimal} is zero.
897 *
898 * @param val {@code long} value to be converted to {@code BigDecimal}.
899 * @since 1.5
900 */
901 public BigDecimal(long val) {
902 if (compactLong(val))
903 intCompact = val;
904 else
905 intVal = BigInteger.valueOf(val);
906 }
907
908 /**
909 * Translates a {@code long} into a {@code BigDecimal}, with
910 * rounding according to the context settings. The scale of the
911 * {@code BigDecimal}, before any rounding, is zero.
912 *
913 * @param val {@code long} value to be converted to {@code BigDecimal}.
914 * @param mc the context to use.
915 * @throws ArithmeticException if the result is inexact but the
916 * rounding mode is {@code UNNECESSARY}.
917 * @since 1.5
918 */
919 public BigDecimal(long val, MathContext mc) {
920 if (compactLong(val))
921 intCompact = val;
922 else
923 intVal = BigInteger.valueOf(val);
924 if (mc.precision > 0)
925 roundThis(mc);
926 }
927
928 /**
929 * Trusted internal constructor
930 */
931 private BigDecimal(long val, int scale) {
932 this.intCompact = val;
933 this.scale = scale;
934 }
935
936 /**
937 * Trusted internal constructor
938 */
939 private BigDecimal(BigInteger intVal, long val, int scale) {
940 this.intVal = intVal;
941 this.intCompact = val;
942 this.scale = scale;
943 }
944
945 // Static Factory Methods
946
947 /**
948 * Translates a {@code long} unscaled value and an
949 * {@code int} scale into a {@code BigDecimal}. This
950 * {@literal "static factory method"} is provided in preference to
951 * a ({@code long}, {@code int}) constructor because it
952 * allows for reuse of frequently used {@code BigDecimal} values..
953 *
954 * @param unscaledVal unscaled value of the {@code BigDecimal}.
955 * @param scale scale of the {@code BigDecimal}.
956 * @return a {@code BigDecimal} whose value is
957 * <tt>(unscaledVal × 10<sup>-scale</sup>)</tt>.
958 */
959 public static BigDecimal valueOf(long unscaledVal, int scale) {
960 if (scale == 0 && unscaledVal >= 0 && unscaledVal <= 10) {
961 return zeroThroughTen[(int)unscaledVal];
962 }
963 if (compactLong(unscaledVal))
964 return new BigDecimal(unscaledVal, scale);
965 return new BigDecimal(BigInteger.valueOf(unscaledVal), scale);
966 }
967
968 /**
969 * Translates a {@code long} value into a {@code BigDecimal}
970 * with a scale of zero. This {@literal "static factory method"}
971 * is provided in preference to a ({@code long}) constructor
972 * because it allows for reuse of frequently used
973 * {@code BigDecimal} values.
974 *
975 * @param val value of the {@code BigDecimal}.
976 * @return a {@code BigDecimal} whose value is {@code val}.
977 */
978 public static BigDecimal valueOf(long val) {
979 return valueOf(val, 0);
980 }
981
982 /**
983 * Translates a {@code double} into a {@code BigDecimal}, using
984 * the {@code double}'s canonical string representation provided
985 * by the {@link Double#toString(double)} method.
986 *
987 * <p><b>Note:</b> This is generally the preferred way to convert
988 * a {@code double} (or {@code float}) into a
989 * {@code BigDecimal}, as the value returned is equal to that
990 * resulting from constructing a {@code BigDecimal} from the
991 * result of using {@link Double#toString(double)}.
992 *
993 * @param val {@code double} to convert to a {@code BigDecimal}.
994 * @return a {@code BigDecimal} whose value is equal to or approximately
995 * equal to the value of {@code val}.
996 * @throws NumberFormatException if {@code val} is infinite or NaN.
997 * @since 1.5
998 */
999 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].inflate().intVal), arg[0].scale);
1038 }
1039
1040 /**
1041 * Returns a {@code BigDecimal} whose value is {@code (this + augend)},
1042 * with rounding according to the context settings.
1043 *
1044 * If either number is zero and the precision setting is nonzero then
1045 * the other number, rounded if necessary, is used as the result.
1046 *
1047 * @param augend value to be added to this {@code BigDecimal}.
1048 * @param mc the context to use.
1049 * @return {@code this + augend}, rounded as necessary.
1050 * @throws ArithmeticException if the result is inexact but the
1051 * rounding mode is {@code UNNECESSARY}.
1052 * @since 1.5
1053 */
1054 public BigDecimal add(BigDecimal augend, MathContext mc) {
1055 if (mc.precision == 0)
1056 return add(augend);
1057 BigDecimal lhs = this;
1058
1059 // Could optimize if values are compact
1060 this.inflate();
1061 augend.inflate();
1062
1063 // If either number is zero then the other number, rounded and
1064 // scaled if necessary, is used as the result.
1065 {
1066 boolean lhsIsZero = lhs.signum() == 0;
1067 boolean augendIsZero = augend.signum() == 0;
1068
1069 if (lhsIsZero || augendIsZero) {
1070 int preferredScale = Math.max(lhs.scale(), augend.scale());
1071 BigDecimal result;
1072
1073 // Could use a factory for zero instead of a new object
1074 if (lhsIsZero && augendIsZero)
1075 return new BigDecimal(BigInteger.ZERO, 0, preferredScale);
1076
1077
1078 result = lhsIsZero ? augend.doRound(mc) : lhs.doRound(mc);
1079
1080 if (result.scale() == preferredScale)
1081 return result;
1082 else if (result.scale() > preferredScale)
1083 return new BigDecimal(result.intVal, result.intCompact, result.scale).
1084 stripZerosToMatchScale(preferredScale);
1085 else { // result.scale < preferredScale
1086 int precisionDiff = mc.precision - result.precision();
1087 int scaleDiff = preferredScale - result.scale();
1088
1089 if (precisionDiff >= scaleDiff)
1090 return result.setScale(preferredScale); // can achieve target scale
1091 else
1092 return result.setScale(result.scale() + precisionDiff);
1093 }
1094 }
1095 }
1096
1097 long padding = (long)lhs.scale - augend.scale;
1098 if (padding != 0) { // scales differ; alignment needed
1099 BigDecimal arg[] = preAlign(lhs, augend, padding, mc);
1100 matchScale(arg);
1101 lhs = arg[0];
1102 augend = arg[1];
1103 }
1104
1105 return new BigDecimal(lhs.inflate().intVal.add(augend.inflate().intVal),
1106 lhs.scale).doRound(mc);
1107 }
1108
1109 /**
1110 * Returns an array of length two, the sum of whose entries is
1111 * equal to the rounded sum of the {@code BigDecimal} arguments.
1112 *
1113 * <p>If the digit positions of the arguments have a sufficient
1114 * gap between them, the value smaller in magnitude can be
1115 * condensed into a {@literal "sticky bit"} and the end result will
1116 * round the same way <em>if</em> the precision of the final
1117 * result does not include the high order digit of the small
1118 * magnitude operand.
1119 *
1120 * <p>Note that while strictly speaking this is an optimization,
1121 * it makes a much wider range of additions practical.
1122 *
1123 * <p>This corresponds to a pre-shift operation in a fixed
1124 * precision floating-point adder; this method is complicated by
1125 * variable precision of the result as determined by the
1126 * MathContext. A more nuanced operation could implement a
1164 smallHighDigitPos > estResultUlpScale + 2) { // small digits not visible
1165 small = BigDecimal.valueOf(small.signum(),
1166 this.checkScale(Math.max(big.scale, estResultUlpScale) + 3));
1167 }
1168
1169 // Since addition is symmetric, preserving input order in
1170 // returned operands doesn't matter
1171 BigDecimal[] result = {big, small};
1172 return result;
1173 }
1174
1175 /**
1176 * Returns a {@code BigDecimal} whose value is {@code (this -
1177 * subtrahend)}, and whose scale is {@code max(this.scale(),
1178 * subtrahend.scale())}.
1179 *
1180 * @param subtrahend value to be subtracted from this {@code BigDecimal}.
1181 * @return {@code this - subtrahend}
1182 */
1183 public BigDecimal subtract(BigDecimal subtrahend) {
1184 BigDecimal arg[] = {this, subtrahend};
1185 matchScale(arg);
1186
1187 long x = arg[0].intCompact;
1188 long y = arg[1].intCompact;
1189
1190 // Might be able to do a more clever check incorporating the
1191 // inflated check into the overflow computation.
1192 if (x != INFLATED && y != INFLATED) {
1193 long difference = x - y;
1194 /*
1195 * If the difference is not an overflowed value, continue
1196 * to use the compact representation. if either of x or y
1197 * is INFLATED, the difference should also be regarded as
1198 * an overflow. See "Hacker's Delight" section 2-12 for
1199 * explanation of the overflow test.
1200 */
1201 if ( ((x ^ y) & (difference ^ x) ) >> 63 == 0L ) // not overflowed
1202 return BigDecimal.valueOf(difference, arg[0].scale);
1203 }
1204 return new BigDecimal(arg[0].inflate().intVal.subtract(arg[1].inflate().intVal),
1205 arg[0].scale);
1206 }
1207
1208 /**
1209 * Returns a {@code BigDecimal} whose value is {@code (this - subtrahend)},
1210 * with rounding according to the context settings.
1211 *
1212 * If {@code subtrahend} is zero then this, rounded if necessary, is used as the
1213 * result. If this is zero then the result is {@code subtrahend.negate(mc)}.
1214 *
1215 * @param subtrahend value to be subtracted from this {@code BigDecimal}.
1216 * @param mc the context to use.
1217 * @return {@code this - subtrahend}, rounded as necessary.
1218 * @throws ArithmeticException if the result is inexact but the
1219 * rounding mode is {@code UNNECESSARY}.
1220 * @since 1.5
1221 */
1222 public BigDecimal subtract(BigDecimal subtrahend, MathContext mc) {
1223 if (mc.precision == 0)
1224 return subtract(subtrahend);
1225 // share the special rounding code in add()
1226 this.inflate();
1227 subtrahend.inflate();
1228 BigDecimal rhs = new BigDecimal(subtrahend.intVal.negate(), subtrahend.scale);
1229 rhs.precision = subtrahend.precision;
1230 return add(rhs, mc);
1231 }
1232
1233 /**
1234 * Returns a {@code BigDecimal} whose value is <tt>(this ×
1235 * multiplicand)</tt>, and whose scale is {@code (this.scale() +
1236 * multiplicand.scale())}.
1237 *
1238 * @param multiplicand value to be multiplied by this {@code BigDecimal}.
1239 * @return {@code this * multiplicand}
1240 */
1241 public BigDecimal multiply(BigDecimal multiplicand) {
1242 long x = this.intCompact;
1243 long y = multiplicand.intCompact;
1244 int productScale = checkScale((long)scale+multiplicand.scale);
1245
1246 // Might be able to do a more clever check incorporating the
1247 // inflated check into the overflow computation.
1248 if (x != INFLATED && y != INFLATED) {
1249 /*
1250 * If the product is not an overflowed value, continue
1251 * to use the compact representation. if either of x or y
1252 * is INFLATED, the product should also be regarded as
1253 * an overflow. See "Hacker's Delight" section 2-12 for
1254 * explanation of the overflow test.
1255 */
1256 long product = x * y;
1257 if ( !(y != 0L && product/y != x) ) // not overflowed
1258 return BigDecimal.valueOf(product, productScale);
1259 }
1260
1261 BigDecimal result = new BigDecimal(this.inflate().intVal.multiply(multiplicand.inflate().intVal), productScale);
1262 return result;
1263 }
1264
1265 /**
1266 * Returns a {@code BigDecimal} whose value is <tt>(this ×
1267 * multiplicand)</tt>, with rounding according to the context settings.
1268 *
1269 * @param multiplicand value to be multiplied by this {@code BigDecimal}.
1270 * @param mc the context to use.
1271 * @return {@code this * multiplicand}, rounded as necessary.
1272 * @throws ArithmeticException if the result is inexact but the
1273 * rounding mode is {@code UNNECESSARY}.
1274 * @since 1.5
1275 */
1276 public BigDecimal multiply(BigDecimal multiplicand, MathContext mc) {
1277 if (mc.precision == 0)
1278 return multiply(multiplicand);
1279 BigDecimal lhs = this;
1280 return lhs.inflate().multiply(multiplicand.inflate()).doRound(mc);
1281 }
1282
1283 /**
1284 * Returns a {@code BigDecimal} whose value is {@code (this /
1285 * divisor)}, and whose scale is as specified. If rounding must
1286 * be performed to generate a result with the specified scale, the
1287 * specified rounding mode is applied.
1288 *
1289 * <p>The new {@link #divide(BigDecimal, int, RoundingMode)} method
1290 * should be used in preference to this legacy method.
1291 *
1292 * @param divisor value by which this {@code BigDecimal} is to be divided.
1293 * @param scale scale of the {@code BigDecimal} quotient to be returned.
1294 * @param roundingMode rounding mode to apply.
1295 * @return {@code this / divisor}
1296 * @throws ArithmeticException if {@code divisor} is zero,
1297 * {@code roundingMode==ROUND_UNNECESSARY} and
1298 * the specified scale is insufficient to represent the result
1299 * of the division exactly.
1300 * @throws IllegalArgumentException if {@code roundingMode} does not
1301 * represent a valid rounding mode.
1302 * @see #ROUND_UP
1303 * @see #ROUND_DOWN
1304 * @see #ROUND_CEILING
1305 * @see #ROUND_FLOOR
1306 * @see #ROUND_HALF_UP
1307 * @see #ROUND_HALF_DOWN
1308 * @see #ROUND_HALF_EVEN
1309 * @see #ROUND_UNNECESSARY
1310 */
1311 public BigDecimal divide(BigDecimal divisor, int scale, int roundingMode) {
1312 /*
1313 * IMPLEMENTATION NOTE: This method *must* return a new object
1314 * since dropDigits uses divide to generate a value whose
1315 * scale is then modified.
1316 */
1317 if (roundingMode < ROUND_UP || roundingMode > ROUND_UNNECESSARY)
1318 throw new IllegalArgumentException("Invalid rounding mode");
1319 /*
1320 * Rescale dividend or divisor (whichever can be "upscaled" to
1321 * produce correctly scaled quotient).
1322 * Take care to detect out-of-range scales
1323 */
1324 BigDecimal dividend;
1325 if (checkScale((long)scale + divisor.scale) >= this.scale) {
1326 dividend = this.setScale(scale + divisor.scale);
1327 } else {
1328 dividend = this;
1329 divisor = divisor.setScale(checkScale((long)this.scale - scale));
1330 }
1331
1332 boolean compact = dividend.intCompact != INFLATED && divisor.intCompact != INFLATED;
1333 long div = INFLATED;
1334 long rem = INFLATED;;
1335 BigInteger q=null, r=null;
1336
1337 if (compact) {
1338 div = dividend.intCompact / divisor.intCompact;
1339 rem = dividend.intCompact % divisor.intCompact;
1340 } else {
1341 // Do the division and return result if it's exact.
1342 BigInteger i[] = dividend.inflate().intVal.divideAndRemainder(divisor.inflate().intVal);
1343 q = i[0];
1344 r = i[1];
1345 }
1346
1347 // Check for exact result
1348 if (compact) {
1349 if (rem == 0)
1350 return new BigDecimal(div, scale);
1351 } else {
1352 if (r.signum() == 0)
1353 return new BigDecimal(q, scale);
1354 }
1355
1356 if (roundingMode == ROUND_UNNECESSARY) // Rounding prohibited
1357 throw new ArithmeticException("Rounding necessary");
1358
1359 /* Round as appropriate */
1360 int signum = dividend.signum() * divisor.signum(); // Sign of result
1361 boolean increment;
1362 if (roundingMode == ROUND_UP) { // Away from zero
1363 increment = true;
1364 } else if (roundingMode == ROUND_DOWN) { // Towards zero
1365 increment = false;
1366 } else if (roundingMode == ROUND_CEILING) { // Towards +infinity
1367 increment = (signum > 0);
1368 } else if (roundingMode == ROUND_FLOOR) { // Towards -infinity
1369 increment = (signum < 0);
1370 } else { // Remaining modes based on nearest-neighbor determination
1371 int cmpFracHalf;
1372 if (compact) {
1373 cmpFracHalf = longCompareTo(Math.abs(2*rem), Math.abs(divisor.intCompact));
1374 } else {
1375 // add(r) here is faster than multiply(2) or shiftLeft(1)
1376 cmpFracHalf= r.add(r).abs().compareTo(divisor.intVal.abs());
1377 }
1378 if (cmpFracHalf < 0) { // We're closer to higher digit
1379 increment = false;
1380 } else if (cmpFracHalf > 0) { // We're closer to lower digit
1381 increment = true;
1382 } else { // We're dead-center
1383 if (roundingMode == ROUND_HALF_UP)
1384 increment = true;
1385 else if (roundingMode == ROUND_HALF_DOWN)
1386 increment = false;
1387 else { // roundingMode == ROUND_HALF_EVEN
1388 if (compact)
1389 increment = (div & 1L) != 0L;
1390 else
1391 increment = q.testBit(0); // true iff q is odd
1392 }
1393 }
1394 }
1395
1396 if (compact) {
1397 if (increment)
1398 div += signum; // guaranteed not to overflow
1399 return new BigDecimal(div, scale);
1400 } else {
1401 return (increment
1402 ? new BigDecimal(q.add(BigInteger.valueOf(signum)), scale)
1403 : new BigDecimal(q, scale));
1404 }
1405 }
1406
1407 /**
1408 * Returns a {@code BigDecimal} whose value is {@code (this /
1409 * divisor)}, and whose scale is as specified. If rounding must
1410 * be performed to generate a result with the specified scale, the
1411 * specified rounding mode is applied.
1412 *
1413 * @param divisor value by which this {@code BigDecimal} is to be divided.
1414 * @param scale scale of the {@code BigDecimal} quotient to be returned.
1415 * @param roundingMode rounding mode to apply.
1416 * @return {@code this / divisor}
1417 * @throws ArithmeticException if {@code divisor} is zero,
1418 * {@code roundingMode==RoundingMode.UNNECESSARY} and
1419 * the specified scale is insufficient to represent the result
1420 * of the division exactly.
1421 * @since 1.5
1422 */
1423 public BigDecimal divide(BigDecimal divisor, int scale, RoundingMode roundingMode) {
1424 return divide(divisor, scale, roundingMode.oldMode);
1482 * expansion) an {@code ArithmeticException} is thrown.
1483 *
1484 * @param divisor value by which this {@code BigDecimal} is to be divided.
1485 * @throws ArithmeticException if the exact quotient does not have a
1486 * terminating decimal expansion
1487 * @return {@code this / divisor}
1488 * @since 1.5
1489 * @author Joseph D. Darcy
1490 */
1491 public BigDecimal divide(BigDecimal divisor) {
1492 /*
1493 * Handle zero cases first.
1494 */
1495 if (divisor.signum() == 0) { // x/0
1496 if (this.signum() == 0) // 0/0
1497 throw new ArithmeticException("Division undefined"); // NaN
1498 throw new ArithmeticException("Division by zero");
1499 }
1500
1501 // Calculate preferred scale
1502 int preferredScale = (int)Math.max(Math.min((long)this.scale() - divisor.scale(),
1503 Integer.MAX_VALUE), Integer.MIN_VALUE);
1504 if (this.signum() == 0) // 0/y
1505 return new BigDecimal(0, preferredScale);
1506 else {
1507 this.inflate();
1508 divisor.inflate();
1509 /*
1510 * If the quotient this/divisor has a terminating decimal
1511 * expansion, the expansion can have no more than
1512 * (a.precision() + ceil(10*b.precision)/3) digits.
1513 * Therefore, create a MathContext object with this
1514 * precision and do a divide with the UNNECESSARY rounding
1515 * mode.
1516 */
1517 MathContext mc = new MathContext( (int)Math.min(this.precision() +
1518 (long)Math.ceil(10.0*divisor.precision()/3.0),
1519 Integer.MAX_VALUE),
1520 RoundingMode.UNNECESSARY);
1521 BigDecimal quotient;
1522 try {
1523 quotient = this.divide(divisor, mc);
1524 } catch (ArithmeticException e) {
1525 throw new ArithmeticException("Non-terminating decimal expansion; " +
1526 "no exact representable decimal result.");
1527 }
1528
1529 int quotientScale = quotient.scale();
1530
1531 // divide(BigDecimal, mc) tries to adjust the quotient to
1532 // the desired one by removing trailing zeros; since the
1533 // exact divide method does not have an explicit digit
1534 // limit, we can add zeros too.
1535
1536 if (preferredScale > quotientScale)
1537 return quotient.setScale(preferredScale);
1538
1539 return quotient;
1540 }
1541 }
1542
1543 /**
1544 * Returns a {@code BigDecimal} whose value is {@code (this /
1545 * divisor)}, with rounding according to the context settings.
1546 *
1547 * @param divisor value by which this {@code BigDecimal} is to be divided.
1548 * @param mc the context to use.
1549 * @return {@code this / divisor}, rounded as necessary.
1550 * @throws ArithmeticException if the result is inexact but the
1551 * rounding mode is {@code UNNECESSARY} or
1552 * {@code mc.precision == 0} and the quotient has a
1553 * non-terminating decimal expansion.
1554 * @since 1.5
1555 */
1556 public BigDecimal divide(BigDecimal divisor, MathContext mc) {
1557 if (mc.precision == 0)
1558 return divide(divisor);
1559 BigDecimal lhs = this.inflate(); // left-hand-side
1560 BigDecimal rhs = divisor.inflate(); // right-hand-side
1561 BigDecimal result; // work
1562
1563 long preferredScale = (long)lhs.scale() - rhs.scale();
1564
1565 // Now calculate the answer. We use the existing
1566 // divide-and-round method, but as this rounds to scale we have
1567 // to normalize the values here to achieve the desired result.
1568 // For x/y we first handle y=0 and x=0, and then normalize x and
1569 // y to give x' and y' with the following constraints:
1570 // (a) 0.1 <= x' < 1
1571 // (b) x' <= y' < 10*x'
1572 // Dividing x'/y' with the required scale set to mc.precision then
1573 // will give a result in the range 0.1 to 1 rounded to exactly
1574 // the right number of digits (except in the case of a result of
1575 // 1.000... which can arise when x=y, or when rounding overflows
1576 // The 1.000... case will reduce properly to 1.
1577 if (rhs.signum() == 0) { // x/0
1578 if (lhs.signum() == 0) // 0/0
1579 throw new ArithmeticException("Division undefined"); // NaN
1580 throw new ArithmeticException("Division by zero");
1581 }
1582 if (lhs.signum() == 0) // 0/y
1583 return new BigDecimal(BigInteger.ZERO,
1584 (int)Math.max(Math.min(preferredScale,
1585 Integer.MAX_VALUE),
1586 Integer.MIN_VALUE));
1587
1588 BigDecimal xprime = new BigDecimal(lhs.intVal.abs(), lhs.precision());
1589 BigDecimal yprime = new BigDecimal(rhs.intVal.abs(), rhs.precision());
1590 // xprime and yprime are now both in range 0.1 through 0.999...
1591 if (mc.roundingMode == RoundingMode.CEILING ||
1592 mc.roundingMode == RoundingMode.FLOOR) {
1593 // The floor (round toward negative infinity) and ceil
1594 // (round toward positive infinity) rounding modes are not
1595 // invariant under a sign flip. If xprime/yprime has a
1596 // different sign than lhs/rhs, the rounding mode must be
1597 // changed.
1598 if ((xprime.signum() != lhs.signum()) ^
1599 (yprime.signum() != rhs.signum())) {
1600 mc = new MathContext(mc.precision,
1601 (mc.roundingMode==RoundingMode.CEILING)?
1602 RoundingMode.FLOOR:RoundingMode.CEILING);
1603 }
1604 }
1605
1606 if (xprime.compareTo(yprime) > 0) // satisfy constraint (b)
1607 yprime.scale -= 1; // [that is, yprime *= 10]
1608 result = xprime.divide(yprime, mc.precision, mc.roundingMode.oldMode);
1609 // correct the scale of the result...
1610 result.scale = checkScale((long)yprime.scale - xprime.scale
1611 - (rhs.scale - lhs.scale) + mc.precision);
1612 // apply the sign
1613 if (lhs.signum() != rhs.signum())
1614 result = result.negate();
1615 // doRound, here, only affects 1000000000 case.
1616 result = result.doRound(mc);
1617
1618 if (result.multiply(divisor).compareTo(this) == 0) {
1619 // Apply preferred scale rules for exact quotients
1620 return result.stripZerosToMatchScale(preferredScale);
1621 }
1622 else {
1623 return result;
1624 }
1625 }
1626
1627 /**
1628 * Returns a {@code BigDecimal} whose value is the integer part
1629 * of the quotient {@code (this / divisor)} rounded down. The
1630 * preferred scale of the result is {@code (this.scale() -
1631 * divisor.scale())}.
1632 *
1633 * @param divisor value by which this {@code BigDecimal} is to be divided.
1634 * @return The integer part of {@code this / divisor}.
1635 * @throws ArithmeticException if {@code divisor==0}
1636 * @since 1.5
1637 */
1638 public BigDecimal divideToIntegralValue(BigDecimal divisor) {
1639 // Calculate preferred scale
1640 int preferredScale = (int)Math.max(Math.min((long)this.scale() - divisor.scale(),
1641 Integer.MAX_VALUE), Integer.MIN_VALUE);
1642 this.inflate();
1643 divisor.inflate();
1644 if (this.abs().compareTo(divisor.abs()) < 0) {
1645 // much faster when this << divisor
1646 return BigDecimal.valueOf(0, preferredScale);
1647 }
1648
1649 if(this.signum() == 0 && divisor.signum() != 0)
1650 return this.setScale(preferredScale);
1651
1652 // Perform a divide with enough digits to round to a correct
1653 // integer value; then remove any fractional digits
1654
1655 int maxDigits = (int)Math.min(this.precision() +
1656 (long)Math.ceil(10.0*divisor.precision()/3.0) +
1657 Math.abs((long)this.scale() - divisor.scale()) + 2,
1658 Integer.MAX_VALUE);
1659
1660 BigDecimal quotient = this.divide(divisor, new MathContext(maxDigits,
1661 RoundingMode.DOWN));
1662 if (quotient.scale > 0) {
1663 quotient = quotient.setScale(0, RoundingMode.DOWN).
1664 stripZerosToMatchScale(preferredScale);
1665 }
1666
1667 if (quotient.scale < preferredScale) {
1668 // pad with zeros if necessary
1669 quotient = quotient.setScale(preferredScale);
1670 }
1671
1672 return quotient;
1673 }
1674
1675 /**
1676 * Returns a {@code BigDecimal} whose value is the integer part
1677 * of {@code (this / divisor)}. Since the integer part of the
1678 * exact quotient does not depend on the rounding mode, the
1679 * rounding mode does not affect the values returned by this
1680 * method. The preferred scale of the result is
1681 * {@code (this.scale() - divisor.scale())}. An
1682 * {@code ArithmeticException} is thrown if the integer part of
1683 * the exact quotient needs more than {@code mc.precision}
1684 * digits.
1685 *
1686 * @param divisor value by which this {@code BigDecimal} is to be divided.
1687 * @param mc the context to use.
1688 * @return The integer part of {@code this / divisor}.
1689 * @throws ArithmeticException if {@code divisor==0}
1690 * @throws ArithmeticException if {@code mc.precision} {@literal >} 0 and the result
1691 * requires a precision of more than {@code mc.precision} digits.
1692 * @since 1.5
1693 * @author Joseph D. Darcy
1694 */
1695 public BigDecimal divideToIntegralValue(BigDecimal divisor, MathContext mc) {
1696 if (mc.precision == 0 || // exact result
1697 (this.abs().compareTo(divisor.abs()) < 0) ) // zero result
1698 return divideToIntegralValue(divisor);
1699
1700 // Calculate preferred scale
1701 int preferredScale = (int)Math.max(Math.min((long)this.scale() - divisor.scale(),
1702 Integer.MAX_VALUE), Integer.MIN_VALUE);
1703
1704 /*
1705 * Perform a normal divide to mc.precision digits. If the
1706 * remainder has absolute value less than the divisor, the
1707 * integer portion of the quotient fits into mc.precision
1708 * digits. Next, remove any fractional digits from the
1709 * quotient and adjust the scale to the preferred value.
1710 */
1711 BigDecimal result = this.divide(divisor, new MathContext(mc.precision,
1712 RoundingMode.DOWN));
1713 int resultScale = result.scale();
1714
1715 if (result.scale() < 0) {
1716 /*
1717 * Result is an integer. See if quotient represents the
1718 * full integer portion of the exact quotient; if it does,
1719 * the computed remainder will be less than the divisor.
1720 */
1721 BigDecimal product = result.multiply(divisor);
1722 // If the quotient is the full integer value,
1723 // |dividend-product| < |divisor|.
1724 if (this.subtract(product).abs().compareTo(divisor.abs()) >= 0) {
1725 throw new ArithmeticException("Division impossible");
1726 }
1727 } else if (result.scale() > 0) {
1728 /*
1729 * Integer portion of quotient will fit into precision
1730 * digits; recompute quotient to scale 0 to avoid double
1731 * rounding and then try to adjust, if necessary.
1732 */
1733 result = result.setScale(0, RoundingMode.DOWN);
1734 }
1735 // else result.scale() == 0;
1736
1737 int precisionDiff;
1738 if ((preferredScale > result.scale()) &&
1739 (precisionDiff = mc.precision - result.precision()) > 0 ) {
1740 return result.setScale(result.scale() +
1741 Math.min(precisionDiff, preferredScale - result.scale) );
1742 } else
1743 return result.stripZerosToMatchScale(preferredScale);
1744 }
1745
1746 /**
1747 * Returns a {@code BigDecimal} whose value is {@code (this % divisor)}.
1748 *
1749 * <p>The remainder is given by
1750 * {@code this.subtract(this.divideToIntegralValue(divisor).multiply(divisor))}.
1751 * Note that this is not the modulo operation (the result can be
1752 * negative).
1753 *
1754 * @param divisor value by which this {@code BigDecimal} is to be divided.
1755 * @return {@code this % divisor}.
1756 * @throws ArithmeticException if {@code divisor==0}
1757 * @since 1.5
1758 */
1759 public BigDecimal remainder(BigDecimal divisor) {
1760 BigDecimal divrem[] = this.divideAndRemainder(divisor);
1761 return divrem[1];
1762 }
1763
1764
1932 * @return <tt>this<sup>n</sup></tt> using the ANSI standard X3.274-1996
1933 * algorithm
1934 * @throws ArithmeticException if the result is inexact but the
1935 * rounding mode is {@code UNNECESSARY}, or {@code n} is out
1936 * of range.
1937 * @since 1.5
1938 */
1939 public BigDecimal pow(int n, MathContext mc) {
1940 if (mc.precision == 0)
1941 return pow(n);
1942 if (n < -999999999 || n > 999999999)
1943 throw new ArithmeticException("Invalid operation");
1944 if (n == 0)
1945 return ONE; // x**0 == 1 in X3.274
1946 this.inflate();
1947 BigDecimal lhs = this;
1948 MathContext workmc = mc; // working settings
1949 int mag = Math.abs(n); // magnitude of n
1950 if (mc.precision > 0) {
1951
1952 int elength = intLength(mag); // length of n in digits
1953 if (elength > mc.precision) // X3.274 rule
1954 throw new ArithmeticException("Invalid operation");
1955 workmc = new MathContext(mc.precision + elength + 1,
1956 mc.roundingMode);
1957 }
1958 // ready to carry out power calculation...
1959 BigDecimal acc = ONE; // accumulator
1960 boolean seenbit = false; // set once we've seen a 1-bit
1961 for (int i=1;;i++) { // for each bit [top bit ignored]
1962 mag += mag; // shift left 1 bit
1963 if (mag < 0) { // top bit is set
1964 seenbit = true; // OK, we're off
1965 acc = acc.multiply(lhs, workmc); // acc=acc*x
1966 }
1967 if (i == 31)
1968 break; // that was the last bit
1969 if (seenbit)
1970 acc=acc.multiply(acc, workmc); // acc=acc*acc [square]
1971 // else (!seenbit) no point in squaring ONE
1972 }
1973 // if negative n, calculate the reciprocal using working precision
1974 if (n<0) // [hence mc.precision>0]
1975 acc=ONE.divide(acc, workmc);
1976 // round to final precision and strip zeros
1977 return acc.doRound(mc);
1978 }
1979
1980 /**
1981 * Returns a {@code BigDecimal} whose value is the absolute value
1982 * of this {@code BigDecimal}, and whose scale is
1983 * {@code this.scale()}.
1984 *
1985 * @return {@code abs(this)}
1986 */
1987 public BigDecimal abs() {
1988 return (signum() < 0 ? negate() : this);
1989 }
1990
1991 /**
1992 * Returns a {@code BigDecimal} whose value is the absolute value
1993 * of this {@code BigDecimal}, with rounding according to the
1994 * context settings.
1995 *
1996 * @param mc the context to use.
1997 * @return {@code abs(this)}, rounded as necessary.
2051 }
2052
2053 /**
2054 * Returns a {@code BigDecimal} whose value is {@code (+this)},
2055 * with rounding according to the context settings.
2056 *
2057 * <p>The effect of this method is identical to that of the {@link
2058 * #round(MathContext)} method.
2059 *
2060 * @param mc the context to use.
2061 * @return {@code this}, rounded as necessary. A zero result will
2062 * have a scale of 0.
2063 * @throws ArithmeticException if the result is inexact but the
2064 * rounding mode is {@code UNNECESSARY}.
2065 * @see #round(MathContext)
2066 * @since 1.5
2067 */
2068 public BigDecimal plus(MathContext mc) {
2069 if (mc.precision == 0) // no rounding please
2070 return this;
2071 return this.doRound(mc);
2072 }
2073
2074 /**
2075 * Returns the signum function of this {@code BigDecimal}.
2076 *
2077 * @return -1, 0, or 1 as the value of this {@code BigDecimal}
2078 * is negative, zero, or positive.
2079 */
2080 public int signum() {
2081 return (intCompact != INFLATED)?
2082 Long.signum(intCompact):
2083 intVal.signum();
2084 }
2085
2086 /**
2087 * Returns the <i>scale</i> of this {@code BigDecimal}. If zero
2088 * or positive, the scale is the number of digits to the right of
2089 * the decimal point. If negative, the unscaled value of the
2090 * number is multiplied by ten to the power of the negation of the
2091 * scale. For example, a scale of {@code -3} means the unscaled
2092 * value is multiplied by 1000.
2093 *
2094 * @return the scale of this {@code BigDecimal}.
2095 */
2096 public int scale() {
2097 return scale;
2098 }
2099
2100 /**
2101 * Returns the <i>precision</i> of this {@code BigDecimal}. (The
2102 * precision is the number of digits in the unscaled value.)
2103 *
2104 * <p>The precision of a zero value is 1.
2105 *
2106 * @return the precision of this {@code BigDecimal}.
2107 * @since 1.5
2108 */
2109 public int precision() {
2110 int result = precision;
2111 if (result == 0) {
2112 result = digitLength();
2113 precision = result;
2114 }
2115 return result;
2116 }
2117
2118
2119 /**
2120 * Returns a {@code BigInteger} whose value is the <i>unscaled
2121 * value</i> of this {@code BigDecimal}. (Computes <tt>(this *
2122 * 10<sup>this.scale()</sup>)</tt>.)
2123 *
2124 * @return the unscaled value of this {@code BigDecimal}.
2125 * @since 1.2
2126 */
2127 public BigInteger unscaledValue() {
2128 return this.inflate().intVal;
2129 }
2130
2131 // Rounding Modes
2132
2133 /**
2134 * Rounding mode to round away from zero. Always increments the
2135 * digit prior to a nonzero discarded fraction. Note that this rounding
2136 * mode never decreases the magnitude of the calculated value.
2137 */
2138 public final static int ROUND_UP = 0;
2139
2140 /**
2141 * Rounding mode to round towards zero. Never increments the digit
2142 * prior to a discarded fraction (i.e., truncates). Note that this
2143 * rounding mode never increases the magnitude of the calculated value.
2144 */
2145 public final static int ROUND_DOWN = 1;
2146
2147 /**
2148 * Rounding mode to round towards positive infinity. If the
2285 * dividing this {@code BigDecimal}'s unscaled value by the
2286 * appropriate power of ten to maintain its overall value.
2287 * @throws ArithmeticException if {@code roundingMode==ROUND_UNNECESSARY}
2288 * and the specified scaling operation would require
2289 * rounding.
2290 * @throws IllegalArgumentException if {@code roundingMode} does not
2291 * represent a valid rounding mode.
2292 * @see #ROUND_UP
2293 * @see #ROUND_DOWN
2294 * @see #ROUND_CEILING
2295 * @see #ROUND_FLOOR
2296 * @see #ROUND_HALF_UP
2297 * @see #ROUND_HALF_DOWN
2298 * @see #ROUND_HALF_EVEN
2299 * @see #ROUND_UNNECESSARY
2300 */
2301 public BigDecimal setScale(int newScale, int roundingMode) {
2302 if (roundingMode < ROUND_UP || roundingMode > ROUND_UNNECESSARY)
2303 throw new IllegalArgumentException("Invalid rounding mode");
2304
2305 if (newScale == this.scale) // easy case
2306 return this;
2307 if (this.signum() == 0) // zero can have any scale
2308 return BigDecimal.valueOf(0, newScale);
2309 if (newScale > this.scale) {
2310 // [we can use checkScale to assure multiplier is valid]
2311 int raise = checkScale((long)newScale - this.scale);
2312
2313 if (intCompact != INFLATED) {
2314 long scaledResult = longTenToThe(intCompact, raise);
2315 if (scaledResult != INFLATED)
2316 return BigDecimal.valueOf(scaledResult, newScale);
2317 this.inflate();
2318 }
2319
2320 BigDecimal result = new BigDecimal(intVal.multiply(tenToThe(raise)),
2321 newScale);
2322 if (this.precision > 0)
2323 result.precision = this.precision + newScale - this.scale;
2324 return result;
2325 }
2326 // scale < this.scale
2327 // we cannot perfectly predict the precision after rounding
2328 return divide(ONE, newScale, roundingMode);
2329 }
2330
2331 /**
2332 * Returns a {@code BigDecimal} whose scale is the specified
2333 * value, and whose value is numerically equal to this
2334 * {@code BigDecimal}'s. Throws an {@code ArithmeticException}
2335 * if this is not possible.
2336 *
2337 * <p>This call is typically used to increase the scale, in which
2338 * case it is guaranteed that there exists a {@code BigDecimal}
2339 * of the specified scale and the correct value. The call can
2340 * also be used to reduce the scale if the caller knows that the
2341 * {@code BigDecimal} has sufficiently many zeros at the end of
2342 * its fractional part (i.e., factors of ten in its integer value)
2343 * to allow for the rescaling without changing its value.
2344 *
2345 * <p>This method returns the same result as the two-argument
2346 * versions of {@code setScale}, but saves the caller the trouble
2347 * of specifying a rounding mode in cases where it is irrelevant.
2348 *
2349 * <p>Note that since {@code BigDecimal} objects are immutable,
2371 // Decimal Point Motion Operations
2372
2373 /**
2374 * Returns a {@code BigDecimal} which is equivalent to this one
2375 * with the decimal point moved {@code n} places to the left. If
2376 * {@code n} is non-negative, the call merely adds {@code n} to
2377 * the scale. If {@code n} is negative, the call is equivalent
2378 * to {@code movePointRight(-n)}. The {@code BigDecimal}
2379 * returned by this call has value <tt>(this ×
2380 * 10<sup>-n</sup>)</tt> and scale {@code max(this.scale()+n,
2381 * 0)}.
2382 *
2383 * @param n number of places to move the decimal point to the left.
2384 * @return a {@code BigDecimal} which is equivalent to this one with the
2385 * decimal point moved {@code n} places to the left.
2386 * @throws ArithmeticException if scale overflows.
2387 */
2388 public BigDecimal movePointLeft(int n) {
2389 // Cannot use movePointRight(-n) in case of n==Integer.MIN_VALUE
2390 int newScale = checkScale((long)scale + n);
2391 BigDecimal num;
2392 if (intCompact != INFLATED)
2393 num = BigDecimal.valueOf(intCompact, newScale);
2394 else
2395 num = new BigDecimal(intVal, newScale);
2396 return (num.scale<0 ? num.setScale(0) : num);
2397 }
2398
2399 /**
2400 * Returns a {@code BigDecimal} which is equivalent to this one
2401 * with the decimal point moved {@code n} places to the right.
2402 * If {@code n} is non-negative, the call merely subtracts
2403 * {@code n} from the scale. If {@code n} is negative, the call
2404 * is equivalent to {@code movePointLeft(-n)}. The
2405 * {@code BigDecimal} returned by this call has value <tt>(this
2406 * × 10<sup>n</sup>)</tt> and scale {@code max(this.scale()-n,
2407 * 0)}.
2408 *
2409 * @param n number of places to move the decimal point to the right.
2410 * @return a {@code BigDecimal} which is equivalent to this one
2411 * with the decimal point moved {@code n} places to the right.
2412 * @throws ArithmeticException if scale overflows.
2413 */
2414 public BigDecimal movePointRight(int n) {
2415 // Cannot use movePointLeft(-n) in case of n==Integer.MIN_VALUE
2416 int newScale = checkScale((long)scale - n);
2417 BigDecimal num;
2418 if (intCompact != INFLATED)
2419 num = BigDecimal.valueOf(intCompact, newScale);
2420 else
2421 num = new BigDecimal(intVal, newScale);
2422 return (num.scale<0 ? num.setScale(0) : num);
2423 }
2424
2425 /**
2426 * Returns a BigDecimal whose numerical value is equal to
2427 * ({@code this} * 10<sup>n</sup>). The scale of
2428 * the result is {@code (this.scale() - n)}.
2429 *
2430 * @throws ArithmeticException if the scale would be
2431 * outside the range of a 32-bit integer.
2432 *
2433 * @since 1.5
2434 */
2435 public BigDecimal scaleByPowerOfTen(int n) {
2436 this.inflate();
2437 BigDecimal num = new BigDecimal(intVal, checkScale((long)scale - n));
2438 num.precision = precision;
2439 return num;
2440 }
2441
2442 /**
2443 * Returns a {@code BigDecimal} which is numerically equal to
2444 * this one but with any trailing zeros removed from the
2445 * representation. For example, stripping the trailing zeros from
2446 * the {@code BigDecimal} value {@code 600.0}, which has
2447 * [{@code BigInteger}, {@code scale}] components equals to
2448 * [6000, 1], yields {@code 6E2} with [{@code BigInteger},
2449 * {@code scale}] components equals to [6, -2]
2450 *
2451 * @return a numerically equal {@code BigDecimal} with any
2452 * trailing zeros removed.
2453 * @since 1.5
2454 */
2455 public BigDecimal stripTrailingZeros() {
2456 this.inflate();
2457 return (new BigDecimal(intVal, scale)).stripZerosToMatchScale(Long.MIN_VALUE);
2458 }
2459
2460 // Comparison Operations
2461
2462 /**
2463 * Compares this {@code BigDecimal} with the specified
2464 * {@code BigDecimal}. Two {@code BigDecimal} objects that are
2465 * equal in value but have a different scale (like 2.0 and 2.00)
2466 * are considered equal by this method. This method is provided
2467 * in preference to individual methods for each of the six boolean
2468 * comparison operators ({@literal <}, ==,
2469 * {@literal >}, {@literal >=}, !=, {@literal <=}). The
2470 * suggested idiom for performing these comparisons is:
2471 * {@code (x.compareTo(y)} <<i>op</i>> {@code 0)}, where
2472 * <<i>op</i>> is one of the six comparison operators.
2473 *
2474 * @param val {@code BigDecimal} to which this {@code BigDecimal} is
2475 * to be compared.
2476 * @return -1, 0, or 1 as this {@code BigDecimal} is numerically
2477 * less than, equal to, or greater than {@code val}.
2478 */
2479 public int compareTo(BigDecimal val) {
2480 if (this.scale == val.scale &&
2481 this.intCompact != INFLATED &&
2482 val.intCompact != INFLATED)
2483 return longCompareTo(this.intCompact, val.intCompact);
2484
2485 // Optimization: would run fine without the next three lines
2486 int sigDiff = signum() - val.signum();
2487 if (sigDiff != 0)
2488 return (sigDiff > 0 ? 1 : -1);
2489
2490 // If the (adjusted) exponents are different we do not need to
2491 // expensively match scales and compare the significands
2492 int aethis = this.precision() - this.scale; // [-1]
2493 int aeval = val.precision() - val.scale; // [-1]
2494 if (aethis < aeval)
2495 return -this.signum();
2496 else if (aethis > aeval)
2497 return this.signum();
2498
2499 // Scale and compare intVals
2500 BigDecimal arg[] = {this, val};
2501 matchScale(arg);
2502 if (arg[0].intCompact != INFLATED &&
2503 arg[1].intCompact != INFLATED)
2504 return longCompareTo(arg[0].intCompact, arg[1].intCompact);
2505 return arg[0].inflate().intVal.compareTo(arg[1].inflate().intVal);
2506 }
2507
2508 /**
2509 * Compares this {@code BigDecimal} with the specified
2510 * {@code Object} for equality. Unlike {@link
2511 * #compareTo(BigDecimal) compareTo}, this method considers two
2512 * {@code BigDecimal} objects equal only if they are equal in
2513 * value and scale (thus 2.0 is not equal to 2.00 when compared by
2514 * this method).
2515 *
2516 * @param x {@code Object} to which this {@code BigDecimal} is
2517 * to be compared.
2518 * @return {@code true} if and only if the specified {@code Object} is a
2519 * {@code BigDecimal} whose value and scale are equal to this
2520 * {@code BigDecimal}'s.
2521 * @see #compareTo(java.math.BigDecimal)
2522 * @see #hashCode
2523 */
2524 public boolean equals(Object x) {
2525 if (!(x instanceof BigDecimal))
2526 return false;
2527 BigDecimal xDec = (BigDecimal) x;
2528 if (scale != xDec.scale)
2529 return false;
2530 if (this.intCompact != INFLATED && xDec.intCompact != INFLATED)
2531 return this.intCompact == xDec.intCompact;
2532 return this.inflate().intVal.equals(xDec.inflate().intVal);
2533 }
2534
2535 /**
2536 * Returns the minimum of this {@code BigDecimal} and
2537 * {@code val}.
2538 *
2539 * @param val value with which the minimum is to be computed.
2540 * @return the {@code BigDecimal} whose value is the lesser of this
2541 * {@code BigDecimal} and {@code val}. If they are equal,
2542 * as defined by the {@link #compareTo(BigDecimal) compareTo}
2543 * method, {@code this} is returned.
2544 * @see #compareTo(java.math.BigDecimal)
2545 */
2546 public BigDecimal min(BigDecimal val) {
2547 return (compareTo(val) <= 0 ? this : val);
2548 }
2549
2550 /**
2551 * Returns the maximum of this {@code BigDecimal} and {@code val}.
2552 *
2555 * {@code BigDecimal} and {@code val}. If they are equal,
2556 * as defined by the {@link #compareTo(BigDecimal) compareTo}
2557 * method, {@code this} is returned.
2558 * @see #compareTo(java.math.BigDecimal)
2559 */
2560 public BigDecimal max(BigDecimal val) {
2561 return (compareTo(val) >= 0 ? this : val);
2562 }
2563
2564 // Hash Function
2565
2566 /**
2567 * Returns the hash code for this {@code BigDecimal}. Note that
2568 * two {@code BigDecimal} objects that are numerically equal but
2569 * differ in scale (like 2.0 and 2.00) will generally <i>not</i>
2570 * have the same hash code.
2571 *
2572 * @return hash code for this {@code BigDecimal}.
2573 * @see #equals(Object)
2574 */
2575 public int hashCode() {
2576 if (intCompact != INFLATED) {
2577 long val2 = (intCompact < 0)?-intCompact:intCompact;
2578 int temp = (int)( ((int)(val2 >>> 32)) * 31 +
2579 (val2 & 0xffffffffL));
2580 return 31*((intCompact < 0) ?-temp:temp) + scale;
2581 } else
2582 return 31*intVal.hashCode() + scale;
2583 }
2584
2585 // Format Converters
2586
2587 /**
2588 * Returns the string representation of this {@code BigDecimal},
2589 * using scientific notation if an exponent is needed.
2590 *
2591 * <p>A standard canonical string form of the {@code BigDecimal}
2592 * is created as though by the following steps: first, the
2593 * absolute value of the unscaled value of the {@code BigDecimal}
2594 * is converted to a string in base ten using the characters
2595 * {@code '0'} through {@code '9'} with no leading zeros (except
2596 * if its value is zero, in which case a single {@code '0'}
2597 * character is used).
2598 *
2599 * <p>Next, an <i>adjusted exponent</i> is calculated; this is the
2666 * as a canonical string representation for exchanging decimal
2667 * data, or as a key for a Hashtable, etc. Locale-sensitive
2668 * number formatting and parsing is handled by the {@link
2669 * java.text.NumberFormat} class and its subclasses.
2670 *
2671 * <li>The {@link #toEngineeringString} method may be used for
2672 * presenting numbers with exponents in engineering notation, and the
2673 * {@link #setScale(int,RoundingMode) setScale} method may be used for
2674 * rounding a {@code BigDecimal} so it has a known number of digits after
2675 * the decimal point.
2676 *
2677 * <li>The digit-to-character mapping provided by
2678 * {@code Character.forDigit} is used.
2679 *
2680 * </ol>
2681 *
2682 * @return string representation of this {@code BigDecimal}.
2683 * @see Character#forDigit
2684 * @see #BigDecimal(java.lang.String)
2685 */
2686 public String toString() {
2687 if (stringCache == null)
2688 stringCache = layoutChars(true);
2689 return stringCache;
2690 }
2691
2692 /**
2693 * Returns a string representation of this {@code BigDecimal},
2694 * using engineering notation if an exponent is needed.
2695 *
2696 * <p>Returns a string that represents the {@code BigDecimal} as
2697 * described in the {@link #toString()} method, except that if
2698 * exponential notation is used, the power of ten is adjusted to
2699 * be a multiple of three (engineering notation) such that the
2700 * integer part of nonzero values will be in the range 1 through
2701 * 999. If exponential notation is used for zero values, a
2702 * decimal point and one or two fractional zero digits are used so
2703 * that the scale of the zero value is preserved. Note that
2704 * unlike the output of {@link #toString()}, the output of this
2705 * method is <em>not</em> guaranteed to recover the same [integer,
2706 * scale] pair of this {@code BigDecimal} if the output string is
2707 * converting back to a {@code BigDecimal} using the {@linkplain
2708 * #BigDecimal(String) string constructor}. The result of this method meets
2709 * the weaker constraint of always producing a numerically equal
2785 /**
2786 * Converts this {@code BigDecimal} to a {@code BigInteger}.
2787 * This conversion is analogous to a <a
2788 * href="http://java.sun.com/docs/books/jls/second_edition/html/conversions.doc.html#25363"><i>narrowing
2789 * primitive conversion</i></a> from {@code double} to
2790 * {@code long} as defined in the <a
2791 * href="http://java.sun.com/docs/books/jls/html/">Java Language
2792 * Specification</a>: any fractional part of this
2793 * {@code BigDecimal} will be discarded. Note that this
2794 * conversion can lose information about the precision of the
2795 * {@code BigDecimal} value.
2796 * <p>
2797 * To have an exception thrown if the conversion is inexact (in
2798 * other words if a nonzero fractional part is discarded), use the
2799 * {@link #toBigIntegerExact()} method.
2800 *
2801 * @return this {@code BigDecimal} converted to a {@code BigInteger}.
2802 */
2803 public BigInteger toBigInteger() {
2804 // force to an integer, quietly
2805 return this.setScale(0, ROUND_DOWN).inflate().intVal;
2806 }
2807
2808 /**
2809 * Converts this {@code BigDecimal} to a {@code BigInteger},
2810 * checking for lost information. An exception is thrown if this
2811 * {@code BigDecimal} has a nonzero fractional part.
2812 *
2813 * @return this {@code BigDecimal} converted to a {@code BigInteger}.
2814 * @throws ArithmeticException if {@code this} has a nonzero
2815 * fractional part.
2816 * @since 1.5
2817 */
2818 public BigInteger toBigIntegerExact() {
2819 // round to an integer, with Exception if decimal part non-0
2820 return this.setScale(0, ROUND_UNNECESSARY).inflate().intVal;
2821 }
2822
2823 /**
2824 * Converts this {@code BigDecimal} to a {@code long}. This
2825 * conversion is analogous to a <a
2826 * href="http://java.sun.com/docs/books/jls/second_edition/html/conversions.doc.html#25363"><i>narrowing
2827 * primitive conversion</i></a> from {@code double} to
2828 * {@code short} as defined in the <a
2829 * href="http://java.sun.com/docs/books/jls/html/">Java Language
2830 * Specification</a>: any fractional part of this
2831 * {@code BigDecimal} will be discarded, and if the resulting
2832 * "{@code BigInteger}" is too big to fit in a
2833 * {@code long}, only the low-order 64 bits are returned.
2834 * Note that this conversion can lose information about the
2835 * overall magnitude and precision of this {@code BigDecimal} value as well
2836 * as return a result with the opposite sign.
2837 *
2838 * @return this {@code BigDecimal} converted to a {@code long}.
2839 */
2840 public long longValue(){
2851 * thrown.
2852 *
2853 * @return this {@code BigDecimal} converted to a {@code long}.
2854 * @throws ArithmeticException if {@code this} has a nonzero
2855 * fractional part, or will not fit in a {@code long}.
2856 * @since 1.5
2857 */
2858 public long longValueExact() {
2859 if (intCompact != INFLATED && scale == 0)
2860 return intCompact;
2861 // If more than 19 digits in integer part it cannot possibly fit
2862 if ((precision() - scale) > 19) // [OK for negative scale too]
2863 throw new java.lang.ArithmeticException("Overflow");
2864 // Fastpath zero and < 1.0 numbers (the latter can be very slow
2865 // to round if very small)
2866 if (this.signum() == 0)
2867 return 0;
2868 if ((this.precision() - this.scale) <= 0)
2869 throw new ArithmeticException("Rounding necessary");
2870 // round to an integer, with Exception if decimal part non-0
2871 BigDecimal num = this.setScale(0, ROUND_UNNECESSARY).inflate();
2872 if (num.precision() >= 19) // need to check carefully
2873 LongOverflow.check(num);
2874 return num.intVal.longValue();
2875 }
2876
2877 private static class LongOverflow {
2878 /** BigInteger equal to Long.MIN_VALUE. */
2879 private static final BigInteger LONGMIN = BigInteger.valueOf(Long.MIN_VALUE);
2880
2881 /** BigInteger equal to Long.MAX_VALUE. */
2882 private static final BigInteger LONGMAX = BigInteger.valueOf(Long.MAX_VALUE);
2883
2884 public static void check(BigDecimal num) {
2885 if ((num.intVal.compareTo(LONGMIN) < 0) ||
2886 (num.intVal.compareTo(LONGMAX) > 0))
2887 throw new java.lang.ArithmeticException("Overflow");
2888 }
2889 }
2890
2891 /**
2892 * Converts this {@code BigDecimal} to an {@code int}. This
2893 * conversion is analogous to a <a
2894 * href="http://java.sun.com/docs/books/jls/second_edition/html/conversions.doc.html#25363"><i>narrowing
2895 * primitive conversion</i></a> from {@code double} to
2896 * {@code short} as defined in the <a
2897 * href="http://java.sun.com/docs/books/jls/html/">Java Language
2898 * Specification</a>: any fractional part of this
2899 * {@code BigDecimal} will be discarded, and if the resulting
2900 * "{@code BigInteger}" is too big to fit in an
2901 * {@code int}, only the low-order 32 bits are returned.
2902 * Note that this conversion can lose information about the
2903 * overall magnitude and precision of this {@code BigDecimal}
2904 * value as well as return a result with the opposite sign.
3020 }
3021
3022 /**
3023 * Returns the size of an ulp, a unit in the last place, of this
3024 * {@code BigDecimal}. An ulp of a nonzero {@code BigDecimal}
3025 * value is the positive distance between this value and the
3026 * {@code BigDecimal} value next larger in magnitude with the
3027 * same number of digits. An ulp of a zero value is numerically
3028 * equal to 1 with the scale of {@code this}. The result is
3029 * stored with the same scale as {@code this} so the result
3030 * for zero and nonzero values is equal to {@code [1,
3031 * this.scale()]}.
3032 *
3033 * @return the size of an ulp of {@code this}
3034 * @since 1.5
3035 */
3036 public BigDecimal ulp() {
3037 return BigDecimal.valueOf(1, this.scale());
3038 }
3039
3040 // Private "Helper" Methods
3041
3042 /**
3043 * Lay out this {@code BigDecimal} into a {@code char[]} array.
3044 * The Java 1.2 equivalent to this was called {@code getValueString}.
3045 *
3046 * @param sci {@code true} for Scientific exponential notation;
3047 * {@code false} for Engineering
3048 * @return string with canonical string representation of this
3049 * {@code BigDecimal}
3050 */
3051 private String layoutChars(boolean sci) {
3052 if (scale == 0) // zero scale is trivial
3053 return (intCompact != INFLATED) ?
3054 Long.toString(intCompact):
3055 intVal.toString();
3056
3057 // Get the significand as an absolute value
3058 char coeff[];
3059 if (intCompact != INFLATED)
3060 coeff = Long.toString(Math.abs(intCompact)).toCharArray();
3061 else
3062 coeff = intVal.abs().toString().toCharArray();
3063
3064 // Construct a buffer, with sufficient capacity for all cases.
3065 // If E-notation is needed, length will be: +1 if negative, +1
3066 // if '.' needed, +2 for "E+", + up to 10 for adjusted exponent.
3067 // Otherwise it could have +1 if negative, plus leading "0.00000"
3068 StringBuilder buf=new StringBuilder(coeff.length+14);
3069 if (signum() < 0) // prefix '-' if negative
3070 buf.append('-');
3071 long adjusted = -(long)scale + (coeff.length-1);
3072 if ((scale >= 0) && (adjusted >= -6)) { // plain number
3073 int pad = scale - coeff.length; // count of padding zeros
3074 if (pad >= 0) { // 0.xxx form
3075 buf.append('0');
3076 buf.append('.');
3077 for (; pad>0; pad--) {
3078 buf.append('0');
3079 }
3080 buf.append(coeff);
3081 } else { // xx.xx form
3082 buf.append(coeff, 0, -pad);
3083 buf.append('.');
3084 buf.append(coeff, -pad, scale);
3085 }
3086 } else { // E-notation is needed
3087 if (sci) { // Scientific notation
3088 buf.append(coeff[0]); // first character
3089 if (coeff.length > 1) { // more to come
3090 buf.append('.');
3091 buf.append(coeff, 1, coeff.length-1);
3092 }
3093 } else { // Engineering notation
3094 int sig = (int)(adjusted % 3);
3095 if (sig < 0)
3096 sig += 3; // [adjusted was negative]
3097 adjusted -= sig; // now a multiple of 3
3098 sig++;
3099 if (signum() == 0) {
3100 switch (sig) {
3101 case 1:
3102 buf.append('0'); // exponent is a multiple of three
3103 break;
3104 case 2:
3105 buf.append("0.00");
3106 adjusted += 3;
3107 break;
3108 case 3:
3109 buf.append("0.0");
3110 adjusted += 3;
3111 break;
3112 default:
3113 throw new AssertionError("Unexpected sig value " + sig);
3114 }
3115 } else if (sig >= coeff.length) { // significand all in integer
3116 buf.append(coeff, 0, coeff.length);
3117 // may need some zeros, too
3118 for (int i = sig - coeff.length; i > 0; i--)
3119 buf.append('0');
3120 } else { // xx.xxE form
3121 buf.append(coeff, 0, sig);
3122 buf.append('.');
3123 buf.append(coeff, sig, coeff.length-sig);
3124 }
3125 }
3126 if (adjusted != 0) { // [!sci could have made 0]
3127 buf.append('E');
3128 if (adjusted > 0) // force sign for positive
3129 buf.append('+');
3130 buf.append(adjusted);
3131 }
3132 }
3133 return buf.toString();
3134 }
3135
3136 /**
3137 * Return 10 to the power n, as a {@code BigInteger}.
3138 *
3139 * @param n the power of ten to be returned (>=0)
3140 * @return a {@code BigInteger} with the value (10<sup>n</sup>)
3141 */
3142 private static BigInteger tenToThe(int n) {
3143 if (n < TENPOWERS.length) // use value from constant array
3144 return TENPOWERS[n];
3145 // BigInteger.pow is slow, so make 10**n by constructing a
3146 // BigInteger from a character string (still not very fast)
3147 char tenpow[] = new char[n + 1];
3148 tenpow[0] = '1';
3149 for (int i = 1; i <= n; i++)
3150 tenpow[i] = '0';
3151 return new BigInteger(tenpow);
3152 }
3153 private static BigInteger TENPOWERS[] = {BigInteger.ONE,
3154 BigInteger.valueOf(10), BigInteger.valueOf(100),
3155 BigInteger.valueOf(1000), BigInteger.valueOf(10000),
3156 BigInteger.valueOf(100000), BigInteger.valueOf(1000000),
3157 BigInteger.valueOf(10000000), BigInteger.valueOf(100000000),
3158 BigInteger.valueOf(1000000000)};
3159
3160 /**
3161 * Compute val * 10 ^ n; return this product if it is
3162 * representable as a long, INFLATED otherwise.
3163 */
3164 private static long longTenToThe(long val, int n) {
3165 // System.err.print("\tval " + val + "\t power " + n + "\tresult ");
3166 if (n >= 0 && n < thresholds.length) {
3167 if (Math.abs(val) <= thresholds[n][0] ) {
3168 // System.err.println(val * thresholds[n][1]);
3169 return val * thresholds[n][1];
3170 }
3171 }
3172 // System.err.println(INFLATED);
3173 return INFLATED;
3174 }
3175
3176 private static long thresholds[][] = {
3177 {Long.MAX_VALUE, 1L}, // 0
3178 {Long.MAX_VALUE/10L, 10L}, // 1
3179 {Long.MAX_VALUE/100L, 100L}, // 2
3180 {Long.MAX_VALUE/1000L, 1000L}, // 3
3181 {Long.MAX_VALUE/10000L, 10000L}, // 4
3182 {Long.MAX_VALUE/100000L, 100000L}, // 5
3183 {Long.MAX_VALUE/1000000L, 1000000L}, // 6
3184 {Long.MAX_VALUE/10000000L, 10000000L}, // 7
3185 {Long.MAX_VALUE/100000000L, 100000000L}, // 8
3186 {Long.MAX_VALUE/1000000000L, 1000000000L}, // 9
3187 {Long.MAX_VALUE/10000000000L, 10000000000L}, // 10
3188 {Long.MAX_VALUE/100000000000L, 100000000000L}, // 11
3189 {Long.MAX_VALUE/1000000000000L, 1000000000000L},// 12
3190 {Long.MAX_VALUE/100000000000000L, 10000000000000L},// 13
3191 };
3192
3193 private static boolean compactLong(long val) {
3194 return (val != Long.MIN_VALUE);
3195 }
3196
3197 /**
3198 * Assign appropriate BigInteger to intVal field if intVal is
3199 * null, i.e. the compact representation is in use.
3200 */
3201 private BigDecimal inflate() {
3202 if (intVal == null)
3203 intVal = BigInteger.valueOf(intCompact);
3204 return this;
3205 }
3206
3207 /**
3208 * Match the scales of two {@code BigDecimal}s to align their
3209 * least significant digits.
3210 *
3211 * <p>If the scales of val[0] and val[1] differ, rescale
3212 * (non-destructively) the lower-scaled {@code BigDecimal} so
3213 * they match. That is, the lower-scaled reference will be
3214 * replaced by a reference to a new object with the same scale as
3215 * the other {@code BigDecimal}.
3216 *
3217 * @param val array of two elements referring to the two
3218 * {@code BigDecimal}s to be aligned.
3219 */
3220 private static void matchScale(BigDecimal[] val) {
3221 if (val[0].scale < val[1].scale)
3222 val[0] = val[0].setScale(val[1].scale);
3223 else if (val[1].scale < val[0].scale)
3224 val[1] = val[1].setScale(val[0].scale);
3225 }
3226
3227 /**
3228 * Reconstitute the {@code BigDecimal} instance from a stream (that is,
3229 * deserialize it).
3230 *
3231 * @param s the stream being read.
3232 */
3233 private void readObject(java.io.ObjectInputStream s)
3234 throws java.io.IOException, ClassNotFoundException {
3235 // Read in all fields
3236 s.defaultReadObject();
3237 // validate possibly bad fields
3238 if (intVal == null) {
3239 String message = "BigDecimal: null intVal in stream";
3240 throw new java.io.StreamCorruptedException(message);
3241 // [all values of scale are now allowed]
3242 }
3243 // Set intCompact to uninitialized value; could also see if the
3244 // intVal was small enough to fit as a compact value.
3245 intCompact = INFLATED;
3246 }
3247
3248 /**
3249 * Serialize this {@code BigDecimal} to the stream in question
3250 *
3251 * @param s the stream to serialize to.
3252 */
3253 private void writeObject(java.io.ObjectOutputStream s)
3254 throws java.io.IOException {
3255 // Must inflate to maintain compatible serial form.
3256 this.inflate();
3257
3258 // Write proper fields
3259 s.defaultWriteObject();
3260 }
3261
3262 /**
3263 * Returns the length of this {@code BigDecimal}, in decimal digits.
3264 *
3265 * Notes:
3266 *<ul>
3267 * <li> This is performance-critical; most operations where a
3268 * context is supplied will need at least one call to this
3269 * method.
3270 *
3271 * <li> This should be a method on BigInteger; the call to this
3272 * method in precision() can then be replaced with the
3273 * term: intVal.digitLength(). It could also be called
3274 * precision() in BigInteger.
3275 *
3276 * Better still -- the precision lookaside could be moved to
3277 * BigInteger, too.
3278 *
3279 * <li> This could/should use MutableBigIntegers directly for the
3280 * reduction loop.
3281 *<ul>
3282 * @return the length of the unscaled value, in decimal digits
3283 */
3284 private int digitLength() {
3285 if (intCompact != INFLATED && Math.abs(intCompact) <= Integer.MAX_VALUE)
3286 return intLength(Math.abs((int)intCompact));
3287 if (signum() == 0) // 0 is one decimal digit
3288 return 1;
3289 this.inflate();
3290 // we have a nonzero magnitude
3291 BigInteger work = intVal;
3292 int digits = 0; // counter
3293 for (;work.mag.length>1;) {
3294 // here when more than one integer in the magnitude; divide
3295 // by a billion (reduce by 9 digits) and try again
3296 work = work.divide(TENPOWERS[9]);
3297 digits += 9;
3298 if (work.signum() == 0) // the division was exact
3299 return digits; // (a power of a billion)
3300 }
3301 // down to a simple nonzero integer
3302 digits += intLength(work.mag[0]);
3303 // System.out.println("digitLength... "+this+" -> "+digits);
3304 return digits;
3305 }
3306
3307 private static int[] ilogTable = {
3308 0,
3309 9,
3310 99,
3311 999,
3312 9999,
3313 99999,
3314 999999,
3315 9999999,
3316 99999999,
3317 999999999,
3318 Integer.MAX_VALUE};
3319
3320 /**
3321 * Returns the length of an unsigned {@code int}, in decimal digits.
3322 * @param i the {@code int} (treated as unsigned)
3323 * @return the length of the unscaled value, in decimal digits
3324 */
3325 private int intLength(int x) {
3326 int digits;
3327 if (x < 0) { // 'negative' is 10 digits unsigned
3328 return 10;
3329 } else { // positive integer
3330 if (x <= 9)
3331 return 1;
3332 // "Hacker's Delight" section 11-4
3333 for(int i = -1; ; i++) {
3334 if (x <= ilogTable[i+1])
3335 return i +1;
3336 }
3337 }
3338 }
3339
3340 /**
3341 * Remove insignificant trailing zeros from this
3342 * {@code BigDecimal} until the preferred scale is reached or no
3343 * more zeros can be removed. If the preferred scale is less than
3344 * Integer.MIN_VALUE, all the trailing zeros will be removed.
3345 *
3346 * {@code BigInteger} assistance could help, here?
3347 *
3348 * <p>WARNING: This method should only be called on new objects as
3349 * it mutates the value fields.
3350 *
3351 * @return this {@code BigDecimal} with a scale possibly reduced
3352 * to be closed to the preferred scale.
3353 */
3354 private BigDecimal stripZerosToMatchScale(long preferredScale) {
3355 boolean compact = (intCompact != INFLATED);
3356 this.inflate();
3357 BigInteger qr[]; // quotient-remainder pair
3358 while ( intVal.abs().compareTo(BigInteger.TEN) >= 0 &&
3359 scale > preferredScale) {
3360 if (intVal.testBit(0))
3361 break; // odd number cannot end in 0
3362 qr = intVal.divideAndRemainder(BigInteger.TEN);
3363 if (qr[1].signum() != 0)
3364 break; // non-0 remainder
3365 intVal=qr[0];
3366 scale = checkScale((long)scale-1); // could Overflow
3367 if (precision > 0) // adjust precision if known
3368 precision--;
3369 }
3370 if (compact)
3371 intCompact = intVal.longValue();
3372 return this;
3373 }
3374
3375 /**
3376 * Check a scale for Underflow or Overflow. If this BigDecimal is
3377 * uninitialized or initialized and nonzero, throw an exception if
3378 * the scale is out of range. If this is zero, saturate the scale
3379 * to the extreme value of the right sign if the scale is out of
3380 * range.
3381 *
3382 * @param val The new scale.
3383 * @throws ArithmeticException (overflow or underflow) if the new
3384 * scale is out of range.
3385 * @return validated scale as an int.
3386 */
3387 private int checkScale(long val) {
3388 if ((int)val != val) {
3389 if ((this.intCompact != INFLATED && this.intCompact != 0) ||
3390 (this.intVal != null && this.signum() != 0) ||
3391 (this.intVal == null && this.intCompact == INFLATED) ) {
3392 if (val > Integer.MAX_VALUE)
3393 throw new ArithmeticException("Underflow");
3394 if (val < Integer.MIN_VALUE)
3395 throw new ArithmeticException("Overflow");
3396 } else {
3397 return (val > Integer.MAX_VALUE)?Integer.MAX_VALUE:Integer.MIN_VALUE;
3398 }
3399 }
3400 return (int)val;
3401 }
3402
3403 /**
3404 * Round an operand; used only if digits > 0. Does not change
3405 * {@code this}; if rounding is needed a new {@code BigDecimal}
3406 * is created and returned.
3407 *
3408 * @param mc the context to use.
3409 * @throws ArithmeticException if the result is inexact but the
3410 * rounding mode is {@code UNNECESSARY}.
3411 */
3412 private BigDecimal roundOp(MathContext mc) {
3413 BigDecimal rounded = doRound(mc);
3414 return rounded;
3415 }
3416
3417 /** Round this BigDecimal according to the MathContext settings;
3418 * used only if precision {@literal >} 0.
3419 *
3420 * <p>WARNING: This method should only be called on new objects as
3421 * it mutates the value fields.
3422 *
3423 * @param mc the context to use.
3424 * @throws ArithmeticException if the rounding mode is
3425 * {@code RoundingMode.UNNECESSARY} and the
3426 * {@code BigDecimal} operation would require rounding.
3427 */
3428 private void roundThis(MathContext mc) {
3429 BigDecimal rounded = doRound(mc);
3430 if (rounded == this) // wasn't rounded
3431 return;
3432 this.intVal = rounded.intVal;
3433 this.intCompact = rounded.intCompact;
3434 this.scale = rounded.scale;
3435 this.precision = rounded.precision;
3436 }
3437
3438 /**
3439 * Returns a {@code BigDecimal} rounded according to the
3440 * MathContext settings; used only if {@code mc.precision > 0}.
3441 * Does not change {@code this}; if rounding is needed a new
3442 * {@code BigDecimal} is created and returned.
3443 *
3444 * @param mc the context to use.
3445 * @return a {@code BigDecimal} rounded according to the MathContext
3446 * settings. May return this, if no rounding needed.
3447 * @throws ArithmeticException if the rounding mode is
3448 * {@code RoundingMode.UNNECESSARY} and the
3449 * result is inexact.
3450 */
3451 private BigDecimal doRound(MathContext mc) {
3452 this.inflate();
3453 if (precision == 0) {
3454 if (mc.roundingMax != null
3455 && intVal.compareTo(mc.roundingMax) < 0
3456 && intVal.compareTo(mc.roundingMin) > 0)
3457 return this; // no rounding needed
3458 precision(); // find it
3459 }
3460 int drop = precision - mc.precision; // digits to discard
3461 if (drop <= 0) // we fit
3462 return this;
3463 BigDecimal rounded = dropDigits(mc, drop);
3464 // we need to double-check, in case of the 999=>1000 case
3465 return rounded.doRound(mc);
3466 }
3467
3468 /**
3469 * Removes digits from the significand of a {@code BigDecimal},
3470 * rounding according to the MathContext settings. Does not
3471 * change {@code this}; a new {@code BigDecimal} is always
3472 * created and returned.
3473 *
3474 * <p>Actual rounding is carried out, as before, by the divide
3475 * method, as this minimized code changes. It might be more
3476 * efficient in most cases to move rounding to here, so we can do
3477 * a round-to-length rather than round-to-scale.
3478 *
3479 * @param mc the context to use.
3480 * @param drop the number of digits to drop, must be {@literal >} 0
3481 * @return a {@code BigDecimal} rounded according to the MathContext
3482 * settings. May return {@code this}, if no rounding needed.
3483 * @throws ArithmeticException if the rounding mode is
3484 * {@code RoundingMode.UNNECESSARY} and the
3485 * result is inexact.
3486 */
3487 private BigDecimal dropDigits(MathContext mc, int drop) {
3488 // here if we need to round; make the divisor = 10**drop)
3489 // [calculating the BigInteger here saves setScale later]
3490 BigDecimal divisor = new BigDecimal(tenToThe(drop), 0);
3491
3492 // divide to same scale to force round to length
3493 BigDecimal rounded = this.divide(divisor, scale,
3494 mc.roundingMode.oldMode);
3495 rounded.scale = checkScale((long)rounded.scale - drop ); // adjust the scale
3496 return rounded;
3497 }
3498
3499 private static int longCompareTo(long x, long y) {
3500 return (x < y) ? -1 : (x == y) ? 0 : 1;
3501 }
3502
3503 /*
3504 * Internal printing routine
3505 */
3506 private static void print(String name, BigDecimal bd) {
3507 System.err.format("%s:\tintCompact %d\tintVal %d\tscale %d\tprecision %d%n",
3508 name,
3509 bd.intCompact,
3510 bd.intVal,
3511 bd.scale,
3512 bd.precision);
3513 }
3514
3515 /**
3516 * Check internal invariants of this BigDecimal. These invariants
3517 * include:
3518 *
3519 * <ul>
3520 *
3521 * <li>The object must be initialized; either intCompact must not be
3522 * INFLATED or intVal is non-null. Both of these conditions may
3523 * be true.
3524 *
3525 * <li>If both intCompact and intVal and set, their values must be
3526 * consistent.
3527 *
3528 * <li>If precision is nonzero, it must have the right value.
3529 * </ul>
3530 */
3531 private BigDecimal audit() {
3532 // Check precision
3533 if (precision > 0) {
3534 if (precision != digitLength()) {
3535 print("audit", this);
3536 throw new AssertionError("precision mismatch");
3537 }
3538 }
3539
3540 if (intCompact == INFLATED) {
3541 if (intVal == null) {
3542 print("audit", this);
3543 throw new AssertionError("null intVal");
3544 }
3545 } else {
3546 if (intVal != null) {
3547 long val = intVal.longValue();
3548 if (val != intCompact) {
3549 print("audit", this);
3550 throw new AssertionError("Inconsistent state, intCompact=" +
3551 intCompact + "\t intVal=" + val);
3552 }
3553 }
3554 }
3555 return this;
3556 }
3557 }
|
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 /*
27 * Portions Copyright IBM Corporation, 2001. All Rights Reserved.
28 */
29
30 package java.math;
31
32 import java.util.Arrays;
33 import static java.math.BigInteger.LONG_MASK;
34
35 /**
36 * Immutable, arbitrary-precision signed decimal numbers. A
37 * {@code BigDecimal} consists of an arbitrary precision integer
38 * <i>unscaled value</i> and a 32-bit integer <i>scale</i>. If zero
39 * or positive, the scale is the number of digits to the right of the
40 * decimal point. If negative, the unscaled value of the number is
41 * multiplied by ten to the power of the negation of the scale. The
42 * value of the number represented by the {@code BigDecimal} is
43 * therefore <tt>(unscaledValue × 10<sup>-scale</sup>)</tt>.
44 *
45 * <p>The {@code BigDecimal} class provides operations for
46 * arithmetic, scale manipulation, rounding, comparison, hashing, and
47 * format conversion. The {@link #toString} method provides a
48 * canonical representation of a {@code BigDecimal}.
49 *
50 * <p>The {@code BigDecimal} class gives its user complete control
51 * over rounding behavior. If no rounding mode is specified and the
52 * exact result cannot be represented, an exception is thrown;
53 * otherwise, calculations can be carried out to a chosen precision
54 * and rounding mode by supplying an appropriate {@link MathContext}
215 * @author Josh Bloch
216 * @author Mike Cowlishaw
217 * @author Joseph D. Darcy
218 */
219 public class BigDecimal extends Number implements Comparable<BigDecimal> {
220 /**
221 * The unscaled value of this BigDecimal, as returned by {@link
222 * #unscaledValue}.
223 *
224 * @serial
225 * @see #unscaledValue
226 */
227 private volatile BigInteger intVal;
228
229 /**
230 * The scale of this BigDecimal, as returned by {@link #scale}.
231 *
232 * @serial
233 * @see #scale
234 */
235 private int scale; // Note: this may have any value, so
236 // calculations must be done in longs
237 /**
238 * The number of decimal digits in this BigDecimal, or 0 if the
239 * number of digits are not known (lookaside information). If
240 * nonzero, the value is guaranteed correct. Use the precision()
241 * method to obtain and set the value if it might be 0. This
242 * field is mutable until set nonzero.
243 *
244 * @since 1.5
245 */
246 private transient int precision;
247
248 /**
249 * Used to store the canonical string representation, if computed.
250 */
251 private transient String stringCache;
252
253 /**
254 * Sentinel value for {@link #intCompact} indicating the
255 * significand information is only available from {@code intVal}.
256 */
257 static final long INFLATED = Long.MIN_VALUE;
258
259 /**
260 * If the absolute value of the significand of this BigDecimal is
261 * less than or equal to {@code Long.MAX_VALUE}, the value can be
262 * compactly stored in this field and used in computations.
263 */
264 private transient long intCompact;
265
266 // All 18-digit base ten strings fit into a long; not all 19-digit
267 // strings will
268 private static final int MAX_COMPACT_DIGITS = 18;
269
270 private static final int MAX_BIGINT_BITS = 62;
271
272 /* Appease the serialization gods */
273 private static final long serialVersionUID = 6108874887143696463L;
274
275 private static final ThreadLocal<StringBuilderHelper>
276 threadLocalStringBuilderHelper = new ThreadLocal<StringBuilderHelper>() {
277 @Override
278 protected StringBuilderHelper initialValue() {
279 return new StringBuilderHelper();
280 }
281 };
282
283 // Cache of common small BigDecimal values.
284 private static final BigDecimal zeroThroughTen[] = {
285 new BigDecimal(BigInteger.ZERO, 0, 0, 1),
286 new BigDecimal(BigInteger.ONE, 1, 0, 1),
287 new BigDecimal(BigInteger.valueOf(2), 2, 0, 1),
288 new BigDecimal(BigInteger.valueOf(3), 3, 0, 1),
289 new BigDecimal(BigInteger.valueOf(4), 4, 0, 1),
290 new BigDecimal(BigInteger.valueOf(5), 5, 0, 1),
291 new BigDecimal(BigInteger.valueOf(6), 6, 0, 1),
292 new BigDecimal(BigInteger.valueOf(7), 7, 0, 1),
293 new BigDecimal(BigInteger.valueOf(8), 8, 0, 1),
294 new BigDecimal(BigInteger.valueOf(9), 9, 0, 1),
295 new BigDecimal(BigInteger.TEN, 10, 0, 2),
296 };
297
298 // Cache of zero scaled by 0 - 15
299 private static final BigDecimal[] ZERO_SCALED_BY = {
300 zeroThroughTen[0],
301 new BigDecimal(BigInteger.ZERO, 0, 1, 1),
302 new BigDecimal(BigInteger.ZERO, 0, 2, 1),
303 new BigDecimal(BigInteger.ZERO, 0, 3, 1),
304 new BigDecimal(BigInteger.ZERO, 0, 4, 1),
305 new BigDecimal(BigInteger.ZERO, 0, 5, 1),
306 new BigDecimal(BigInteger.ZERO, 0, 6, 1),
307 new BigDecimal(BigInteger.ZERO, 0, 7, 1),
308 new BigDecimal(BigInteger.ZERO, 0, 8, 1),
309 new BigDecimal(BigInteger.ZERO, 0, 9, 1),
310 new BigDecimal(BigInteger.ZERO, 0, 10, 1),
311 new BigDecimal(BigInteger.ZERO, 0, 11, 1),
312 new BigDecimal(BigInteger.ZERO, 0, 12, 1),
313 new BigDecimal(BigInteger.ZERO, 0, 13, 1),
314 new BigDecimal(BigInteger.ZERO, 0, 14, 1),
315 new BigDecimal(BigInteger.ZERO, 0, 15, 1),
316 };
317
318 // Constants
319 /**
320 * The value 0, with a scale of 0.
321 *
322 * @since 1.5
323 */
324 public static final BigDecimal ZERO =
325 zeroThroughTen[0];
326
327 /**
328 * The value 1, with a scale of 0.
329 *
330 * @since 1.5
331 */
332 public static final BigDecimal ONE =
333 zeroThroughTen[1];
334
335 /**
336 * The value 10, with a scale of 0.
337 *
338 * @since 1.5
339 */
340 public static final BigDecimal TEN =
341 zeroThroughTen[10];
342
343 // Constructors
344
345 /**
346 * Trusted package private constructor.
347 * Trusted simply means if val is INFLATED, intVal could not be null and
348 * if intVal is null, val could not be INFLATED.
349 */
350 BigDecimal(BigInteger intVal, long val, int scale, int prec) {
351 this.scale = scale;
352 this.precision = prec;
353 this.intCompact = val;
354 this.intVal = intVal;
355 }
356
357 /**
358 * Translates a character array representation of a
359 * {@code BigDecimal} into a {@code BigDecimal}, accepting the
360 * same sequence of characters as the {@link #BigDecimal(String)}
361 * constructor, while allowing a sub-array to be specified.
362 *
363 * <p>Note that if the sequence of characters is already available
364 * within a character array, using this constructor is faster than
365 * converting the {@code char} array to string and using the
366 * {@code BigDecimal(String)} constructor .
367 *
368 * @param in {@code char} array that is the source of characters.
369 * @param offset first character in the array to inspect.
370 * @param len number of characters to consider.
371 * @throws NumberFormatException if {@code in} is not a valid
372 * representation of a {@code BigDecimal} or the defined subarray
373 * is not wholly within {@code in}.
374 * @since 1.5
375 */
376 public BigDecimal(char[] in, int offset, int len) {
377 // protect against huge length.
378 if (offset+len > in.length || offset < 0)
379 throw new NumberFormatException();
380 // This is the primary string to BigDecimal constructor; all
381 // incoming strings end up here; it uses explicit (inline)
382 // parsing for speed and generates at most one intermediate
383 // (temporary) object (a char[] array) for non-compact case.
384
385 // Use locals for all fields values until completion
386 int prec = 0; // record precision value
387 int scl = 0; // record scale value
388 long rs = 0; // the compact value in long
389 BigInteger rb = null; // the inflated value in BigInteger
390
391 // use array bounds checking to handle too-long, len == 0,
392 // bad offset, etc.
393 try {
394 // handle the sign
395 boolean isneg = false; // assume positive
396 if (in[offset] == '-') {
397 isneg = true; // leading minus means negative
398 offset++;
399 len--;
400 } else if (in[offset] == '+') { // leading + allowed
401 offset++;
402 len--;
403 }
404
405 // should now be at numeric part of the significand
406 boolean dot = false; // true when there is a '.'
407 int cfirst = offset; // record start of integer
408 long exp = 0; // exponent
409 char c; // current character
410
411 boolean isCompact = (len <= MAX_COMPACT_DIGITS);
412 // integer significand array & idx is the index to it. The array
413 // is ONLY used when we can't use a compact representation.
414 char coeff[] = isCompact ? null : new char[len];
415 int idx = 0;
416
417 for (; len > 0; offset++, len--) {
418 c = in[offset];
419 // have digit
420 if ((c >= '0' && c <= '9') || Character.isDigit(c)) {
421 // First compact case, we need not to preserve the character
422 // and we can just compute the value in place.
423 if (isCompact) {
424 int digit = Character.digit(c, 10);
425 if (digit == 0) {
426 if (prec == 0)
427 prec = 1;
428 else if (rs != 0) {
429 rs *= 10;
430 ++prec;
431 } // else digit is a redundant leading zero
432 } else {
433 if (prec != 1 || rs != 0)
434 ++prec; // prec unchanged if preceded by 0s
435 rs = rs * 10 + digit;
436 }
437 } else { // the unscaled value is likely a BigInteger object.
438 if (c == '0' || Character.digit(c, 10) == 0) {
439 if (prec == 0) {
440 coeff[idx] = c;
441 prec = 1;
442 } else if (idx != 0) {
443 coeff[idx++] = c;
444 ++prec;
445 } // else c must be a redundant leading zero
446 } else {
447 if (prec != 1 || idx != 0)
448 ++prec; // prec unchanged if preceded by 0s
449 coeff[idx++] = c;
450 }
451 }
452 if (dot)
453 ++scl;
454 continue;
455 }
456 // have dot
457 if (c == '.') {
458 // have dot
459 if (dot) // two dots
460 throw new NumberFormatException();
461 dot = true;
462 continue;
463 }
464 // exponent expected
465 if ((c != 'e') && (c != 'E'))
466 throw new NumberFormatException();
467 offset++;
468 c = in[offset];
469 len--;
470 boolean negexp = (c == '-');
471 // optional sign
472 if (negexp || c == '+') {
473 offset++;
474 c = in[offset];
475 len--;
476 }
477 if (len <= 0) // no exponent digits
478 throw new NumberFormatException();
479 // skip leading zeros in the exponent
480 while (len > 10 && Character.digit(c, 10) == 0) {
481 offset++;
482 c = in[offset];
483 len--;
484 }
485 if (len > 10) // too many nonzero exponent digits
486 throw new NumberFormatException();
487 // c now holds first digit of exponent
488 for (;; len--) {
489 int v;
490 if (c >= '0' && c <= '9') {
491 v = c - '0';
492 } else {
493 v = Character.digit(c, 10);
494 if (v < 0) // not a digit
495 throw new NumberFormatException();
496 }
497 exp = exp * 10 + v;
498 if (len == 1)
499 break; // that was final character
500 offset++;
501 c = in[offset];
502 }
503 if (negexp) // apply sign
504 exp = -exp;
505 // Next test is required for backwards compatibility
506 if ((int)exp != exp) // overflow
507 throw new NumberFormatException();
508 break; // [saves a test]
509 }
510 // here when no characters left
511 if (prec == 0) // no digits found
512 throw new NumberFormatException();
513
514 // Adjust scale if exp is not zero.
515 if (exp != 0) { // had significant exponent
516 // Can't call checkScale which relies on proper fields value
517 long adjustedScale = scl - exp;
518 if (adjustedScale > Integer.MAX_VALUE ||
519 adjustedScale < Integer.MIN_VALUE)
520 throw new NumberFormatException("Scale out of range.");
521 scl = (int)adjustedScale;
522 }
523
524 // Remove leading zeros from precision (digits count)
525 if (isCompact) {
526 rs = isneg ? -rs : rs;
527 } else {
528 char quick[];
529 if (!isneg) {
530 quick = (coeff.length != prec) ?
531 Arrays.copyOf(coeff, prec) : coeff;
532 } else {
533 quick = new char[prec + 1];
534 quick[0] = '-';
535 System.arraycopy(coeff, 0, quick, 1, prec);
536 }
537 rb = new BigInteger(quick);
538 rs = compactValFor(rb);
539 }
540 } catch (ArrayIndexOutOfBoundsException e) {
541 throw new NumberFormatException();
542 } catch (NegativeArraySizeException e) {
543 throw new NumberFormatException();
544 }
545 this.scale = scl;
546 this.precision = prec;
547 this.intCompact = rs;
548 this.intVal = rb;
549 }
550
551 /**
552 * Translates a character array representation of a
553 * {@code BigDecimal} into a {@code BigDecimal}, accepting the
554 * same sequence of characters as the {@link #BigDecimal(String)}
555 * constructor, while allowing a sub-array to be specified and
556 * with rounding according to the context settings.
557 *
558 * <p>Note that if the sequence of characters is already available
559 * within a character array, using this constructor is faster than
560 * converting the {@code char} array to string and using the
561 * {@code BigDecimal(String)} constructor .
562 *
563 * @param in {@code char} array that is the source of characters.
564 * @param offset first character in the array to inspect.
565 * @param len number of characters to consider..
566 * @param mc the context to use.
567 * @throws ArithmeticException if the result is inexact but the
568 * rounding mode is {@code UNNECESSARY}.
821 intVal = BigInteger.ZERO;
822 intCompact = 0;
823 precision = 1;
824 return;
825 }
826
827 // Normalize
828 while((significand & 1) == 0) { // i.e., significand is even
829 significand >>= 1;
830 exponent++;
831 }
832
833 // Calculate intVal and scale
834 intVal = BigInteger.valueOf(sign*significand);
835 if (exponent < 0) {
836 intVal = intVal.multiply(BigInteger.valueOf(5).pow(-exponent));
837 scale = -exponent;
838 } else if (exponent > 0) {
839 intVal = intVal.multiply(BigInteger.valueOf(2).pow(exponent));
840 }
841 intCompact = compactValFor(intVal);
842 }
843
844 /**
845 * Translates a {@code double} into a {@code BigDecimal}, with
846 * rounding according to the context settings. The scale of the
847 * {@code BigDecimal} is the smallest value such that
848 * <tt>(10<sup>scale</sup> × val)</tt> is an integer.
849 *
850 * <p>The results of this constructor can be somewhat unpredictable
851 * and its use is generally not recommended; see the notes under
852 * the {@link #BigDecimal(double)} constructor.
853 *
854 * @param val {@code double} value to be converted to
855 * {@code BigDecimal}.
856 * @param mc the context to use.
857 * @throws ArithmeticException if the result is inexact but the
858 * RoundingMode is UNNECESSARY.
859 * @throws NumberFormatException if {@code val} is infinite or NaN.
860 * @since 1.5
861 */
862 public BigDecimal(double val, MathContext mc) {
863 this(val);
864 if (mc.precision > 0)
865 roundThis(mc);
866 }
867
868 /**
869 * Translates a {@code BigInteger} into a {@code BigDecimal}.
870 * The scale of the {@code BigDecimal} is zero.
871 *
872 * @param val {@code BigInteger} value to be converted to
873 * {@code BigDecimal}.
874 */
875 public BigDecimal(BigInteger val) {
876 intVal = val;
877 intCompact = compactValFor(val);
878 }
879
880 /**
881 * Translates a {@code BigInteger} into a {@code BigDecimal}
882 * rounding according to the context settings. The scale of the
883 * {@code BigDecimal} is zero.
884 *
885 * @param val {@code BigInteger} value to be converted to
886 * {@code BigDecimal}.
887 * @param mc the context to use.
888 * @throws ArithmeticException if the result is inexact but the
889 * rounding mode is {@code UNNECESSARY}.
890 * @since 1.5
891 */
892 public BigDecimal(BigInteger val, MathContext mc) {
893 this(val);
894 if (mc.precision > 0)
895 roundThis(mc);
896 }
897
898 /**
899 * Translates a {@code BigInteger} unscaled value and an
900 * {@code int} scale into a {@code BigDecimal}. The value of
901 * the {@code BigDecimal} is
902 * <tt>(unscaledVal × 10<sup>-scale</sup>)</tt>.
903 *
904 * @param unscaledVal unscaled value of the {@code BigDecimal}.
905 * @param scale scale of the {@code BigDecimal}.
906 */
907 public BigDecimal(BigInteger unscaledVal, int scale) {
908 // Negative scales are now allowed
909 this(unscaledVal);
910 this.scale = scale;
911 }
912
913 /**
914 * Translates a {@code BigInteger} unscaled value and an
915 * {@code int} scale into a {@code BigDecimal}, with rounding
916 * according to the context settings. The value of the
917 * {@code BigDecimal} is <tt>(unscaledVal ×
918 * 10<sup>-scale</sup>)</tt>, rounded according to the
919 * {@code precision} and rounding mode settings.
920 *
921 * @param unscaledVal unscaled value of the {@code BigDecimal}.
922 * @param scale scale of the {@code BigDecimal}.
923 * @param mc the context to use.
924 * @throws ArithmeticException if the result is inexact but the
925 * rounding mode is {@code UNNECESSARY}.
926 * @since 1.5
927 */
928 public BigDecimal(BigInteger unscaledVal, int scale, MathContext mc) {
929 this(unscaledVal);
930 this.scale = scale;
931 if (mc.precision > 0)
932 roundThis(mc);
933 }
934
935 /**
936 * Translates an {@code int} into a {@code BigDecimal}. The
937 * scale of the {@code BigDecimal} is zero.
938 *
939 * @param val {@code int} value to be converted to
940 * {@code BigDecimal}.
941 * @since 1.5
942 */
943 public BigDecimal(int val) {
944 intCompact = val;
945 }
946
947 /**
948 * Translates an {@code int} into a {@code BigDecimal}, with
949 * rounding according to the context settings. The scale of the
952 * @param val {@code int} value to be converted to {@code BigDecimal}.
953 * @param mc the context to use.
954 * @throws ArithmeticException if the result is inexact but the
955 * rounding mode is {@code UNNECESSARY}.
956 * @since 1.5
957 */
958 public BigDecimal(int val, MathContext mc) {
959 intCompact = val;
960 if (mc.precision > 0)
961 roundThis(mc);
962 }
963
964 /**
965 * Translates a {@code long} into a {@code BigDecimal}. The
966 * scale of the {@code BigDecimal} is zero.
967 *
968 * @param val {@code long} value to be converted to {@code BigDecimal}.
969 * @since 1.5
970 */
971 public BigDecimal(long val) {
972 this.intCompact = val;
973 this.intVal = (val == INFLATED) ? BigInteger.valueOf(val) : null;
974 }
975
976 /**
977 * Translates a {@code long} into a {@code BigDecimal}, with
978 * rounding according to the context settings. The scale of the
979 * {@code BigDecimal}, before any rounding, is zero.
980 *
981 * @param val {@code long} value to be converted to {@code BigDecimal}.
982 * @param mc the context to use.
983 * @throws ArithmeticException if the result is inexact but the
984 * rounding mode is {@code UNNECESSARY}.
985 * @since 1.5
986 */
987 public BigDecimal(long val, MathContext mc) {
988 this(val);
989 if (mc.precision > 0)
990 roundThis(mc);
991 }
992
993 // Static Factory Methods
994
995 /**
996 * Translates a {@code long} unscaled value and an
997 * {@code int} scale into a {@code BigDecimal}. This
998 * {@literal "static factory method"} is provided in preference to
999 * a ({@code long}, {@code int}) constructor because it
1000 * allows for reuse of frequently used {@code BigDecimal} values..
1001 *
1002 * @param unscaledVal unscaled value of the {@code BigDecimal}.
1003 * @param scale scale of the {@code BigDecimal}.
1004 * @return a {@code BigDecimal} whose value is
1005 * <tt>(unscaledVal × 10<sup>-scale</sup>)</tt>.
1006 */
1007 public static BigDecimal valueOf(long unscaledVal, int scale) {
1008 if (scale == 0)
1009 return valueOf(unscaledVal);
1010 else if (unscaledVal == 0) {
1011 if (scale > 0 && scale < ZERO_SCALED_BY.length)
1012 return ZERO_SCALED_BY[scale];
1013 else
1014 return new BigDecimal(BigInteger.ZERO, 0, scale, 1);
1015 }
1016 return new BigDecimal(unscaledVal == INFLATED ?
1017 BigInteger.valueOf(unscaledVal) : null,
1018 unscaledVal, scale, 0);
1019 }
1020
1021 /**
1022 * Translates a {@code long} value into a {@code BigDecimal}
1023 * with a scale of zero. This {@literal "static factory method"}
1024 * is provided in preference to a ({@code long}) constructor
1025 * because it allows for reuse of frequently used
1026 * {@code BigDecimal} values.
1027 *
1028 * @param val value of the {@code BigDecimal}.
1029 * @return a {@code BigDecimal} whose value is {@code val}.
1030 */
1031 public static BigDecimal valueOf(long val) {
1032 if (val >= 0 && val < zeroThroughTen.length)
1033 return zeroThroughTen[(int)val];
1034 else if (val != INFLATED)
1035 return new BigDecimal(null, val, 0, 0);
1036 return new BigDecimal(BigInteger.valueOf(val), val, 0, 0);
1037 }
1038
1039 /**
1040 * Translates a {@code double} into a {@code BigDecimal}, using
1041 * the {@code double}'s canonical string representation provided
1042 * by the {@link Double#toString(double)} method.
1043 *
1044 * <p><b>Note:</b> This is generally the preferred way to convert
1045 * a {@code double} (or {@code float}) into a
1046 * {@code BigDecimal}, as the value returned is equal to that
1047 * resulting from constructing a {@code BigDecimal} from the
1048 * result of using {@link Double#toString(double)}.
1049 *
1050 * @param val {@code double} to convert to a {@code BigDecimal}.
1051 * @return a {@code BigDecimal} whose value is equal to or approximately
1052 * equal to the value of {@code val}.
1053 * @throws NumberFormatException if {@code val} is infinite or NaN.
1054 * @since 1.5
1055 */
1056 public static BigDecimal valueOf(double val) {
1057 // Reminder: a zero double returns '0.0', so we cannot fastpath
1058 // to use the constant ZERO. This might be important enough to
1059 // justify a factory approach, a cache, or a few private
1060 // constants, later.
1061 return new BigDecimal(Double.toString(val));
1062 }
1063
1064 // Arithmetic Operations
1065 /**
1066 * Returns a {@code BigDecimal} whose value is {@code (this +
1067 * augend)}, and whose scale is {@code max(this.scale(),
1068 * augend.scale())}.
1069 *
1070 * @param augend value to be added to this {@code BigDecimal}.
1071 * @return {@code this + augend}
1072 */
1073 public BigDecimal add(BigDecimal augend) {
1074 long xs = this.intCompact;
1075 long ys = augend.intCompact;
1076 BigInteger fst = this.intVal;
1077 BigInteger snd = augend.intVal;
1078 int rscale = this.scale;
1079
1080 long sdiff = (long)rscale - augend.scale;
1081 if (sdiff != 0) {
1082 if (sdiff < 0) {
1083 int raise = checkScale(-sdiff);
1084 rscale = augend.scale;
1085 if (xs == INFLATED ||
1086 (xs = longMultiplyPowerTen(xs, raise)) == INFLATED)
1087 fst = bigMultiplyPowerTen(raise);
1088 } else {
1089 int raise = augend.checkScale(sdiff);
1090 if (ys == INFLATED ||
1091 (ys = longMultiplyPowerTen(ys, raise)) == INFLATED)
1092 snd = augend.bigMultiplyPowerTen(raise);
1093 }
1094 }
1095 if (xs != INFLATED && ys != INFLATED) {
1096 long sum = xs + ys;
1097 // See "Hacker's Delight" section 2-12 for explanation of
1098 // the overflow test.
1099 if ( (((sum ^ xs) & (sum ^ ys))) >= 0L) // not overflowed
1100 return new BigDecimal(null, sum, rscale, 0);
1101 }
1102 if (fst == null)
1103 fst = BigInteger.valueOf(xs);
1104 if (snd == null)
1105 snd = BigInteger.valueOf(ys);
1106 BigInteger sum = fst.add(snd);
1107 return (fst.signum == snd.signum) ?
1108 new BigDecimal(sum, INFLATED, rscale, 0) :
1109 new BigDecimal(sum, compactValFor(sum), rscale, 0);
1110 }
1111
1112 /**
1113 * Returns a {@code BigDecimal} whose value is {@code (this + augend)},
1114 * with rounding according to the context settings.
1115 *
1116 * If either number is zero and the precision setting is nonzero then
1117 * the other number, rounded if necessary, is used as the result.
1118 *
1119 * @param augend value to be added to this {@code BigDecimal}.
1120 * @param mc the context to use.
1121 * @return {@code this + augend}, rounded as necessary.
1122 * @throws ArithmeticException if the result is inexact but the
1123 * rounding mode is {@code UNNECESSARY}.
1124 * @since 1.5
1125 */
1126 public BigDecimal add(BigDecimal augend, MathContext mc) {
1127 if (mc.precision == 0)
1128 return add(augend);
1129 BigDecimal lhs = this;
1130
1131 // Could optimize if values are compact
1132 this.inflate();
1133 augend.inflate();
1134
1135 // If either number is zero then the other number, rounded and
1136 // scaled if necessary, is used as the result.
1137 {
1138 boolean lhsIsZero = lhs.signum() == 0;
1139 boolean augendIsZero = augend.signum() == 0;
1140
1141 if (lhsIsZero || augendIsZero) {
1142 int preferredScale = Math.max(lhs.scale(), augend.scale());
1143 BigDecimal result;
1144
1145 // Could use a factory for zero instead of a new object
1146 if (lhsIsZero && augendIsZero)
1147 return new BigDecimal(BigInteger.ZERO, 0, preferredScale, 0);
1148
1149 result = lhsIsZero ? doRound(augend, mc) : doRound(lhs, mc);
1150
1151 if (result.scale() == preferredScale)
1152 return result;
1153 else if (result.scale() > preferredScale) {
1154 BigDecimal scaledResult =
1155 new BigDecimal(result.intVal, result.intCompact,
1156 result.scale, 0);
1157 scaledResult.stripZerosToMatchScale(preferredScale);
1158 return scaledResult;
1159 } else { // result.scale < preferredScale
1160 int precisionDiff = mc.precision - result.precision();
1161 int scaleDiff = preferredScale - result.scale();
1162
1163 if (precisionDiff >= scaleDiff)
1164 return result.setScale(preferredScale); // can achieve target scale
1165 else
1166 return result.setScale(result.scale() + precisionDiff);
1167 }
1168 }
1169 }
1170
1171 long padding = (long)lhs.scale - augend.scale;
1172 if (padding != 0) { // scales differ; alignment needed
1173 BigDecimal arg[] = preAlign(lhs, augend, padding, mc);
1174 matchScale(arg);
1175 lhs = arg[0];
1176 augend = arg[1];
1177 }
1178
1179 BigDecimal d = new BigDecimal(lhs.inflate().add(augend.inflate()),
1180 lhs.scale);
1181 return doRound(d, mc);
1182 }
1183
1184 /**
1185 * Returns an array of length two, the sum of whose entries is
1186 * equal to the rounded sum of the {@code BigDecimal} arguments.
1187 *
1188 * <p>If the digit positions of the arguments have a sufficient
1189 * gap between them, the value smaller in magnitude can be
1190 * condensed into a {@literal "sticky bit"} and the end result will
1191 * round the same way <em>if</em> the precision of the final
1192 * result does not include the high order digit of the small
1193 * magnitude operand.
1194 *
1195 * <p>Note that while strictly speaking this is an optimization,
1196 * it makes a much wider range of additions practical.
1197 *
1198 * <p>This corresponds to a pre-shift operation in a fixed
1199 * precision floating-point adder; this method is complicated by
1200 * variable precision of the result as determined by the
1201 * MathContext. A more nuanced operation could implement a
1239 smallHighDigitPos > estResultUlpScale + 2) { // small digits not visible
1240 small = BigDecimal.valueOf(small.signum(),
1241 this.checkScale(Math.max(big.scale, estResultUlpScale) + 3));
1242 }
1243
1244 // Since addition is symmetric, preserving input order in
1245 // returned operands doesn't matter
1246 BigDecimal[] result = {big, small};
1247 return result;
1248 }
1249
1250 /**
1251 * Returns a {@code BigDecimal} whose value is {@code (this -
1252 * subtrahend)}, and whose scale is {@code max(this.scale(),
1253 * subtrahend.scale())}.
1254 *
1255 * @param subtrahend value to be subtracted from this {@code BigDecimal}.
1256 * @return {@code this - subtrahend}
1257 */
1258 public BigDecimal subtract(BigDecimal subtrahend) {
1259 return add(subtrahend.negate());
1260 }
1261
1262 /**
1263 * Returns a {@code BigDecimal} whose value is {@code (this - subtrahend)},
1264 * with rounding according to the context settings.
1265 *
1266 * If {@code subtrahend} is zero then this, rounded if necessary, is used as the
1267 * result. If this is zero then the result is {@code subtrahend.negate(mc)}.
1268 *
1269 * @param subtrahend value to be subtracted from this {@code BigDecimal}.
1270 * @param mc the context to use.
1271 * @return {@code this - subtrahend}, rounded as necessary.
1272 * @throws ArithmeticException if the result is inexact but the
1273 * rounding mode is {@code UNNECESSARY}.
1274 * @since 1.5
1275 */
1276 public BigDecimal subtract(BigDecimal subtrahend, MathContext mc) {
1277 BigDecimal nsubtrahend = subtrahend.negate();
1278 if (mc.precision == 0)
1279 return add(nsubtrahend);
1280 // share the special rounding code in add()
1281 return add(nsubtrahend, mc);
1282 }
1283
1284 /**
1285 * Returns a {@code BigDecimal} whose value is <tt>(this ×
1286 * multiplicand)</tt>, and whose scale is {@code (this.scale() +
1287 * multiplicand.scale())}.
1288 *
1289 * @param multiplicand value to be multiplied by this {@code BigDecimal}.
1290 * @return {@code this * multiplicand}
1291 */
1292 public BigDecimal multiply(BigDecimal multiplicand) {
1293 long x = this.intCompact;
1294 long y = multiplicand.intCompact;
1295 int productScale = checkScale((long)scale + multiplicand.scale);
1296
1297 // Might be able to do a more clever check incorporating the
1298 // inflated check into the overflow computation.
1299 if (x != INFLATED && y != INFLATED) {
1300 /*
1301 * If the product is not an overflowed value, continue
1302 * to use the compact representation. if either of x or y
1303 * is INFLATED, the product should also be regarded as
1304 * an overflow. Before using the overflow test suggested in
1305 * "Hacker's Delight" section 2-12, we perform quick checks
1306 * using the precision information to see whether the overflow
1307 * would occur since division is expensive on most CPUs.
1308 */
1309 long product = x * y;
1310 int prec = this.precision() + multiplicand.precision();
1311 if (prec < 19 || (prec < 21 && (y == 0 || product / y == x)))
1312 return new BigDecimal(null, product, productScale, 0);
1313 return new BigDecimal(BigInteger.valueOf(x).multiply(y), INFLATED,
1314 productScale, 0);
1315 }
1316 BigInteger rb;
1317 if (x == INFLATED && y == INFLATED)
1318 rb = this.intVal.multiply(multiplicand.intVal);
1319 else if (x != INFLATED)
1320 rb = multiplicand.intVal.multiply(x);
1321 else
1322 rb = this.intVal.multiply(y);
1323 return new BigDecimal(rb, INFLATED, productScale, 0);
1324 }
1325
1326 /**
1327 * Returns a {@code BigDecimal} whose value is <tt>(this ×
1328 * multiplicand)</tt>, with rounding according to the context settings.
1329 *
1330 * @param multiplicand value to be multiplied by this {@code BigDecimal}.
1331 * @param mc the context to use.
1332 * @return {@code this * multiplicand}, rounded as necessary.
1333 * @throws ArithmeticException if the result is inexact but the
1334 * rounding mode is {@code UNNECESSARY}.
1335 * @since 1.5
1336 */
1337 public BigDecimal multiply(BigDecimal multiplicand, MathContext mc) {
1338 if (mc.precision == 0)
1339 return multiply(multiplicand);
1340 return doRound(this.multiply(multiplicand), mc);
1341 }
1342
1343 /**
1344 * Returns a {@code BigDecimal} whose value is {@code (this /
1345 * divisor)}, and whose scale is as specified. If rounding must
1346 * be performed to generate a result with the specified scale, the
1347 * specified rounding mode is applied.
1348 *
1349 * <p>The new {@link #divide(BigDecimal, int, RoundingMode)} method
1350 * should be used in preference to this legacy method.
1351 *
1352 * @param divisor value by which this {@code BigDecimal} is to be divided.
1353 * @param scale scale of the {@code BigDecimal} quotient to be returned.
1354 * @param roundingMode rounding mode to apply.
1355 * @return {@code this / divisor}
1356 * @throws ArithmeticException if {@code divisor} is zero,
1357 * {@code roundingMode==ROUND_UNNECESSARY} and
1358 * the specified scale is insufficient to represent the result
1359 * of the division exactly.
1360 * @throws IllegalArgumentException if {@code roundingMode} does not
1361 * represent a valid rounding mode.
1362 * @see #ROUND_UP
1363 * @see #ROUND_DOWN
1364 * @see #ROUND_CEILING
1365 * @see #ROUND_FLOOR
1366 * @see #ROUND_HALF_UP
1367 * @see #ROUND_HALF_DOWN
1368 * @see #ROUND_HALF_EVEN
1369 * @see #ROUND_UNNECESSARY
1370 */
1371 public BigDecimal divide(BigDecimal divisor, int scale, int roundingMode) {
1372 /*
1373 * IMPLEMENTATION NOTE: This method *must* return a new object
1374 * since divideAndRound uses divide to generate a value whose
1375 * scale is then modified.
1376 */
1377 if (roundingMode < ROUND_UP || roundingMode > ROUND_UNNECESSARY)
1378 throw new IllegalArgumentException("Invalid rounding mode");
1379 /*
1380 * Rescale dividend or divisor (whichever can be "upscaled" to
1381 * produce correctly scaled quotient).
1382 * Take care to detect out-of-range scales
1383 */
1384 BigDecimal dividend = this;
1385 if (checkScale((long)scale + divisor.scale) > this.scale)
1386 dividend = this.setScale(scale + divisor.scale, ROUND_UNNECESSARY);
1387 else
1388 divisor = divisor.setScale(checkScale((long)this.scale - scale),
1389 ROUND_UNNECESSARY);
1390 return divideAndRound(dividend.intCompact, dividend.intVal,
1391 divisor.intCompact, divisor.intVal,
1392 scale, roundingMode, scale);
1393 }
1394
1395 /**
1396 * Internally used for division operation. The dividend and divisor are
1397 * passed both in {@code long} format and {@code BigInteger} format. The
1398 * returned {@code BigDecimal} object is the quotient whose scale is set to
1399 * the passed in scale. If the remainder is not zero, it will be rounded
1400 * based on the passed in roundingMode. Also, if the remainder is zero and
1401 * the last parameter, i.e. preferredScale is NOT equal to scale, the
1402 * trailing zeros of the result is stripped to match the preferredScale.
1403 */
1404 private static BigDecimal divideAndRound(long ldividend, BigInteger bdividend,
1405 long ldivisor, BigInteger bdivisor,
1406 int scale, int roundingMode,
1407 int preferredScale) {
1408 boolean isRemainderZero; // record remainder is zero or not
1409 int qsign; // quotient sign
1410 long q = 0, r = 0; // store quotient & remainder in long
1411 MutableBigInteger mq = null; // store quotient
1412 MutableBigInteger mr = null; // store remainder
1413 MutableBigInteger mdivisor = null;
1414 boolean isLongDivision = (ldividend != INFLATED && ldivisor != INFLATED);
1415 if (isLongDivision) {
1416 q = ldividend / ldivisor;
1417 if (roundingMode == ROUND_DOWN && scale == preferredScale)
1418 return new BigDecimal(null, q, scale, 0);
1419 r = ldividend % ldivisor;
1420 isRemainderZero = (r == 0);
1421 qsign = ((ldividend < 0) == (ldivisor < 0)) ? 1 : -1;
1422 } else {
1423 if (bdividend == null)
1424 bdividend = BigInteger.valueOf(ldividend);
1425 // Descend into mutables for faster remainder checks
1426 MutableBigInteger mdividend = new MutableBigInteger(bdividend.mag);
1427 mq = new MutableBigInteger();
1428 if (ldivisor != INFLATED) {
1429 r = mdividend.divide(ldivisor, mq);
1430 isRemainderZero = (r == 0);
1431 qsign = (ldivisor < 0) ? -bdividend.signum : bdividend.signum;
1432 } else {
1433 mdivisor = new MutableBigInteger(bdivisor.mag);
1434 mr = mdividend.divide(mdivisor, mq);
1435 isRemainderZero = mr.isZero();
1436 qsign = (bdividend.signum != bdivisor.signum) ? -1 : 1;
1437 }
1438 }
1439 boolean increment = false;
1440 if (!isRemainderZero) {
1441 int cmpFracHalf;
1442 /* Round as appropriate */
1443 if (roundingMode == ROUND_UNNECESSARY) { // Rounding prohibited
1444 throw new ArithmeticException("Rounding necessary");
1445 } else if (roundingMode == ROUND_UP) { // Away from zero
1446 increment = true;
1447 } else if (roundingMode == ROUND_DOWN) { // Towards zero
1448 increment = false;
1449 } else if (roundingMode == ROUND_CEILING) { // Towards +infinity
1450 increment = (qsign > 0);
1451 } else if (roundingMode == ROUND_FLOOR) { // Towards -infinity
1452 increment = (qsign < 0);
1453 } else {
1454 if (isLongDivision || ldivisor != INFLATED)
1455 cmpFracHalf = longCompareMagnitude(2 * r, ldivisor);
1456 else
1457 cmpFracHalf = mr.compareHalf(mdivisor);
1458 if (cmpFracHalf < 0)
1459 increment = false; // We're closer to higher digit
1460 else if (cmpFracHalf > 0) // We're closer to lower digit
1461 increment = true;
1462 else if (roundingMode == ROUND_HALF_UP)
1463 increment = true;
1464 else if (roundingMode == ROUND_HALF_DOWN)
1465 increment = false;
1466 else // roundingMode == ROUND_HALF_EVEN, true iff quotient is odd
1467 increment = isLongDivision ? (q & 1L) != 0L : mq.isOdd();
1468 }
1469 }
1470 BigDecimal res;
1471 if (isLongDivision)
1472 res = new BigDecimal(null, (increment ? q + qsign : q), scale, 0);
1473 else {
1474 if (increment)
1475 mq.add(MutableBigInteger.ONE);
1476 res = mq.toBigDecimal(qsign, scale);
1477 }
1478 if (isRemainderZero && preferredScale != scale)
1479 res.stripZerosToMatchScale(preferredScale);
1480 return res;
1481 }
1482
1483 /**
1484 * Returns a {@code BigDecimal} whose value is {@code (this /
1485 * divisor)}, and whose scale is as specified. If rounding must
1486 * be performed to generate a result with the specified scale, the
1487 * specified rounding mode is applied.
1488 *
1489 * @param divisor value by which this {@code BigDecimal} is to be divided.
1490 * @param scale scale of the {@code BigDecimal} quotient to be returned.
1491 * @param roundingMode rounding mode to apply.
1492 * @return {@code this / divisor}
1493 * @throws ArithmeticException if {@code divisor} is zero,
1494 * {@code roundingMode==RoundingMode.UNNECESSARY} and
1495 * the specified scale is insufficient to represent the result
1496 * of the division exactly.
1497 * @since 1.5
1498 */
1499 public BigDecimal divide(BigDecimal divisor, int scale, RoundingMode roundingMode) {
1500 return divide(divisor, scale, roundingMode.oldMode);
1558 * expansion) an {@code ArithmeticException} is thrown.
1559 *
1560 * @param divisor value by which this {@code BigDecimal} is to be divided.
1561 * @throws ArithmeticException if the exact quotient does not have a
1562 * terminating decimal expansion
1563 * @return {@code this / divisor}
1564 * @since 1.5
1565 * @author Joseph D. Darcy
1566 */
1567 public BigDecimal divide(BigDecimal divisor) {
1568 /*
1569 * Handle zero cases first.
1570 */
1571 if (divisor.signum() == 0) { // x/0
1572 if (this.signum() == 0) // 0/0
1573 throw new ArithmeticException("Division undefined"); // NaN
1574 throw new ArithmeticException("Division by zero");
1575 }
1576
1577 // Calculate preferred scale
1578 int preferredScale = saturateLong((long)this.scale - divisor.scale);
1579 if (this.signum() == 0) // 0/y
1580 return (preferredScale >= 0 &&
1581 preferredScale < ZERO_SCALED_BY.length) ?
1582 ZERO_SCALED_BY[preferredScale] :
1583 new BigDecimal(null, 0, preferredScale, 1);
1584 else {
1585 this.inflate();
1586 divisor.inflate();
1587 /*
1588 * If the quotient this/divisor has a terminating decimal
1589 * expansion, the expansion can have no more than
1590 * (a.precision() + ceil(10*b.precision)/3) digits.
1591 * Therefore, create a MathContext object with this
1592 * precision and do a divide with the UNNECESSARY rounding
1593 * mode.
1594 */
1595 MathContext mc = new MathContext( (int)Math.min(this.precision() +
1596 (long)Math.ceil(10.0*divisor.precision()/3.0),
1597 Integer.MAX_VALUE),
1598 RoundingMode.UNNECESSARY);
1599 BigDecimal quotient;
1600 try {
1601 quotient = this.divide(divisor, mc);
1602 } catch (ArithmeticException e) {
1603 throw new ArithmeticException("Non-terminating decimal expansion; " +
1604 "no exact representable decimal result.");
1605 }
1606
1607 int quotientScale = quotient.scale();
1608
1609 // divide(BigDecimal, mc) tries to adjust the quotient to
1610 // the desired one by removing trailing zeros; since the
1611 // exact divide method does not have an explicit digit
1612 // limit, we can add zeros too.
1613
1614 if (preferredScale > quotientScale)
1615 return quotient.setScale(preferredScale, ROUND_UNNECESSARY);
1616
1617 return quotient;
1618 }
1619 }
1620
1621 /**
1622 * Returns a {@code BigDecimal} whose value is {@code (this /
1623 * divisor)}, with rounding according to the context settings.
1624 *
1625 * @param divisor value by which this {@code BigDecimal} is to be divided.
1626 * @param mc the context to use.
1627 * @return {@code this / divisor}, rounded as necessary.
1628 * @throws ArithmeticException if the result is inexact but the
1629 * rounding mode is {@code UNNECESSARY} or
1630 * {@code mc.precision == 0} and the quotient has a
1631 * non-terminating decimal expansion.
1632 * @since 1.5
1633 */
1634 public BigDecimal divide(BigDecimal divisor, MathContext mc) {
1635 int mcp = mc.precision;
1636 if (mcp == 0)
1637 return divide(divisor);
1638
1639 BigDecimal dividend = this;
1640 long preferredScale = (long)dividend.scale - divisor.scale;
1641 // Now calculate the answer. We use the existing
1642 // divide-and-round method, but as this rounds to scale we have
1643 // to normalize the values here to achieve the desired result.
1644 // For x/y we first handle y=0 and x=0, and then normalize x and
1645 // y to give x' and y' with the following constraints:
1646 // (a) 0.1 <= x' < 1
1647 // (b) x' <= y' < 10*x'
1648 // Dividing x'/y' with the required scale set to mc.precision then
1649 // will give a result in the range 0.1 to 1 rounded to exactly
1650 // the right number of digits (except in the case of a result of
1651 // 1.000... which can arise when x=y, or when rounding overflows
1652 // The 1.000... case will reduce properly to 1.
1653 if (divisor.signum() == 0) { // x/0
1654 if (dividend.signum() == 0) // 0/0
1655 throw new ArithmeticException("Division undefined"); // NaN
1656 throw new ArithmeticException("Division by zero");
1657 }
1658 if (dividend.signum() == 0) // 0/y
1659 return new BigDecimal(BigInteger.ZERO, 0,
1660 saturateLong(preferredScale), 1);
1661
1662 // Normalize dividend & divisor so that both fall into [0.1, 0.999...]
1663 int xscale = dividend.precision();
1664 int yscale = divisor.precision();
1665 dividend = new BigDecimal(dividend.intVal, dividend.intCompact,
1666 xscale, xscale);
1667 divisor = new BigDecimal(divisor.intVal, divisor.intCompact,
1668 yscale, yscale);
1669 if (dividend.compareMagnitude(divisor) > 0) // satisfy constraint (b)
1670 yscale = divisor.scale -= 1; // [that is, divisor *= 10]
1671
1672 // In order to find out whether the divide generates the exact result,
1673 // we avoid calling the above divide method. 'quotient' holds the
1674 // return BigDecimal object whose scale will be set to 'scl'.
1675 BigDecimal quotient;
1676 int scl = checkScale(preferredScale + yscale - xscale + mcp);
1677 if (checkScale((long)mcp + yscale) > xscale)
1678 dividend = dividend.setScale(mcp + yscale, ROUND_UNNECESSARY);
1679 else
1680 divisor = divisor.setScale(checkScale((long)xscale - mcp),
1681 ROUND_UNNECESSARY);
1682 quotient = divideAndRound(dividend.intCompact, dividend.intVal,
1683 divisor.intCompact, divisor.intVal,
1684 scl, mc.roundingMode.oldMode,
1685 checkScale(preferredScale));
1686 // doRound, here, only affects 1000000000 case.
1687 quotient = doRound(quotient, mc);
1688
1689 return quotient;
1690 }
1691
1692 /**
1693 * Returns a {@code BigDecimal} whose value is the integer part
1694 * of the quotient {@code (this / divisor)} rounded down. The
1695 * preferred scale of the result is {@code (this.scale() -
1696 * divisor.scale())}.
1697 *
1698 * @param divisor value by which this {@code BigDecimal} is to be divided.
1699 * @return The integer part of {@code this / divisor}.
1700 * @throws ArithmeticException if {@code divisor==0}
1701 * @since 1.5
1702 */
1703 public BigDecimal divideToIntegralValue(BigDecimal divisor) {
1704 // Calculate preferred scale
1705 int preferredScale = saturateLong((long)this.scale - divisor.scale);
1706 if (this.compareMagnitude(divisor) < 0) {
1707 // much faster when this << divisor
1708 return BigDecimal.valueOf(0, preferredScale);
1709 }
1710
1711 if(this.signum() == 0 && divisor.signum() != 0)
1712 return this.setScale(preferredScale, ROUND_UNNECESSARY);
1713
1714 // Perform a divide with enough digits to round to a correct
1715 // integer value; then remove any fractional digits
1716
1717 int maxDigits = (int)Math.min(this.precision() +
1718 (long)Math.ceil(10.0*divisor.precision()/3.0) +
1719 Math.abs((long)this.scale() - divisor.scale()) + 2,
1720 Integer.MAX_VALUE);
1721 BigDecimal quotient = this.divide(divisor, new MathContext(maxDigits,
1722 RoundingMode.DOWN));
1723 if (quotient.scale > 0) {
1724 quotient = quotient.setScale(0, RoundingMode.DOWN);
1725 quotient.stripZerosToMatchScale(preferredScale);
1726 }
1727
1728 if (quotient.scale < preferredScale) {
1729 // pad with zeros if necessary
1730 quotient = quotient.setScale(preferredScale, ROUND_UNNECESSARY);
1731 }
1732 return quotient;
1733 }
1734
1735 /**
1736 * Returns a {@code BigDecimal} whose value is the integer part
1737 * of {@code (this / divisor)}. Since the integer part of the
1738 * exact quotient does not depend on the rounding mode, the
1739 * rounding mode does not affect the values returned by this
1740 * method. The preferred scale of the result is
1741 * {@code (this.scale() - divisor.scale())}. An
1742 * {@code ArithmeticException} is thrown if the integer part of
1743 * the exact quotient needs more than {@code mc.precision}
1744 * digits.
1745 *
1746 * @param divisor value by which this {@code BigDecimal} is to be divided.
1747 * @param mc the context to use.
1748 * @return The integer part of {@code this / divisor}.
1749 * @throws ArithmeticException if {@code divisor==0}
1750 * @throws ArithmeticException if {@code mc.precision} {@literal >} 0 and the result
1751 * requires a precision of more than {@code mc.precision} digits.
1752 * @since 1.5
1753 * @author Joseph D. Darcy
1754 */
1755 public BigDecimal divideToIntegralValue(BigDecimal divisor, MathContext mc) {
1756 if (mc.precision == 0 || // exact result
1757 (this.compareMagnitude(divisor) < 0) ) // zero result
1758 return divideToIntegralValue(divisor);
1759
1760 // Calculate preferred scale
1761 int preferredScale = saturateLong((long)this.scale - divisor.scale);
1762
1763 /*
1764 * Perform a normal divide to mc.precision digits. If the
1765 * remainder has absolute value less than the divisor, the
1766 * integer portion of the quotient fits into mc.precision
1767 * digits. Next, remove any fractional digits from the
1768 * quotient and adjust the scale to the preferred value.
1769 */
1770 BigDecimal result = this.
1771 divide(divisor, new MathContext(mc.precision, RoundingMode.DOWN));
1772
1773 if (result.scale() < 0) {
1774 /*
1775 * Result is an integer. See if quotient represents the
1776 * full integer portion of the exact quotient; if it does,
1777 * the computed remainder will be less than the divisor.
1778 */
1779 BigDecimal product = result.multiply(divisor);
1780 // If the quotient is the full integer value,
1781 // |dividend-product| < |divisor|.
1782 if (this.subtract(product).compareMagnitude(divisor) >= 0) {
1783 throw new ArithmeticException("Division impossible");
1784 }
1785 } else if (result.scale() > 0) {
1786 /*
1787 * Integer portion of quotient will fit into precision
1788 * digits; recompute quotient to scale 0 to avoid double
1789 * rounding and then try to adjust, if necessary.
1790 */
1791 result = result.setScale(0, RoundingMode.DOWN);
1792 }
1793 // else result.scale() == 0;
1794
1795 int precisionDiff;
1796 if ((preferredScale > result.scale()) &&
1797 (precisionDiff = mc.precision - result.precision()) > 0) {
1798 return result.setScale(result.scale() +
1799 Math.min(precisionDiff, preferredScale - result.scale) );
1800 } else {
1801 result.stripZerosToMatchScale(preferredScale);
1802 return result;
1803 }
1804 }
1805
1806 /**
1807 * Returns a {@code BigDecimal} whose value is {@code (this % divisor)}.
1808 *
1809 * <p>The remainder is given by
1810 * {@code this.subtract(this.divideToIntegralValue(divisor).multiply(divisor))}.
1811 * Note that this is not the modulo operation (the result can be
1812 * negative).
1813 *
1814 * @param divisor value by which this {@code BigDecimal} is to be divided.
1815 * @return {@code this % divisor}.
1816 * @throws ArithmeticException if {@code divisor==0}
1817 * @since 1.5
1818 */
1819 public BigDecimal remainder(BigDecimal divisor) {
1820 BigDecimal divrem[] = this.divideAndRemainder(divisor);
1821 return divrem[1];
1822 }
1823
1824
1992 * @return <tt>this<sup>n</sup></tt> using the ANSI standard X3.274-1996
1993 * algorithm
1994 * @throws ArithmeticException if the result is inexact but the
1995 * rounding mode is {@code UNNECESSARY}, or {@code n} is out
1996 * of range.
1997 * @since 1.5
1998 */
1999 public BigDecimal pow(int n, MathContext mc) {
2000 if (mc.precision == 0)
2001 return pow(n);
2002 if (n < -999999999 || n > 999999999)
2003 throw new ArithmeticException("Invalid operation");
2004 if (n == 0)
2005 return ONE; // x**0 == 1 in X3.274
2006 this.inflate();
2007 BigDecimal lhs = this;
2008 MathContext workmc = mc; // working settings
2009 int mag = Math.abs(n); // magnitude of n
2010 if (mc.precision > 0) {
2011
2012 int elength = longDigitLength(mag); // length of n in digits
2013 if (elength > mc.precision) // X3.274 rule
2014 throw new ArithmeticException("Invalid operation");
2015 workmc = new MathContext(mc.precision + elength + 1,
2016 mc.roundingMode);
2017 }
2018 // ready to carry out power calculation...
2019 BigDecimal acc = ONE; // accumulator
2020 boolean seenbit = false; // set once we've seen a 1-bit
2021 for (int i=1;;i++) { // for each bit [top bit ignored]
2022 mag += mag; // shift left 1 bit
2023 if (mag < 0) { // top bit is set
2024 seenbit = true; // OK, we're off
2025 acc = acc.multiply(lhs, workmc); // acc=acc*x
2026 }
2027 if (i == 31)
2028 break; // that was the last bit
2029 if (seenbit)
2030 acc=acc.multiply(acc, workmc); // acc=acc*acc [square]
2031 // else (!seenbit) no point in squaring ONE
2032 }
2033 // if negative n, calculate the reciprocal using working precision
2034 if (n<0) // [hence mc.precision>0]
2035 acc=ONE.divide(acc, workmc);
2036 // round to final precision and strip zeros
2037 return doRound(acc, mc);
2038 }
2039
2040 /**
2041 * Returns a {@code BigDecimal} whose value is the absolute value
2042 * of this {@code BigDecimal}, and whose scale is
2043 * {@code this.scale()}.
2044 *
2045 * @return {@code abs(this)}
2046 */
2047 public BigDecimal abs() {
2048 return (signum() < 0 ? negate() : this);
2049 }
2050
2051 /**
2052 * Returns a {@code BigDecimal} whose value is the absolute value
2053 * of this {@code BigDecimal}, with rounding according to the
2054 * context settings.
2055 *
2056 * @param mc the context to use.
2057 * @return {@code abs(this)}, rounded as necessary.
2111 }
2112
2113 /**
2114 * Returns a {@code BigDecimal} whose value is {@code (+this)},
2115 * with rounding according to the context settings.
2116 *
2117 * <p>The effect of this method is identical to that of the {@link
2118 * #round(MathContext)} method.
2119 *
2120 * @param mc the context to use.
2121 * @return {@code this}, rounded as necessary. A zero result will
2122 * have a scale of 0.
2123 * @throws ArithmeticException if the result is inexact but the
2124 * rounding mode is {@code UNNECESSARY}.
2125 * @see #round(MathContext)
2126 * @since 1.5
2127 */
2128 public BigDecimal plus(MathContext mc) {
2129 if (mc.precision == 0) // no rounding please
2130 return this;
2131 return doRound(this, mc);
2132 }
2133
2134 /**
2135 * Returns the signum function of this {@code BigDecimal}.
2136 *
2137 * @return -1, 0, or 1 as the value of this {@code BigDecimal}
2138 * is negative, zero, or positive.
2139 */
2140 public int signum() {
2141 return (intCompact != INFLATED)?
2142 Long.signum(intCompact):
2143 intVal.signum();
2144 }
2145
2146 /**
2147 * Returns the <i>scale</i> of this {@code BigDecimal}. If zero
2148 * or positive, the scale is the number of digits to the right of
2149 * the decimal point. If negative, the unscaled value of the
2150 * number is multiplied by ten to the power of the negation of the
2151 * scale. For example, a scale of {@code -3} means the unscaled
2152 * value is multiplied by 1000.
2153 *
2154 * @return the scale of this {@code BigDecimal}.
2155 */
2156 public int scale() {
2157 return scale;
2158 }
2159
2160 /**
2161 * Returns the <i>precision</i> of this {@code BigDecimal}. (The
2162 * precision is the number of digits in the unscaled value.)
2163 *
2164 * <p>The precision of a zero value is 1.
2165 *
2166 * @return the precision of this {@code BigDecimal}.
2167 * @since 1.5
2168 */
2169 public int precision() {
2170 int result = precision;
2171 if (result == 0) {
2172 long s = intCompact;
2173 if (s != INFLATED)
2174 result = longDigitLength(s);
2175 else
2176 result = bigDigitLength(inflate());
2177 precision = result;
2178 }
2179 return result;
2180 }
2181
2182
2183 /**
2184 * Returns a {@code BigInteger} whose value is the <i>unscaled
2185 * value</i> of this {@code BigDecimal}. (Computes <tt>(this *
2186 * 10<sup>this.scale()</sup>)</tt>.)
2187 *
2188 * @return the unscaled value of this {@code BigDecimal}.
2189 * @since 1.2
2190 */
2191 public BigInteger unscaledValue() {
2192 return this.inflate();
2193 }
2194
2195 // Rounding Modes
2196
2197 /**
2198 * Rounding mode to round away from zero. Always increments the
2199 * digit prior to a nonzero discarded fraction. Note that this rounding
2200 * mode never decreases the magnitude of the calculated value.
2201 */
2202 public final static int ROUND_UP = 0;
2203
2204 /**
2205 * Rounding mode to round towards zero. Never increments the digit
2206 * prior to a discarded fraction (i.e., truncates). Note that this
2207 * rounding mode never increases the magnitude of the calculated value.
2208 */
2209 public final static int ROUND_DOWN = 1;
2210
2211 /**
2212 * Rounding mode to round towards positive infinity. If the
2349 * dividing this {@code BigDecimal}'s unscaled value by the
2350 * appropriate power of ten to maintain its overall value.
2351 * @throws ArithmeticException if {@code roundingMode==ROUND_UNNECESSARY}
2352 * and the specified scaling operation would require
2353 * rounding.
2354 * @throws IllegalArgumentException if {@code roundingMode} does not
2355 * represent a valid rounding mode.
2356 * @see #ROUND_UP
2357 * @see #ROUND_DOWN
2358 * @see #ROUND_CEILING
2359 * @see #ROUND_FLOOR
2360 * @see #ROUND_HALF_UP
2361 * @see #ROUND_HALF_DOWN
2362 * @see #ROUND_HALF_EVEN
2363 * @see #ROUND_UNNECESSARY
2364 */
2365 public BigDecimal setScale(int newScale, int roundingMode) {
2366 if (roundingMode < ROUND_UP || roundingMode > ROUND_UNNECESSARY)
2367 throw new IllegalArgumentException("Invalid rounding mode");
2368
2369 int oldScale = this.scale;
2370 if (newScale == oldScale) // easy case
2371 return this;
2372 if (this.signum() == 0) // zero can have any scale
2373 return BigDecimal.valueOf(0, newScale);
2374
2375 long rs = this.intCompact;
2376 if (newScale > oldScale) {
2377 int raise = checkScale((long)newScale - oldScale);
2378 BigInteger rb = null;
2379 if (rs == INFLATED ||
2380 (rs = longMultiplyPowerTen(rs, raise)) == INFLATED)
2381 rb = bigMultiplyPowerTen(raise);
2382 return new BigDecimal(rb, rs, newScale,
2383 (precision > 0) ? precision + raise : 0);
2384 } else {
2385 // newScale < oldScale -- drop some digits
2386 // Can't predict the precision due to the effect of rounding.
2387 int drop = checkScale((long)oldScale - newScale);
2388 if (drop < LONG_TEN_POWERS_TABLE.length)
2389 return divideAndRound(rs, this.intVal,
2390 LONG_TEN_POWERS_TABLE[drop], null,
2391 newScale, roundingMode, newScale);
2392 else
2393 return divideAndRound(rs, this.intVal,
2394 INFLATED, bigTenToThe(drop),
2395 newScale, roundingMode, newScale);
2396 }
2397 }
2398
2399 /**
2400 * Returns a {@code BigDecimal} whose scale is the specified
2401 * value, and whose value is numerically equal to this
2402 * {@code BigDecimal}'s. Throws an {@code ArithmeticException}
2403 * if this is not possible.
2404 *
2405 * <p>This call is typically used to increase the scale, in which
2406 * case it is guaranteed that there exists a {@code BigDecimal}
2407 * of the specified scale and the correct value. The call can
2408 * also be used to reduce the scale if the caller knows that the
2409 * {@code BigDecimal} has sufficiently many zeros at the end of
2410 * its fractional part (i.e., factors of ten in its integer value)
2411 * to allow for the rescaling without changing its value.
2412 *
2413 * <p>This method returns the same result as the two-argument
2414 * versions of {@code setScale}, but saves the caller the trouble
2415 * of specifying a rounding mode in cases where it is irrelevant.
2416 *
2417 * <p>Note that since {@code BigDecimal} objects are immutable,
2439 // Decimal Point Motion Operations
2440
2441 /**
2442 * Returns a {@code BigDecimal} which is equivalent to this one
2443 * with the decimal point moved {@code n} places to the left. If
2444 * {@code n} is non-negative, the call merely adds {@code n} to
2445 * the scale. If {@code n} is negative, the call is equivalent
2446 * to {@code movePointRight(-n)}. The {@code BigDecimal}
2447 * returned by this call has value <tt>(this ×
2448 * 10<sup>-n</sup>)</tt> and scale {@code max(this.scale()+n,
2449 * 0)}.
2450 *
2451 * @param n number of places to move the decimal point to the left.
2452 * @return a {@code BigDecimal} which is equivalent to this one with the
2453 * decimal point moved {@code n} places to the left.
2454 * @throws ArithmeticException if scale overflows.
2455 */
2456 public BigDecimal movePointLeft(int n) {
2457 // Cannot use movePointRight(-n) in case of n==Integer.MIN_VALUE
2458 int newScale = checkScale((long)scale + n);
2459 BigDecimal num = new BigDecimal(intVal, intCompact, newScale, 0);
2460 return num.scale < 0 ? num.setScale(0, ROUND_UNNECESSARY) : num;
2461 }
2462
2463 /**
2464 * Returns a {@code BigDecimal} which is equivalent to this one
2465 * with the decimal point moved {@code n} places to the right.
2466 * If {@code n} is non-negative, the call merely subtracts
2467 * {@code n} from the scale. If {@code n} is negative, the call
2468 * is equivalent to {@code movePointLeft(-n)}. The
2469 * {@code BigDecimal} returned by this call has value <tt>(this
2470 * × 10<sup>n</sup>)</tt> and scale {@code max(this.scale()-n,
2471 * 0)}.
2472 *
2473 * @param n number of places to move the decimal point to the right.
2474 * @return a {@code BigDecimal} which is equivalent to this one
2475 * with the decimal point moved {@code n} places to the right.
2476 * @throws ArithmeticException if scale overflows.
2477 */
2478 public BigDecimal movePointRight(int n) {
2479 // Cannot use movePointLeft(-n) in case of n==Integer.MIN_VALUE
2480 int newScale = checkScale((long)scale - n);
2481 BigDecimal num = new BigDecimal(intVal, intCompact, newScale, 0);
2482 return num.scale < 0 ? num.setScale(0, ROUND_UNNECESSARY) : num;
2483 }
2484
2485 /**
2486 * Returns a BigDecimal whose numerical value is equal to
2487 * ({@code this} * 10<sup>n</sup>). The scale of
2488 * the result is {@code (this.scale() - n)}.
2489 *
2490 * @throws ArithmeticException if the scale would be
2491 * outside the range of a 32-bit integer.
2492 *
2493 * @since 1.5
2494 */
2495 public BigDecimal scaleByPowerOfTen(int n) {
2496 return new BigDecimal(intVal, intCompact,
2497 checkScale((long)scale - n), precision);
2498 }
2499
2500 /**
2501 * Returns a {@code BigDecimal} which is numerically equal to
2502 * this one but with any trailing zeros removed from the
2503 * representation. For example, stripping the trailing zeros from
2504 * the {@code BigDecimal} value {@code 600.0}, which has
2505 * [{@code BigInteger}, {@code scale}] components equals to
2506 * [6000, 1], yields {@code 6E2} with [{@code BigInteger},
2507 * {@code scale}] components equals to [6, -2]
2508 *
2509 * @return a numerically equal {@code BigDecimal} with any
2510 * trailing zeros removed.
2511 * @since 1.5
2512 */
2513 public BigDecimal stripTrailingZeros() {
2514 this.inflate();
2515 BigDecimal result = new BigDecimal(intVal, scale);
2516 result.stripZerosToMatchScale(Long.MIN_VALUE);
2517 return result;
2518 }
2519
2520 // Comparison Operations
2521
2522 /**
2523 * Compares this {@code BigDecimal} with the specified
2524 * {@code BigDecimal}. Two {@code BigDecimal} objects that are
2525 * equal in value but have a different scale (like 2.0 and 2.00)
2526 * are considered equal by this method. This method is provided
2527 * in preference to individual methods for each of the six boolean
2528 * comparison operators ({@literal <}, ==,
2529 * {@literal >}, {@literal >=}, !=, {@literal <=}). The
2530 * suggested idiom for performing these comparisons is:
2531 * {@code (x.compareTo(y)} <<i>op</i>> {@code 0)}, where
2532 * <<i>op</i>> is one of the six comparison operators.
2533 *
2534 * @param val {@code BigDecimal} to which this {@code BigDecimal} is
2535 * to be compared.
2536 * @return -1, 0, or 1 as this {@code BigDecimal} is numerically
2537 * less than, equal to, or greater than {@code val}.
2538 */
2539 public int compareTo(BigDecimal val) {
2540 // Quick path for equal scale and non-inflated case.
2541 if (scale == val.scale) {
2542 long xs = intCompact;
2543 long ys = val.intCompact;
2544 if (xs != INFLATED && ys != INFLATED)
2545 return xs != ys ? ((xs > ys) ? 1 : -1) : 0;
2546 }
2547 int xsign = this.signum();
2548 int ysign = val.signum();
2549 if (xsign != ysign)
2550 return (xsign > ysign) ? 1 : -1;
2551 if (xsign == 0)
2552 return 0;
2553 int cmp = compareMagnitude(val);
2554 return (xsign > 0) ? cmp : -cmp;
2555 }
2556
2557 /**
2558 * Version of compareTo that ignores sign.
2559 */
2560 private int compareMagnitude(BigDecimal val) {
2561 // Match scales, avoid unnecessary inflation
2562 long ys = val.intCompact;
2563 long xs = this.intCompact;
2564 if (xs == 0)
2565 return (ys == 0) ? 0 : -1;
2566 if (ys == 0)
2567 return 1;
2568
2569 int sdiff = this.scale - val.scale;
2570 if (sdiff != 0) {
2571 // Avoid matching scales if the (adjusted) exponents differ
2572 int xae = this.precision() - this.scale; // [-1]
2573 int yae = val.precision() - val.scale; // [-1]
2574 if (xae < yae)
2575 return -1;
2576 if (xae > yae)
2577 return 1;
2578 BigInteger rb = null;
2579 if (sdiff < 0) {
2580 if ( (xs == INFLATED ||
2581 (xs = longMultiplyPowerTen(xs, -sdiff)) == INFLATED) &&
2582 ys == INFLATED) {
2583 rb = bigMultiplyPowerTen(-sdiff);
2584 return rb.compareMagnitude(val.intVal);
2585 }
2586 } else { // sdiff > 0
2587 if ( (ys == INFLATED ||
2588 (ys = longMultiplyPowerTen(ys, sdiff)) == INFLATED) &&
2589 xs == INFLATED) {
2590 rb = val.bigMultiplyPowerTen(sdiff);
2591 return this.intVal.compareMagnitude(rb);
2592 }
2593 }
2594 }
2595 if (xs != INFLATED)
2596 return (ys != INFLATED) ? longCompareMagnitude(xs, ys) : -1;
2597 else if (ys != INFLATED)
2598 return 1;
2599 else
2600 return this.intVal.compareMagnitude(val.intVal);
2601 }
2602
2603 /**
2604 * Compares this {@code BigDecimal} with the specified
2605 * {@code Object} for equality. Unlike {@link
2606 * #compareTo(BigDecimal) compareTo}, this method considers two
2607 * {@code BigDecimal} objects equal only if they are equal in
2608 * value and scale (thus 2.0 is not equal to 2.00 when compared by
2609 * this method).
2610 *
2611 * @param x {@code Object} to which this {@code BigDecimal} is
2612 * to be compared.
2613 * @return {@code true} if and only if the specified {@code Object} is a
2614 * {@code BigDecimal} whose value and scale are equal to this
2615 * {@code BigDecimal}'s.
2616 * @see #compareTo(java.math.BigDecimal)
2617 * @see #hashCode
2618 */
2619 @Override
2620 public boolean equals(Object x) {
2621 if (!(x instanceof BigDecimal))
2622 return false;
2623 BigDecimal xDec = (BigDecimal) x;
2624 if (x == this)
2625 return true;
2626 if (scale != xDec.scale)
2627 return false;
2628 long s = this.intCompact;
2629 long xs = xDec.intCompact;
2630 if (s != INFLATED) {
2631 if (xs == INFLATED)
2632 xs = compactValFor(xDec.intVal);
2633 return xs == s;
2634 } else if (xs != INFLATED)
2635 return xs == compactValFor(this.intVal);
2636
2637 return this.inflate().equals(xDec.inflate());
2638 }
2639
2640 /**
2641 * Returns the minimum of this {@code BigDecimal} and
2642 * {@code val}.
2643 *
2644 * @param val value with which the minimum is to be computed.
2645 * @return the {@code BigDecimal} whose value is the lesser of this
2646 * {@code BigDecimal} and {@code val}. If they are equal,
2647 * as defined by the {@link #compareTo(BigDecimal) compareTo}
2648 * method, {@code this} is returned.
2649 * @see #compareTo(java.math.BigDecimal)
2650 */
2651 public BigDecimal min(BigDecimal val) {
2652 return (compareTo(val) <= 0 ? this : val);
2653 }
2654
2655 /**
2656 * Returns the maximum of this {@code BigDecimal} and {@code val}.
2657 *
2660 * {@code BigDecimal} and {@code val}. If they are equal,
2661 * as defined by the {@link #compareTo(BigDecimal) compareTo}
2662 * method, {@code this} is returned.
2663 * @see #compareTo(java.math.BigDecimal)
2664 */
2665 public BigDecimal max(BigDecimal val) {
2666 return (compareTo(val) >= 0 ? this : val);
2667 }
2668
2669 // Hash Function
2670
2671 /**
2672 * Returns the hash code for this {@code BigDecimal}. Note that
2673 * two {@code BigDecimal} objects that are numerically equal but
2674 * differ in scale (like 2.0 and 2.00) will generally <i>not</i>
2675 * have the same hash code.
2676 *
2677 * @return hash code for this {@code BigDecimal}.
2678 * @see #equals(Object)
2679 */
2680 @Override
2681 public int hashCode() {
2682 if (intCompact != INFLATED) {
2683 long val2 = (intCompact < 0)? -intCompact : intCompact;
2684 int temp = (int)( ((int)(val2 >>> 32)) * 31 +
2685 (val2 & LONG_MASK));
2686 return 31*((intCompact < 0) ?-temp:temp) + scale;
2687 } else
2688 return 31*intVal.hashCode() + scale;
2689 }
2690
2691 // Format Converters
2692
2693 /**
2694 * Returns the string representation of this {@code BigDecimal},
2695 * using scientific notation if an exponent is needed.
2696 *
2697 * <p>A standard canonical string form of the {@code BigDecimal}
2698 * is created as though by the following steps: first, the
2699 * absolute value of the unscaled value of the {@code BigDecimal}
2700 * is converted to a string in base ten using the characters
2701 * {@code '0'} through {@code '9'} with no leading zeros (except
2702 * if its value is zero, in which case a single {@code '0'}
2703 * character is used).
2704 *
2705 * <p>Next, an <i>adjusted exponent</i> is calculated; this is the
2772 * as a canonical string representation for exchanging decimal
2773 * data, or as a key for a Hashtable, etc. Locale-sensitive
2774 * number formatting and parsing is handled by the {@link
2775 * java.text.NumberFormat} class and its subclasses.
2776 *
2777 * <li>The {@link #toEngineeringString} method may be used for
2778 * presenting numbers with exponents in engineering notation, and the
2779 * {@link #setScale(int,RoundingMode) setScale} method may be used for
2780 * rounding a {@code BigDecimal} so it has a known number of digits after
2781 * the decimal point.
2782 *
2783 * <li>The digit-to-character mapping provided by
2784 * {@code Character.forDigit} is used.
2785 *
2786 * </ol>
2787 *
2788 * @return string representation of this {@code BigDecimal}.
2789 * @see Character#forDigit
2790 * @see #BigDecimal(java.lang.String)
2791 */
2792 @Override
2793 public String toString() {
2794 String sc = stringCache;
2795 if (sc == null)
2796 stringCache = sc = layoutChars(true);
2797 return sc;
2798 }
2799
2800 /**
2801 * Returns a string representation of this {@code BigDecimal},
2802 * using engineering notation if an exponent is needed.
2803 *
2804 * <p>Returns a string that represents the {@code BigDecimal} as
2805 * described in the {@link #toString()} method, except that if
2806 * exponential notation is used, the power of ten is adjusted to
2807 * be a multiple of three (engineering notation) such that the
2808 * integer part of nonzero values will be in the range 1 through
2809 * 999. If exponential notation is used for zero values, a
2810 * decimal point and one or two fractional zero digits are used so
2811 * that the scale of the zero value is preserved. Note that
2812 * unlike the output of {@link #toString()}, the output of this
2813 * method is <em>not</em> guaranteed to recover the same [integer,
2814 * scale] pair of this {@code BigDecimal} if the output string is
2815 * converting back to a {@code BigDecimal} using the {@linkplain
2816 * #BigDecimal(String) string constructor}. The result of this method meets
2817 * the weaker constraint of always producing a numerically equal
2893 /**
2894 * Converts this {@code BigDecimal} to a {@code BigInteger}.
2895 * This conversion is analogous to a <a
2896 * href="http://java.sun.com/docs/books/jls/second_edition/html/conversions.doc.html#25363"><i>narrowing
2897 * primitive conversion</i></a> from {@code double} to
2898 * {@code long} as defined in the <a
2899 * href="http://java.sun.com/docs/books/jls/html/">Java Language
2900 * Specification</a>: any fractional part of this
2901 * {@code BigDecimal} will be discarded. Note that this
2902 * conversion can lose information about the precision of the
2903 * {@code BigDecimal} value.
2904 * <p>
2905 * To have an exception thrown if the conversion is inexact (in
2906 * other words if a nonzero fractional part is discarded), use the
2907 * {@link #toBigIntegerExact()} method.
2908 *
2909 * @return this {@code BigDecimal} converted to a {@code BigInteger}.
2910 */
2911 public BigInteger toBigInteger() {
2912 // force to an integer, quietly
2913 return this.setScale(0, ROUND_DOWN).inflate();
2914 }
2915
2916 /**
2917 * Converts this {@code BigDecimal} to a {@code BigInteger},
2918 * checking for lost information. An exception is thrown if this
2919 * {@code BigDecimal} has a nonzero fractional part.
2920 *
2921 * @return this {@code BigDecimal} converted to a {@code BigInteger}.
2922 * @throws ArithmeticException if {@code this} has a nonzero
2923 * fractional part.
2924 * @since 1.5
2925 */
2926 public BigInteger toBigIntegerExact() {
2927 // round to an integer, with Exception if decimal part non-0
2928 return this.setScale(0, ROUND_UNNECESSARY).inflate();
2929 }
2930
2931 /**
2932 * Converts this {@code BigDecimal} to a {@code long}. This
2933 * conversion is analogous to a <a
2934 * href="http://java.sun.com/docs/books/jls/second_edition/html/conversions.doc.html#25363"><i>narrowing
2935 * primitive conversion</i></a> from {@code double} to
2936 * {@code short} as defined in the <a
2937 * href="http://java.sun.com/docs/books/jls/html/">Java Language
2938 * Specification</a>: any fractional part of this
2939 * {@code BigDecimal} will be discarded, and if the resulting
2940 * "{@code BigInteger}" is too big to fit in a
2941 * {@code long}, only the low-order 64 bits are returned.
2942 * Note that this conversion can lose information about the
2943 * overall magnitude and precision of this {@code BigDecimal} value as well
2944 * as return a result with the opposite sign.
2945 *
2946 * @return this {@code BigDecimal} converted to a {@code long}.
2947 */
2948 public long longValue(){
2959 * thrown.
2960 *
2961 * @return this {@code BigDecimal} converted to a {@code long}.
2962 * @throws ArithmeticException if {@code this} has a nonzero
2963 * fractional part, or will not fit in a {@code long}.
2964 * @since 1.5
2965 */
2966 public long longValueExact() {
2967 if (intCompact != INFLATED && scale == 0)
2968 return intCompact;
2969 // If more than 19 digits in integer part it cannot possibly fit
2970 if ((precision() - scale) > 19) // [OK for negative scale too]
2971 throw new java.lang.ArithmeticException("Overflow");
2972 // Fastpath zero and < 1.0 numbers (the latter can be very slow
2973 // to round if very small)
2974 if (this.signum() == 0)
2975 return 0;
2976 if ((this.precision() - this.scale) <= 0)
2977 throw new ArithmeticException("Rounding necessary");
2978 // round to an integer, with Exception if decimal part non-0
2979 BigDecimal num = this.setScale(0, ROUND_UNNECESSARY);
2980 if (num.precision() >= 19) // need to check carefully
2981 LongOverflow.check(num);
2982 return num.inflate().longValue();
2983 }
2984
2985 private static class LongOverflow {
2986 /** BigInteger equal to Long.MIN_VALUE. */
2987 private static final BigInteger LONGMIN = BigInteger.valueOf(Long.MIN_VALUE);
2988
2989 /** BigInteger equal to Long.MAX_VALUE. */
2990 private static final BigInteger LONGMAX = BigInteger.valueOf(Long.MAX_VALUE);
2991
2992 public static void check(BigDecimal num) {
2993 num.inflate();
2994 if ((num.intVal.compareTo(LONGMIN) < 0) ||
2995 (num.intVal.compareTo(LONGMAX) > 0))
2996 throw new java.lang.ArithmeticException("Overflow");
2997 }
2998 }
2999
3000 /**
3001 * Converts this {@code BigDecimal} to an {@code int}. This
3002 * conversion is analogous to a <a
3003 * href="http://java.sun.com/docs/books/jls/second_edition/html/conversions.doc.html#25363"><i>narrowing
3004 * primitive conversion</i></a> from {@code double} to
3005 * {@code short} as defined in the <a
3006 * href="http://java.sun.com/docs/books/jls/html/">Java Language
3007 * Specification</a>: any fractional part of this
3008 * {@code BigDecimal} will be discarded, and if the resulting
3009 * "{@code BigInteger}" is too big to fit in an
3010 * {@code int}, only the low-order 32 bits are returned.
3011 * Note that this conversion can lose information about the
3012 * overall magnitude and precision of this {@code BigDecimal}
3013 * value as well as return a result with the opposite sign.
3129 }
3130
3131 /**
3132 * Returns the size of an ulp, a unit in the last place, of this
3133 * {@code BigDecimal}. An ulp of a nonzero {@code BigDecimal}
3134 * value is the positive distance between this value and the
3135 * {@code BigDecimal} value next larger in magnitude with the
3136 * same number of digits. An ulp of a zero value is numerically
3137 * equal to 1 with the scale of {@code this}. The result is
3138 * stored with the same scale as {@code this} so the result
3139 * for zero and nonzero values is equal to {@code [1,
3140 * this.scale()]}.
3141 *
3142 * @return the size of an ulp of {@code this}
3143 * @since 1.5
3144 */
3145 public BigDecimal ulp() {
3146 return BigDecimal.valueOf(1, this.scale());
3147 }
3148
3149
3150 // Private class to build a string representation for BigDecimal object.
3151 // "StringBuilderHelper" is constructed as a thread local variable so it is
3152 // thread safe. The StringBuilder field acts as a buffer to hold the temporary
3153 // representation of BigDecimal. The cmpCharArray holds all the characters for
3154 // the compact representation of BigDecimal (except for '-' sign' if it is
3155 // negative) if its intCompact field is not INFLATED. It is shared by all
3156 // calls to toString() and its variants in that particular thread.
3157 static class StringBuilderHelper {
3158 final StringBuilder sb; // Placeholder for BigDecimal string
3159 final char[] cmpCharArray; // character array to place the intCompact
3160
3161 StringBuilderHelper() {
3162 sb = new StringBuilder();
3163 // All non negative longs can be made to fit into 19 character array.
3164 cmpCharArray = new char[19];
3165 }
3166
3167 // Accessors.
3168 StringBuilder getStringBuilder() {
3169 sb.setLength(0);
3170 return sb;
3171 }
3172
3173 char[] getCompactCharArray() {
3174 return cmpCharArray;
3175 }
3176
3177 /**
3178 * Places characters representing the intCompact in {@code long} into
3179 * cmpCharArray and returns the offset to the array where the
3180 * representation starts.
3181 *
3182 * @param intCompact the number to put into the cmpCharArray.
3183 * @return offset to the array where the representation starts.
3184 * Note: intCompact must be greater or equal to zero.
3185 */
3186 int putIntCompact(long intCompact) {
3187 assert intCompact >= 0;
3188
3189 long q;
3190 int r;
3191 // since we start from the least significant digit, charPos points to
3192 // the last character in cmpCharArray.
3193 int charPos = cmpCharArray.length;
3194
3195 // Get 2 digits/iteration using longs until quotient fits into an int
3196 while (intCompact > Integer.MAX_VALUE) {
3197 q = intCompact / 100;
3198 r = (int)(intCompact - q * 100);
3199 intCompact = q;
3200 cmpCharArray[--charPos] = DIGIT_ONES[r];
3201 cmpCharArray[--charPos] = DIGIT_TENS[r];
3202 }
3203
3204 // Get 2 digits/iteration using ints when i2 >= 100
3205 int q2;
3206 int i2 = (int)intCompact;
3207 while (i2 >= 100) {
3208 q2 = i2 / 100;
3209 r = i2 - q2 * 100;
3210 i2 = q2;
3211 cmpCharArray[--charPos] = DIGIT_ONES[r];
3212 cmpCharArray[--charPos] = DIGIT_TENS[r];
3213 }
3214
3215 cmpCharArray[--charPos] = DIGIT_ONES[i2];
3216 if (i2 >= 10)
3217 cmpCharArray[--charPos] = DIGIT_TENS[i2];
3218
3219 return charPos;
3220 }
3221
3222 final static char[] DIGIT_TENS = {
3223 '0', '0', '0', '0', '0', '0', '0', '0', '0', '0',
3224 '1', '1', '1', '1', '1', '1', '1', '1', '1', '1',
3225 '2', '2', '2', '2', '2', '2', '2', '2', '2', '2',
3226 '3', '3', '3', '3', '3', '3', '3', '3', '3', '3',
3227 '4', '4', '4', '4', '4', '4', '4', '4', '4', '4',
3228 '5', '5', '5', '5', '5', '5', '5', '5', '5', '5',
3229 '6', '6', '6', '6', '6', '6', '6', '6', '6', '6',
3230 '7', '7', '7', '7', '7', '7', '7', '7', '7', '7',
3231 '8', '8', '8', '8', '8', '8', '8', '8', '8', '8',
3232 '9', '9', '9', '9', '9', '9', '9', '9', '9', '9',
3233 };
3234
3235 final static char[] DIGIT_ONES = {
3236 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
3237 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
3238 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
3239 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
3240 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
3241 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
3242 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
3243 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
3244 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
3245 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
3246 };
3247 }
3248
3249 /**
3250 * Lay out this {@code BigDecimal} into a {@code char[]} array.
3251 * The Java 1.2 equivalent to this was called {@code getValueString}.
3252 *
3253 * @param sci {@code true} for Scientific exponential notation;
3254 * {@code false} for Engineering
3255 * @return string with canonical string representation of this
3256 * {@code BigDecimal}
3257 */
3258 private String layoutChars(boolean sci) {
3259 if (scale == 0) // zero scale is trivial
3260 return (intCompact != INFLATED) ?
3261 Long.toString(intCompact):
3262 intVal.toString();
3263
3264 StringBuilderHelper sbHelper = threadLocalStringBuilderHelper.get();
3265 char[] coeff;
3266 int offset; // offset is the starting index for coeff array
3267 // Get the significand as an absolute value
3268 if (intCompact != INFLATED) {
3269 offset = sbHelper.putIntCompact(Math.abs(intCompact));
3270 coeff = sbHelper.getCompactCharArray();
3271 } else {
3272 offset = 0;
3273 coeff = intVal.abs().toString().toCharArray();
3274 }
3275
3276 // Construct a buffer, with sufficient capacity for all cases.
3277 // If E-notation is needed, length will be: +1 if negative, +1
3278 // if '.' needed, +2 for "E+", + up to 10 for adjusted exponent.
3279 // Otherwise it could have +1 if negative, plus leading "0.00000"
3280 StringBuilder buf = sbHelper.getStringBuilder();
3281 if (signum() < 0) // prefix '-' if negative
3282 buf.append('-');
3283 int coeffLen = coeff.length - offset;
3284 long adjusted = -(long)scale + (coeffLen -1);
3285 if ((scale >= 0) && (adjusted >= -6)) { // plain number
3286 int pad = scale - coeffLen; // count of padding zeros
3287 if (pad >= 0) { // 0.xxx form
3288 buf.append('0');
3289 buf.append('.');
3290 for (; pad>0; pad--) {
3291 buf.append('0');
3292 }
3293 buf.append(coeff, offset, coeffLen);
3294 } else { // xx.xx form
3295 buf.append(coeff, offset, -pad);
3296 buf.append('.');
3297 buf.append(coeff, -pad + offset, scale);
3298 }
3299 } else { // E-notation is needed
3300 if (sci) { // Scientific notation
3301 buf.append(coeff[offset]); // first character
3302 if (coeffLen > 1) { // more to come
3303 buf.append('.');
3304 buf.append(coeff, offset + 1, coeffLen - 1);
3305 }
3306 } else { // Engineering notation
3307 int sig = (int)(adjusted % 3);
3308 if (sig < 0)
3309 sig += 3; // [adjusted was negative]
3310 adjusted -= sig; // now a multiple of 3
3311 sig++;
3312 if (signum() == 0) {
3313 switch (sig) {
3314 case 1:
3315 buf.append('0'); // exponent is a multiple of three
3316 break;
3317 case 2:
3318 buf.append("0.00");
3319 adjusted += 3;
3320 break;
3321 case 3:
3322 buf.append("0.0");
3323 adjusted += 3;
3324 break;
3325 default:
3326 throw new AssertionError("Unexpected sig value " + sig);
3327 }
3328 } else if (sig >= coeffLen) { // significand all in integer
3329 buf.append(coeff, offset, coeffLen);
3330 // may need some zeros, too
3331 for (int i = sig - coeffLen; i > 0; i--)
3332 buf.append('0');
3333 } else { // xx.xxE form
3334 buf.append(coeff, offset, sig);
3335 buf.append('.');
3336 buf.append(coeff, offset + sig, coeffLen - sig);
3337 }
3338 }
3339 if (adjusted != 0) { // [!sci could have made 0]
3340 buf.append('E');
3341 if (adjusted > 0) // force sign for positive
3342 buf.append('+');
3343 buf.append(adjusted);
3344 }
3345 }
3346 return buf.toString();
3347 }
3348
3349 /**
3350 * Return 10 to the power n, as a {@code BigInteger}.
3351 *
3352 * @param n the power of ten to be returned (>=0)
3353 * @return a {@code BigInteger} with the value (10<sup>n</sup>)
3354 */
3355 private static BigInteger bigTenToThe(int n) {
3356 if (n < 0)
3357 return BigInteger.ZERO;
3358
3359 if (n < BIG_TEN_POWERS_TABLE_MAX) {
3360 BigInteger[] pows = BIG_TEN_POWERS_TABLE;
3361 if (n < pows.length)
3362 return pows[n];
3363 else
3364 return expandBigIntegerTenPowers(n);
3365 }
3366 // BigInteger.pow is slow, so make 10**n by constructing a
3367 // BigInteger from a character string (still not very fast)
3368 char tenpow[] = new char[n + 1];
3369 tenpow[0] = '1';
3370 for (int i = 1; i <= n; i++)
3371 tenpow[i] = '0';
3372 return new BigInteger(tenpow);
3373 }
3374
3375 /**
3376 * Expand the BIG_TEN_POWERS_TABLE array to contain at least 10**n.
3377 *
3378 * @param n the power of ten to be returned (>=0)
3379 * @return a {@code BigDecimal} with the value (10<sup>n</sup>) and
3380 * in the meantime, the BIG_TEN_POWERS_TABLE array gets
3381 * expanded to the size greater than n.
3382 */
3383 private static BigInteger expandBigIntegerTenPowers(int n) {
3384 synchronized(BigDecimal.class) {
3385 BigInteger[] pows = BIG_TEN_POWERS_TABLE;
3386 int curLen = pows.length;
3387 // The following comparison and the above synchronized statement is
3388 // to prevent multiple threads from expanding the same array.
3389 if (curLen <= n) {
3390 int newLen = curLen << 1;
3391 while (newLen <= n)
3392 newLen <<= 1;
3393 pows = Arrays.copyOf(pows, newLen);
3394 for (int i = curLen; i < newLen; i++)
3395 pows[i] = pows[i - 1].multiply(BigInteger.TEN);
3396 // Based on the following facts:
3397 // 1. pows is a private local varible;
3398 // 2. the following store is a volatile store.
3399 // the newly created array elements can be safely published.
3400 BIG_TEN_POWERS_TABLE = pows;
3401 }
3402 return pows[n];
3403 }
3404 }
3405
3406 private static final long[] LONG_TEN_POWERS_TABLE = {
3407 1, // 0 / 10^0
3408 10, // 1 / 10^1
3409 100, // 2 / 10^2
3410 1000, // 3 / 10^3
3411 10000, // 4 / 10^4
3412 100000, // 5 / 10^5
3413 1000000, // 6 / 10^6
3414 10000000, // 7 / 10^7
3415 100000000, // 8 / 10^8
3416 1000000000, // 9 / 10^9
3417 10000000000L, // 10 / 10^10
3418 100000000000L, // 11 / 10^11
3419 1000000000000L, // 12 / 10^12
3420 10000000000000L, // 13 / 10^13
3421 100000000000000L, // 14 / 10^14
3422 1000000000000000L, // 15 / 10^15
3423 10000000000000000L, // 16 / 10^16
3424 100000000000000000L, // 17 / 10^17
3425 1000000000000000000L // 18 / 10^18
3426 };
3427
3428 private static volatile BigInteger BIG_TEN_POWERS_TABLE[] = {BigInteger.ONE,
3429 BigInteger.valueOf(10), BigInteger.valueOf(100),
3430 BigInteger.valueOf(1000), BigInteger.valueOf(10000),
3431 BigInteger.valueOf(100000), BigInteger.valueOf(1000000),
3432 BigInteger.valueOf(10000000), BigInteger.valueOf(100000000),
3433 BigInteger.valueOf(1000000000),
3434 BigInteger.valueOf(10000000000L),
3435 BigInteger.valueOf(100000000000L),
3436 BigInteger.valueOf(1000000000000L),
3437 BigInteger.valueOf(10000000000000L),
3438 BigInteger.valueOf(100000000000000L),
3439 BigInteger.valueOf(1000000000000000L),
3440 BigInteger.valueOf(10000000000000000L),
3441 BigInteger.valueOf(100000000000000000L),
3442 BigInteger.valueOf(1000000000000000000L)
3443 };
3444
3445 private static final int BIG_TEN_POWERS_TABLE_INITLEN =
3446 BIG_TEN_POWERS_TABLE.length;
3447 private static final int BIG_TEN_POWERS_TABLE_MAX =
3448 16 * BIG_TEN_POWERS_TABLE_INITLEN;
3449
3450 private static final long THRESHOLDS_TABLE[] = {
3451 Long.MAX_VALUE, // 0
3452 Long.MAX_VALUE/10L, // 1
3453 Long.MAX_VALUE/100L, // 2
3454 Long.MAX_VALUE/1000L, // 3
3455 Long.MAX_VALUE/10000L, // 4
3456 Long.MAX_VALUE/100000L, // 5
3457 Long.MAX_VALUE/1000000L, // 6
3458 Long.MAX_VALUE/10000000L, // 7
3459 Long.MAX_VALUE/100000000L, // 8
3460 Long.MAX_VALUE/1000000000L, // 9
3461 Long.MAX_VALUE/10000000000L, // 10
3462 Long.MAX_VALUE/100000000000L, // 11
3463 Long.MAX_VALUE/1000000000000L, // 12
3464 Long.MAX_VALUE/10000000000000L, // 13
3465 Long.MAX_VALUE/100000000000000L, // 14
3466 Long.MAX_VALUE/1000000000000000L, // 15
3467 Long.MAX_VALUE/10000000000000000L, // 16
3468 Long.MAX_VALUE/100000000000000000L, // 17
3469 Long.MAX_VALUE/1000000000000000000L // 18
3470 };
3471
3472 /**
3473 * Compute val * 10 ^ n; return this product if it is
3474 * representable as a long, INFLATED otherwise.
3475 */
3476 private static long longMultiplyPowerTen(long val, int n) {
3477 if (val == 0 || n <= 0)
3478 return val;
3479 long[] tab = LONG_TEN_POWERS_TABLE;
3480 long[] bounds = THRESHOLDS_TABLE;
3481 if (n < tab.length && n < bounds.length) {
3482 long tenpower = tab[n];
3483 if (val == 1)
3484 return tenpower;
3485 if (Math.abs(val) <= bounds[n])
3486 return val * tenpower;
3487 }
3488 return INFLATED;
3489 }
3490
3491 /**
3492 * Compute this * 10 ^ n.
3493 * Needed mainly to allow special casing to trap zero value
3494 */
3495 private BigInteger bigMultiplyPowerTen(int n) {
3496 if (n <= 0)
3497 return this.inflate();
3498
3499 if (intCompact != INFLATED)
3500 return bigTenToThe(n).multiply(intCompact);
3501 else
3502 return intVal.multiply(bigTenToThe(n));
3503 }
3504
3505 /**
3506 * Assign appropriate BigInteger to intVal field if intVal is
3507 * null, i.e. the compact representation is in use.
3508 */
3509 private BigInteger inflate() {
3510 if (intVal == null)
3511 intVal = BigInteger.valueOf(intCompact);
3512 return intVal;
3513 }
3514
3515 /**
3516 * Match the scales of two {@code BigDecimal}s to align their
3517 * least significant digits.
3518 *
3519 * <p>If the scales of val[0] and val[1] differ, rescale
3520 * (non-destructively) the lower-scaled {@code BigDecimal} so
3521 * they match. That is, the lower-scaled reference will be
3522 * replaced by a reference to a new object with the same scale as
3523 * the other {@code BigDecimal}.
3524 *
3525 * @param val array of two elements referring to the two
3526 * {@code BigDecimal}s to be aligned.
3527 */
3528 private static void matchScale(BigDecimal[] val) {
3529 if (val[0].scale == val[1].scale) {
3530 return;
3531 } else if (val[0].scale < val[1].scale) {
3532 val[0] = val[0].setScale(val[1].scale, ROUND_UNNECESSARY);
3533 } else if (val[1].scale < val[0].scale) {
3534 val[1] = val[1].setScale(val[0].scale, ROUND_UNNECESSARY);
3535 }
3536 }
3537
3538 /**
3539 * Reconstitute the {@code BigDecimal} instance from a stream (that is,
3540 * deserialize it).
3541 *
3542 * @param s the stream being read.
3543 */
3544 private void readObject(java.io.ObjectInputStream s)
3545 throws java.io.IOException, ClassNotFoundException {
3546 // Read in all fields
3547 s.defaultReadObject();
3548 // validate possibly bad fields
3549 if (intVal == null) {
3550 String message = "BigDecimal: null intVal in stream";
3551 throw new java.io.StreamCorruptedException(message);
3552 // [all values of scale are now allowed]
3553 }
3554 intCompact = compactValFor(intVal);
3555 }
3556
3557 /**
3558 * Serialize this {@code BigDecimal} to the stream in question
3559 *
3560 * @param s the stream to serialize to.
3561 */
3562 private void writeObject(java.io.ObjectOutputStream s)
3563 throws java.io.IOException {
3564 // Must inflate to maintain compatible serial form.
3565 this.inflate();
3566
3567 // Write proper fields
3568 s.defaultWriteObject();
3569 }
3570
3571
3572 /**
3573 * Returns the length of the absolute value of a {@code long}, in decimal
3574 * digits.
3575 *
3576 * @param x the {@code long}
3577 * @return the length of the unscaled value, in deciaml digits.
3578 */
3579 private static int longDigitLength(long x) {
3580 /*
3581 * As described in "Bit Twiddling Hacks" by Sean Anderson,
3582 * (http://graphics.stanford.edu/~seander/bithacks.html)
3583 * integer log 10 of x is within 1 of
3584 * (1233/4096)* (1 + integer log 2 of x).
3585 * The fraction 1233/4096 approximates log10(2). So we first
3586 * do a version of log2 (a variant of Long class with
3587 * pre-checks and opposite directionality) and then scale and
3588 * check against powers table. This is a little simpler in
3589 * present context than the version in Hacker's Delight sec
3590 * 11-4. Adding one to bit length allows comparing downward
3591 * from the LONG_TEN_POWERS_TABLE that we need anyway.
3592 */
3593 assert x != INFLATED;
3594 if (x < 0)
3595 x = -x;
3596 if (x < 10) // must screen for 0, might as well 10
3597 return 1;
3598 int n = 64; // not 63, to avoid needing to add 1 later
3599 int y = (int)(x >>> 32);
3600 if (y == 0) { n -= 32; y = (int)x; }
3601 if (y >>> 16 == 0) { n -= 16; y <<= 16; }
3602 if (y >>> 24 == 0) { n -= 8; y <<= 8; }
3603 if (y >>> 28 == 0) { n -= 4; y <<= 4; }
3604 if (y >>> 30 == 0) { n -= 2; y <<= 2; }
3605 int r = (((y >>> 31) + n) * 1233) >>> 12;
3606 long[] tab = LONG_TEN_POWERS_TABLE;
3607 // if r >= length, must have max possible digits for long
3608 return (r >= tab.length || x < tab[r])? r : r+1;
3609 }
3610
3611 /**
3612 * Returns the length of the absolute value of a BigInteger, in
3613 * decimal digits.
3614 *
3615 * @param b the BigInteger
3616 * @return the length of the unscaled value, in decimal digits
3617 */
3618 private static int bigDigitLength(BigInteger b) {
3619 /*
3620 * Same idea as the long version, but we need a better
3621 * approximation of log10(2). Using 646456993/2^31
3622 * is accurate up to max possible reported bitLength.
3623 */
3624 if (b.signum == 0)
3625 return 1;
3626 int r = (int)((((long)b.bitLength() + 1) * 646456993) >>> 31);
3627 return b.compareMagnitude(bigTenToThe(r)) < 0? r : r+1;
3628 }
3629
3630
3631 /**
3632 * Remove insignificant trailing zeros from this
3633 * {@code BigDecimal} until the preferred scale is reached or no
3634 * more zeros can be removed. If the preferred scale is less than
3635 * Integer.MIN_VALUE, all the trailing zeros will be removed.
3636 *
3637 * {@code BigInteger} assistance could help, here?
3638 *
3639 * <p>WARNING: This method should only be called on new objects as
3640 * it mutates the value fields.
3641 *
3642 * @return this {@code BigDecimal} with a scale possibly reduced
3643 * to be closed to the preferred scale.
3644 */
3645 private BigDecimal stripZerosToMatchScale(long preferredScale) {
3646 boolean compact = (intCompact != INFLATED);
3647 this.inflate();
3648 BigInteger qr[]; // quotient-remainder pair
3649 while ( intVal.compareMagnitude(BigInteger.TEN) >= 0 &&
3650 scale > preferredScale) {
3651 if (intVal.testBit(0))
3652 break; // odd number cannot end in 0
3653 qr = intVal.divideAndRemainder(BigInteger.TEN);
3654 if (qr[1].signum() != 0)
3655 break; // non-0 remainder
3656 intVal=qr[0];
3657 scale = checkScale((long)scale-1); // could Overflow
3658 if (precision > 0) // adjust precision if known
3659 precision--;
3660 }
3661 if (intVal != null)
3662 intCompact = compactValFor(intVal);
3663 return this;
3664 }
3665
3666 /**
3667 * Check a scale for Underflow or Overflow. If this BigDecimal is
3668 * nonzero, throw an exception if the scale is outof range. If this
3669 * is zero, saturate the scale to the extreme value of the right
3670 * sign if the scale is out of range.
3671 *
3672 * @param val The new scale.
3673 * @throws ArithmeticException (overflow or underflow) if the new
3674 * scale is out of range.
3675 * @return validated scale as an int.
3676 */
3677 private int checkScale(long val) {
3678 int asInt = (int)val;
3679 if (asInt != val) {
3680 asInt = val>Integer.MAX_VALUE ? Integer.MAX_VALUE : Integer.MIN_VALUE;
3681 BigInteger b;
3682 if (intCompact != 0 &&
3683 ((b = intVal) == null || b.signum() != 0))
3684 throw new ArithmeticException(asInt>0 ? "Undeflow":"Overflow");
3685 }
3686 return asInt;
3687 }
3688
3689 /**
3690 * Round an operand; used only if digits > 0. Does not change
3691 * {@code this}; if rounding is needed a new {@code BigDecimal}
3692 * is created and returned.
3693 *
3694 * @param mc the context to use.
3695 * @throws ArithmeticException if the result is inexact but the
3696 * rounding mode is {@code UNNECESSARY}.
3697 */
3698 private BigDecimal roundOp(MathContext mc) {
3699 BigDecimal rounded = doRound(this, mc);
3700 return rounded;
3701 }
3702
3703 /** Round this BigDecimal according to the MathContext settings;
3704 * used only if precision {@literal >} 0.
3705 *
3706 * <p>WARNING: This method should only be called on new objects as
3707 * it mutates the value fields.
3708 *
3709 * @param mc the context to use.
3710 * @throws ArithmeticException if the rounding mode is
3711 * {@code RoundingMode.UNNECESSARY} and the
3712 * {@code BigDecimal} operation would require rounding.
3713 */
3714 private void roundThis(MathContext mc) {
3715 BigDecimal rounded = doRound(this, mc);
3716 if (rounded == this) // wasn't rounded
3717 return;
3718 this.intVal = rounded.intVal;
3719 this.intCompact = rounded.intCompact;
3720 this.scale = rounded.scale;
3721 this.precision = rounded.precision;
3722 }
3723
3724 /**
3725 * Returns a {@code BigDecimal} rounded according to the
3726 * MathContext settings; used only if {@code mc.precision > 0}.
3727 * Does not change {@code this}; if rounding is needed a new
3728 * {@code BigDecimal} is created and returned.
3729 *
3730 * @param mc the context to use.
3731 * @return a {@code BigDecimal} rounded according to the MathContext
3732 * settings. May return this, if no rounding needed.
3733 * @throws ArithmeticException if the rounding mode is
3734 * {@code RoundingMode.UNNECESSARY} and the
3735 * result is inexact.
3736 */
3737 private static BigDecimal doRound(BigDecimal d, MathContext mc) {
3738 int mcp = mc.precision;
3739 int drop;
3740 // This might (rarely) iterate to cover the 999=>1000 case
3741 while ((drop = d.precision() - mcp) > 0) {
3742 int newScale = d.checkScale((long)d.scale - drop);
3743 int mode = mc.roundingMode.oldMode;
3744 if (drop < LONG_TEN_POWERS_TABLE.length)
3745 d = divideAndRound(d.intCompact, d.intVal,
3746 LONG_TEN_POWERS_TABLE[drop], null,
3747 newScale, mode, newScale);
3748 else
3749 d = divideAndRound(d.intCompact, d.intVal,
3750 INFLATED, bigTenToThe(drop),
3751 newScale, mode, newScale);
3752 }
3753 return d;
3754 }
3755
3756 /**
3757 * Returns the compact value for given {@code BigInteger}, or
3758 * INFLATED if too big. Relies on internal representation of
3759 * {@code BigInteger}.
3760 */
3761 private static long compactValFor(BigInteger b) {
3762 int[] m = b.mag;
3763 int len = m.length;
3764 if (len == 0)
3765 return 0;
3766 int d = m[0];
3767 if (len > 2 || (len == 2 && d < 0))
3768 return INFLATED;
3769
3770 long u = (len == 2)?
3771 (((long) m[1] & LONG_MASK) + (((long)d) << 32)) :
3772 (((long)d) & LONG_MASK);
3773 return (b.signum < 0)? -u : u;
3774 }
3775
3776 private static int longCompareMagnitude(long x, long y) {
3777 if (x < 0)
3778 x = -x;
3779 if (y < 0)
3780 y = -y;
3781 return (x < y) ? -1 : ((x == y) ? 0 : 1);
3782 }
3783
3784 private static int saturateLong(long s) {
3785 int i = (int)s;
3786 return (s == i) ? i : (s < 0 ? Integer.MIN_VALUE : Integer.MAX_VALUE);
3787 }
3788
3789 /*
3790 * Internal printing routine
3791 */
3792 private static void print(String name, BigDecimal bd) {
3793 System.err.format("%s:\tintCompact %d\tintVal %d\tscale %d\tprecision %d%n",
3794 name,
3795 bd.intCompact,
3796 bd.intVal,
3797 bd.scale,
3798 bd.precision);
3799 }
3800
3801 /**
3802 * Check internal invariants of this BigDecimal. These invariants
3803 * include:
3804 *
3805 * <ul>
3806 *
3807 * <li>The object must be initialized; either intCompact must not be
3808 * INFLATED or intVal is non-null. Both of these conditions may
3809 * be true.
3810 *
3811 * <li>If both intCompact and intVal and set, their values must be
3812 * consistent.
3813 *
3814 * <li>If precision is nonzero, it must have the right value.
3815 * </ul>
3816 *
3817 * Note: Since this is an audit method, we are not supposed to change the
3818 * state of this BigDecimal object.
3819 */
3820 private BigDecimal audit() {
3821 if (intCompact == INFLATED) {
3822 if (intVal == null) {
3823 print("audit", this);
3824 throw new AssertionError("null intVal");
3825 }
3826 // Check precision
3827 if (precision > 0 && precision != bigDigitLength(intVal)) {
3828 print("audit", this);
3829 throw new AssertionError("precision mismatch");
3830 }
3831 } else {
3832 if (intVal != null) {
3833 long val = intVal.longValue();
3834 if (val != intCompact) {
3835 print("audit", this);
3836 throw new AssertionError("Inconsistent state, intCompact=" +
3837 intCompact + "\t intVal=" + val);
3838 }
3839 }
3840 // Check precision
3841 if (precision > 0 && precision != longDigitLength(intCompact)) {
3842 print("audit", this);
3843 throw new AssertionError("precision mismatch");
3844 }
3845 }
3846 return this;
3847 }
3848 }
|