
JSR 216 (Maintenance Release)  
PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object java.lang.Number java.math.BigDecimal
Immutable, arbitraryprecision signed decimal numbers. A BigDecimal consists of an arbitrary precision integer unscaled value and a nonnegative 32bit integer scale, which represents the number of digits to the right of the decimal point. The number represented by the BigDecimal is (unscaledValue/10^{scale}). BigDecimal provides operations for basic arithmetic, scale manipulation, comparison, hashing, and format conversion.
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 (divide(BigDecimal, int)
, divide(BigDecimal, int, int)
,
and setScale(int, int)
). 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 (movePointLeft(int)
and
movePointRight(int)
) 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, pseudocode is used throughout the descriptions of BigDecimal methods. The pseudocode expression (i + j) is shorthand for "a BigDecimal whose value is that of the BigDecimal i plus that of the BigDecimal j." The pseudocode expression (i == j) is shorthand for "true if and only if the BigDecimal i represents the same value as the the BigDecimal j." Other pseudocode expressions are interpreted similarly.
Note: care should be exercised if BigDecimals are to be used as
keys in a SortedMap
or elements in a SortedSet
, as BigDecimal's natural ordering is
inconsistent with equals. See Comparable
, SortedMap
or SortedSet
for more
information.
All methods and constructors for this class
throw NullPointerException
when passed
a null object reference for any input parameter.
BigInteger
,
SortedMap
,
SortedSet
,
Serialized FormField Summary  
static int 
ROUND_CEILING
Rounding mode to round towards positive infinity. 
static int 
ROUND_DOWN
Rounding mode to round towards zero. 
static int 
ROUND_FLOOR
Rounding mode to round towards negative infinity. 
static int 
ROUND_HALF_DOWN
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down. 
static int 
ROUND_HALF_EVEN
Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor. 
static int 
ROUND_HALF_UP
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up. 
static int 
ROUND_UNNECESSARY
Rounding mode to assert that the requested operation has an exact result, hence no rounding is necessary. 
static int 
ROUND_UP
Rounding mode to round away from zero. 
Constructor Summary  
BigDecimal(BigInteger val)
Translates a BigInteger into a BigDecimal. 

BigDecimal(BigInteger unscaledVal,
int scale)
Translates a BigInteger unscaled value and an int
scale into a BigDecimal. 

BigDecimal(double val)
Translates a double into a BigDecimal. 

BigDecimal(String val)
Translates the String representation of a BigDecimal into a BigDecimal. 
Method Summary  
BigDecimal 
abs()
Returns a BigDecimal whose value is the absolute value of this BigDecimal, and whose scale is this.scale(). 
BigDecimal 
add(BigDecimal val)
Returns a BigDecimal whose value is (this + val), and whose scale is max(this.scale(), val.scale()). 
int 
compareTo(BigDecimal val)
Compares this BigDecimal with the specified BigDecimal. 
int 
compareTo(Object o)
Compares this BigDecimal with the specified Object. 
BigDecimal 
divide(BigDecimal val,
int roundingMode)
Returns a BigDecimal whose value is (this / val), and whose scale is this.scale(). 
BigDecimal 
divide(BigDecimal val,
int scale,
int roundingMode)
Returns a BigDecimal whose value is (this / val), and whose scale is as specified. 
double 
doubleValue()
Converts this BigDecimal to a double . 
boolean 
equals(Object x)
Compares this BigDecimal with the specified Object for equality. 
float 
floatValue()
Converts this BigDecimal to a float . 
int 
hashCode()
Returns the hash code for this BigDecimal. 
int 
intValue()
Converts this BigDecimal to an int . 
long 
longValue()
Converts this BigDecimal to a long . 
BigDecimal 
max(BigDecimal val)
Returns the maximum of this BigDecimal and val. 
BigDecimal 
min(BigDecimal val)
Returns the minimum of this BigDecimal and val. 
BigDecimal 
movePointLeft(int n)
Returns a BigDecimal which is equivalent to this one with the decimal point moved n places to the left. 
BigDecimal 
movePointRight(int n)
Moves the decimal point the specified number of places to the right. 
BigDecimal 
multiply(BigDecimal val)
Returns a BigDecimal whose value is (this * val), and whose scale is (this.scale() + val.scale()). 
BigDecimal 
negate()
Returns a BigDecimal whose value is (this), and whose scale is this.scale(). 
int 
scale()
Returns the scale of this BigDecimal. 
BigDecimal 
setScale(int scale)
Returns a BigDecimal whose scale is the specified value, and whose value is numerically equal to this BigDecimal's. 
BigDecimal 
setScale(int scale,
int roundingMode)
Returns a BigDecimal whose scale is the specified value, and whose unscaled value is determined by multiplying or dividing this BigDecimal's unscaled value by the appropriate power of ten to maintain its overall value. 
int 
signum()
Returns the signum function of this BigDecimal. 
BigDecimal 
subtract(BigDecimal val)
Returns a BigDecimal whose value is (this  val), and whose scale is max(this.scale(), val.scale()). 
BigInteger 
toBigInteger()
Converts this BigDecimal to a BigInteger. 
String 
toString()
Returns the string representation of this BigDecimal. 
BigInteger 
unscaledValue()
Returns a BigInteger whose value is the unscaled value of this BigDecimal. 
static BigDecimal 
valueOf(long val)
Translates a long value into a BigDecimal with a
scale of zero. 
static BigDecimal 
valueOf(long unscaledVal,
int scale)
Translates a long unscaled value and an
int scale into a BigDecimal. 
Methods inherited from class java.lang.Number 
byteValue, shortValue 
Methods inherited from class java.lang.Object 
clone, finalize, getClass, notify, notifyAll, wait, wait, wait 
Field Detail 
public static final int ROUND_UP
public static final int ROUND_DOWN
public static final int ROUND_CEILING
public static final int ROUND_FLOOR
public static final int ROUND_HALF_UP
public static final int ROUND_HALF_DOWN
public static final int ROUND_HALF_EVEN
public static final int ROUND_UNNECESSARY
Constructor Detail 
public BigDecimal(String val)
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(char)
returnstrue
, 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 charactertodigit mapping is provided by Character.digit(char, int)
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(float)
and Double.toString(double)
. 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(double)
constructor.
Note: the optional leading plus sign and trailing exponent were added in release 1.3.
val
 String representation of BigDecimal.
