Java Doc for BigDecimal.java in  » 6.0-JDK-Modules » j2me » java » math » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The BigDecimal class gives its user complete control over rounding behavior, forcing the user to explicitly specify a rounding behavior for operations capable of discarding precision ( BigDecimal.divide(BigDecimal,int) , BigDecimal.divide(BigDecimal,int,int) , and BigDecimal.setScale ). Eight rounding modes are provided for this purpose.

Two types of operations are provided for manipulating the scale of a BigDecimal: scaling/rounding operations and decimal point motion operations. Scaling/rounding operations (setScale) return a BigDecimal whose value is approximately (or exactly) equal to that of the operand, but whose scale is the specified value; that is, they increase or decrease the precision of the number with minimal effect on its value. Decimal point motion operations ( BigDecimal.movePointLeft and BigDecimal.movePointRight ) return a BigDecimal created from the operand by moving the decimal point a specified distance in the specified direction; that is, they change a number's value without affecting its precision.

For the sake of brevity and clarity, pseudo-code is used throughout the descriptions of BigDecimal methods. The pseudo-code expression (i + j) is shorthand for "a BigDecimal whose value is that of the BigDecimal i plus that of the BigDecimal j." The pseudo-code expression (i == j) is shorthand for "true if and only if the BigDecimal i represents the same value as the the BigDecimal j." Other pseudo-code expressions are interpreted similarly.

Note: care should be exercised if BigDecimals are to be used as keys in a java.util.SortedMap or elements in a java.util.SortedSet , as BigDecimal's natural ordering is inconsistent with equals. See Comparable , java.util.SortedMap or java.util.SortedSet for more information.

All methods and constructors for this class throw NullPointerException when passed a null object reference for any input parameter.
See Also:   BigInteger
See Also:   java.util.SortedMap
See Also:   java.util.SortedSet
version:
   1.33, 08/19/02
author:
   Josh Bloch

The fraction consists of of a decimal point followed by zero or more decimal digits. The string must contain at least one digit in either the integer or the fraction. The number formed by the sign, the integer and the fraction is referred to as the significand.

The exponent consists of the character 'e' ('\u0075') or 'E' ('\u0045') followed by one or more decimal digits. The value of the exponent must lie between - Integer.MAX_VALUE ( Integer.MIN_VALUE +1) and Integer.MAX_VALUE , inclusive.

More formally, the strings this constructor accepts are described by the following grammar:

BigDecimalString:

Sign_opt Significand Exponent_opt

Sign:

+

-

Significand:

IntegerPart . FractionPart_opt

. FractionPart

IntegerPart

IntegerPart:

Digits

FractionPart:

Digits

Exponent:

ExponentIndicator SignedInteger

ExponentIndicator:

e

E

SignedInteger:

Sign_opt Digits

Digits:

Digit

Digits Digit

Digit:

any character for which Character.isDigit returns true, including 0, 1, 2 ...

The scale of the returned BigDecimal will be the number of digits in the fraction, or zero if the string contains no decimal point, subject to adjustment for any exponent: If the string contains an exponent, the exponent is subtracted from the scale. If the resulting scale is negative, the scale of the returned BigDecimal is zero and the unscaled value is multiplied by the appropriate power of ten so that, in every case, the resulting BigDecimal is equal to significand × 10^exponent. (If in the future this specification is amended to permit negative scales, the final step of zeroing the scale and adjusting the unscaled value will be eliminated.)

The character-to-digit mapping is provided by java.lang.Character.digit set to convert to radix 10. The String may not contain any extraneous characters (whitespace, for example).

Note: For values other float and double NaN and ±Infinity, this constructor is compatible with the values returned by Float.toString and Double.toString . This is generally the preferred way to convert a float or double into a BigDecimal, as it doesn't suffer from the unpredictability of the BigDecimal.BigDecimal(double) constructor.

Note: the optional leading plus sign and trailing exponent were added in release 1.3.
Parameters:
  val - String representation of BigDecimal.
throws:
  NumberFormatException - val is not a valid representationof a BigDecimal.

Note: the results of this constructor can be somewhat unpredictable. One might assume that new BigDecimal(.1) is exactly equal to .1, but it is actually equal to .1000000000000000055511151231257827021181583404541015625. This is so because .1 cannot be represented exactly as a double (or, for that matter, as a binary fraction of any finite length). Thus, the long value that is being passed in to the constructor is not exactly equal to .1, appearances notwithstanding.

The (String) constructor, on the other hand, is perfectly predictable: new BigDecimal(".1") is exactly equal to .1, as one would expect. Therefore, it is generally recommended that the (String) constructor be used in preference to this one.
Parameters:
  val - double value to be converted to BigDecimal.
throws:
  NumberFormatException - val if val isinfinite or NaN.

Note that since BigDecimal objects are immutable, calls of this method do not result in the original object being modified, contrary to the usual convention of having methods named setX mutate field X. Instead, setScale returns an object with the proper scale; the returned object may or may not be newly allocated.
Parameters:
  scale - scale of the BigDecimal value to be returned.
Parameters:
  roundingMode - The rounding mode to apply. a BigDecimal whose scale is the specified value, and whoseunscaled value is determined by multiplying or dividing thisBigDecimal's unscaled value by the appropriate power of ten tomaintain its overall value.
throws:
  ArithmeticException - scale is negative, orroundingMode==ROUND_UNNECESSARY and the specifiedscaling operation would require rounding.
throws:
  IllegalArgumentException - roundingMode does notrepresent a valid rounding mode.
See Also:   BigDecimal.ROUND_UP
See Also:   BigDecimal.ROUND_DOWN
See Also:   BigDecimal.ROUND_CEILING
See Also:   BigDecimal.ROUND_FLOOR
See Also:   BigDecimal.ROUND_HALF_UP
See Also:   BigDecimal.ROUND_HALF_DOWN
See Also:   BigDecimal.ROUND_HALF_EVEN
See Also:   BigDecimal.ROUND_UNNECESSARY

This method returns the same result as the two argument version of setScale, but saves the caller the trouble of specifying a rounding mode in cases where it is irrelevant.

Note that since BigDecimal objects are immutable, calls of this method do not result in the original object being modified, contrary to the usual convention of having methods named setX mutate field X. Instead, setScale returns an object with the proper scale; the returned object may or may not be newly allocated.
Parameters:
  scale - scale of the BigDecimal value to be returned. a BigDecimal whose scale is the specified value, and whoseunscaled value is determined by multiplying or dividing thisBigDecimal's unscaled value by the appropriate power of ten tomaintain its overall value.
throws:
  ArithmeticException - scale is negative, orthe specified scaling operation would require rounding.
See Also:   BigDecimal.setScale(int,int)