NumberFormatException
 val is not a valid representation
of a BigDecimal.public BigDecimal(double val)
double
into a BigDecimal. The scale
of the BigDecimal is the smallest value such that
(10^{scale} * val) is an integer.
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.
val
 double
value to be converted to BigDecimal.
NumberFormatException
 val if val is
infinite or NaN.public BigDecimal(BigInteger val)
val
 BigInteger value to be converted to BigDecimal.public BigDecimal(BigInteger unscaledVal, int scale)
int
scale into a BigDecimal. The value of the BigDecimal is
(unscaledVal/10^{scale}).
unscaledVal
 unscaled value of the BigDecimal.scale
 scale of the BigDecimal.
NumberFormatException
 scale is negativeMethod Detail 
public static BigDecimal valueOf(long unscaledVal, int scale)
long
unscaled value and an
int
scale into a BigDecimal. This "static factory
method" is provided in preference to a (long
,
int
) constructor because it allows for reuse of
frequently used BigDecimals.
unscaledVal
 unscaled value of the BigDecimal.scale
 scale of the BigDecimal.
public static BigDecimal valueOf(long val)
long
value into a BigDecimal with a
scale of zero. This "static factory method" is provided in
preference to a (long
) constructor because it
allows for reuse of frequently used BigDecimals.
val
 value of the BigDecimal.
public BigDecimal add(BigDecimal val)
val
 value to be added to this BigDecimal.
public BigDecimal subtract(BigDecimal val)
val
 value to be subtracted from this BigDecimal.
public BigDecimal multiply(BigDecimal val)
val
 value to be multiplied by this BigDecimal.
public BigDecimal divide(BigDecimal val, int scale, int roundingMode)
val
 value by which this BigDecimal is to be divided.scale
 scale of the BigDecimal quotient to be returned.roundingMode
 rounding mode to apply.
ArithmeticException
 val is zero, scale is
negative, or roundingMode==ROUND_UNNECESSARY and
the specified scale is insufficient to represent the result
of the division exactly.
IllegalArgumentException
 roundingMode does not
represent a valid rounding mode.ROUND_UP
,
ROUND_DOWN
,
ROUND_CEILING
,
ROUND_FLOOR
,
ROUND_HALF_UP
,
ROUND_HALF_DOWN
,
ROUND_HALF_EVEN
,
ROUND_UNNECESSARY
public BigDecimal divide(BigDecimal val, int roundingMode)
val
 value by which this BigDecimal is to be divided.roundingMode
 rounding mode to apply.
ArithmeticException
 val==0, or
roundingMode==ROUND_UNNECESSARY and
this.scale() is insufficient to represent the result
of the division exactly.
IllegalArgumentException
 roundingMode does not
represent a valid rounding mode.ROUND_UP
,
ROUND_DOWN
,
ROUND_CEILING
,
ROUND_FLOOR
,
ROUND_HALF_UP
,
ROUND_HALF_DOWN
,
ROUND_HALF_EVEN
,
ROUND_UNNECESSARY
public BigDecimal abs()
public BigDecimal negate()
public int signum()
public int scale()
public BigInteger unscaledValue()
public BigDecimal setScale(int scale, int roundingMode)
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.
scale
 scale of the BigDecimal value to be returned.roundingMode
 The rounding mode to apply.
ArithmeticException
 scale is negative, or
roundingMode==ROUND_UNNECESSARY and the specified
scaling operation would require rounding.
IllegalArgumentException
 roundingMode does not
represent a valid rounding mode.ROUND_UP
,
ROUND_DOWN
,
ROUND_CEILING
,
ROUND_FLOOR
,
ROUND_HALF_UP
,
ROUND_HALF_DOWN
,
ROUND_HALF_EVEN
,
ROUND_UNNECESSARY
public BigDecimal setScale(int scale)
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.
scale
 scale of the BigDecimal value to be returned.
ArithmeticException
 scale is negative, or
the specified scaling operation would require rounding.setScale(int, int)
public BigDecimal movePointLeft(int n)
n
 number of places to move the decimal point to the left.
public BigDecimal movePointRight(int n)
n
 number of places to move the decimal point to the right.
public int compareTo(BigDecimal val)
val
 BigDecimal to which this BigDecimal is to be compared.
public int compareTo(Object o)
compareTo
.
Otherwise, it throws a ClassCastException (as BigDecimals are
comparable only to other BigDecimals).
compareTo
in interface Comparable
o
 Object to which this BigDecimal is to be compared.
ClassCastException
 o is not a BigDecimal.compareTo(java.math.BigDecimal)
,
Comparable
public boolean equals(Object x)
compareTo
, this method
considers two BigDecimals equal only if they are equal in value
and scale (thus 2.0 is not equal to 2.00 when compared by this
method).
equals
in class Object
x
 Object to which this BigDecimal is to be compared.
compareTo(java.math.BigDecimal)
public BigDecimal min(BigDecimal val)
val
 value with which the minimum is to be computed.
compareTo
method, either may be returned.compareTo(java.math.BigDecimal)
public BigDecimal max(BigDecimal val)
val
 value with which the maximum is to be computed.
compareTo
method, either may be returned.compareTo(java.math.BigDecimal)
public int hashCode()
hashCode
in class Object
Object.equals(java.lang.Object)
,
Hashtable
public String toString()
Character.forDigit(int, int)
is used.
A leading minus sign is used to indicate sign, and the number of digits
to the right of the decimal point is used to indicate scale. (This
representation is compatible with the (String) constructor.)
toString
in class Object
Character.forDigit(int, int)
,
BigDecimal(java.lang.String)
public BigInteger toBigInteger()
double
to
long
as defined in the Java Language
Specification: any fractional part of this BigDecimal will
be discarded. Note that this conversion can lose information
about the precision of the BigDecimal value.
public int intValue()
int
. This
conversion is analogous to a narrowing
primitive conversion from double
to
short
as defined in the Java Language
Specification: any fractional part of this BigDecimal will
be discarded, and if the resulting "BigInteger" is
too big to fit in an int
, only the loworder 32
bits are returned. Note that this conversion can lose
information about the overall magnitude and precision of the
BigDecimal value as well as return a result with the opposite
sign.
intValue
in class Number
int
.public long longValue()
long
. This
conversion is analogous to a narrowing
primitive conversion from double
to
short
as defined in the Java Language
Specification: any fractional part of this BigDecimal will
be discarded, and if the resulting "BigInteger" is
too big to fit in a long
, only the loworder 64
bits are returned. Note that this conversion can lose
information about the overall magnitude and precision of the
BigDecimal value as well as return a result with the opposite
sign.
longValue
in class Number
long
.public float floatValue()
float
. This
conversion is similar to the narrowing
primitive conversion from double
to
float
defined in the Java Language
Specification: if this BigDecimal has too great a magnitude
to represent as a float
, it will be converted to
Float.NEGATIVE_INFINITY
or Float.POSITIVE_INFINITY
as appropriate. Note that even when
the return value is finite, this conversion can lose
information about the precision of the BigDecimal value.
floatValue
in class Number
float
.public double doubleValue()
double
. This
conversion is similar to the narrowing
primitive conversion from double
to
float
as defined in the Java Language
Specification: if this BigDecimal has too great a magnitude
represent as a double
, it will be converted to
Double.NEGATIVE_INFINITY
or Double.POSITIVE_INFINITY
as appropriate. Note that even when
the return value is finite, this conversion can lose
information about the precision of the BigDecimal value.
doubleValue
in class Number
double
.

JSR 216 (Maintenance Release)  
PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 