BigDecimal
public
class
BigDecimal
extends Number
implements
Comparable<BigDecimal>,
Serializable
java.lang.Object  
↳  java.lang.Number  
↳  java.math.BigDecimal 
An immutable arbitraryprecision signed decimal.
A value is represented by an arbitraryprecision "unscaled value" and a signed 32bit "scale",
combined thus: unscaled * 10<sup>scale</sup>
. See unscaledValue()
and scale()
.
Most operations allow you to supply a MathContext
to specify a desired rounding mode.
Summary
Constants  

int 
ROUND_CEILING
Rounding mode to round towards positive infinity. 
int 
ROUND_DOWN
Rounding mode where the values are rounded towards zero. 
int 
ROUND_FLOOR
Rounding mode to round towards negative infinity. 
int 
ROUND_HALF_DOWN
Rounding mode where values are rounded towards the nearest neighbor. 
int 
ROUND_HALF_EVEN
Rounding mode where values are rounded towards the nearest neighbor. 
int 
ROUND_HALF_UP
Rounding mode where values are rounded towards the nearest neighbor. 
int 
ROUND_UNNECESSARY
Rounding mode where the rounding operations throws an 
int 
ROUND_UP
Rounding mode where positive values are rounded towards positive infinity and negative values towards negative infinity. 
Fields  

public
static
final
BigDecimal 
ONE
The constant one as a 
public
static
final
BigDecimal 
TEN
The constant ten as a 
public
static
final
BigDecimal 
ZERO
The constant zero as a 
Public constructors  

BigDecimal(char[] in, int offset, int len)
Constructs a new 

BigDecimal(char[] in, int offset, int len, MathContext mc)
Constructs a new 

BigDecimal(char[] in)
Constructs a new 

BigDecimal(char[] in, MathContext mc)
Constructs a new 

BigDecimal(String val)
Constructs a new 

BigDecimal(String val, MathContext mc)
Constructs a new 

BigDecimal(double val)
Constructs a new 

BigDecimal(double val, MathContext mc)
Constructs a new 

BigDecimal(BigInteger val)
Constructs a new 

BigDecimal(BigInteger val, MathContext mc)
Constructs a new 

BigDecimal(BigInteger unscaledVal, int scale)
Constructs a new 

BigDecimal(BigInteger unscaledVal, int scale, MathContext mc)
Constructs a new 

BigDecimal(int val)
Constructs a new 

BigDecimal(int val, MathContext mc)
Constructs a new 

BigDecimal(long val)
Constructs a new 

BigDecimal(long val, MathContext mc)
Constructs a new 
Public methods  

BigDecimal

abs(MathContext mc)
Returns a 
BigDecimal

abs()
Returns a 
BigDecimal

add(BigDecimal augend)
Returns a new 
BigDecimal

add(BigDecimal augend, MathContext mc)
Returns a new 
byte

byteValueExact()
Returns this 
int

compareTo(BigDecimal val)
Compares this 
BigDecimal

divide(BigDecimal divisor, int scale, int roundingMode)
Returns a new 
BigDecimal

divide(BigDecimal divisor, int scale, RoundingMode roundingMode)
Returns a new 
BigDecimal

divide(BigDecimal divisor, int roundingMode)
Returns a new 
BigDecimal

divide(BigDecimal divisor, MathContext mc)
Returns a new 
BigDecimal

divide(BigDecimal divisor, RoundingMode roundingMode)
Returns a new 
BigDecimal

divide(BigDecimal divisor)
Returns a new 
BigDecimal[]

divideAndRemainder(BigDecimal divisor, MathContext mc)
Returns a 
BigDecimal[]

divideAndRemainder(BigDecimal divisor)
Returns a 
BigDecimal

divideToIntegralValue(BigDecimal divisor, MathContext mc)
Returns a new 
BigDecimal

divideToIntegralValue(BigDecimal divisor)
Returns a new 
double

doubleValue()
Returns this 
boolean

equals(Object x)
Returns 
float

floatValue()
Returns this 
int

hashCode()
Returns a hash code for this 
int

intValue()
Returns this 
int

intValueExact()
Returns this 
long

longValue()
Returns this 
long

longValueExact()
Returns this 
BigDecimal

max(BigDecimal val)
Returns the maximum of this 
BigDecimal

min(BigDecimal val)
Returns the minimum of this 
BigDecimal

movePointLeft(int n)
Returns a new 
BigDecimal

movePointRight(int n)
Returns a new 
BigDecimal

multiply(BigDecimal multiplicand, MathContext mc)
Returns a new 
BigDecimal

multiply(BigDecimal multiplicand)
Returns a new 
BigDecimal

negate()
Returns a new 
BigDecimal

negate(MathContext mc)
Returns a new 
BigDecimal

plus()
Returns a new 
BigDecimal

plus(MathContext mc)
Returns a new 
BigDecimal

pow(int n, MathContext mc)
Returns a new 
BigDecimal

pow(int n)
Returns a new 
int

precision()
Returns the precision of this 
BigDecimal

remainder(BigDecimal divisor)
Returns a new 
BigDecimal

remainder(BigDecimal divisor, MathContext mc)
Returns a new 
BigDecimal

round(MathContext mc)
Returns a new 
int

scale()
Returns the scale of this 
BigDecimal

scaleByPowerOfTen(int n)
Returns a new 
BigDecimal

setScale(int newScale, int roundingMode)
Returns a new 
BigDecimal

setScale(int newScale)
Returns a new 
BigDecimal

setScale(int newScale, RoundingMode roundingMode)
Returns a new 
short

shortValueExact()
Returns this 
int

signum()
Returns the sign of this 
BigDecimal

stripTrailingZeros()
Returns a new 
BigDecimal

subtract(BigDecimal subtrahend)
Returns a new 
BigDecimal

subtract(BigDecimal subtrahend, MathContext mc)
Returns a new 
BigInteger

toBigInteger()
Returns this 
BigInteger

toBigIntegerExact()
Returns this 
String

toEngineeringString()
Returns a string representation of this 
String

toPlainString()
Returns a string representation of this 
String

toString()
Returns a canonical string representation of this 
BigDecimal

ulp()
Returns the unit in the last place (ULP) of this 
BigInteger

unscaledValue()
Returns the unscaled value (mantissa) of this 
static
BigDecimal

valueOf(double val)
Returns a new 
static
BigDecimal

valueOf(long unscaledVal)
Returns a new 
static
BigDecimal

valueOf(long unscaledVal, int scale)
Returns a new 
Inherited methods  

Constants
ROUND_CEILING
int ROUND_CEILING
Rounding mode to round towards positive infinity. For positive values
this rounding mode behaves as ROUND_UP
, for negative values as
ROUND_DOWN
.
See also:
Constant Value: 2 (0x00000002)
ROUND_DOWN
int ROUND_DOWN
Rounding mode where the values are rounded towards zero.
See also:
Constant Value: 1 (0x00000001)
ROUND_FLOOR
int ROUND_FLOOR
Rounding mode to round towards negative infinity. For positive values
this rounding mode behaves as ROUND_DOWN
, for negative values as
ROUND_UP
.
See also:
Constant Value: 3 (0x00000003)
ROUND_HALF_DOWN
int ROUND_HALF_DOWN
Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding down.
See also:
Constant Value: 5 (0x00000005)
ROUND_HALF_EVEN
int ROUND_HALF_EVEN
Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding to the even neighbor.
See also:
Constant Value: 6 (0x00000006)
ROUND_HALF_UP
int ROUND_HALF_UP
Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding up.
See also:
Constant Value: 4 (0x00000004)
ROUND_UNNECESSARY
int ROUND_UNNECESSARY
Rounding mode where the rounding operations throws an ArithmeticException
for the case that rounding is necessary, i.e. for
the case that the value cannot be represented exactly.
See also:
Constant Value: 7 (0x00000007)
ROUND_UP
int ROUND_UP
Rounding mode where positive values are rounded towards positive infinity and negative values towards negative infinity.
See also:
Constant Value: 0 (0x00000000)
Fields
Public constructors
BigDecimal
BigDecimal (char[] in, int offset, int len)
Constructs a new BigDecimal
instance from a string representation
given as a character array.
Parameters  

in 
char : array of characters containing the string representation of
this BigDecimal . 
offset 
int : first index to be copied. 
len 
int : number of characters to be used. 
Throws  

NumberFormatException 
if offset < 0  len <= 0  offset+len1 < 0 
offset+len1 >= in.length , or if in does not
contain a valid string representation of a big decimal.

BigDecimal
BigDecimal (char[] in, int offset, int len, MathContext mc)
Constructs a new BigDecimal
instance from a string representation
given as a character array.
Parameters  

in 
char : array of characters containing the string representation of
this BigDecimal . 
offset 
int : first index to be copied. 
len 
int : number of characters to be used. 
mc 
MathContext : rounding mode and precision for the result of this operation. 
Throws  

NumberFormatException 
if offset < 0  len <= 0  offset+len1 < 0 
offset+len1 >= in.length , or if in does not
contain a valid string representation of a big decimal. 
ArithmeticException 
if mc.precision > 0 and mc.roundingMode ==
UNNECESSARY and the new big decimal cannot be represented
within the given precision without rounding.

BigDecimal
BigDecimal (char[] in)
Constructs a new BigDecimal
instance from a string representation
given as a character array.
Parameters  

in 
char : array of characters containing the string representation of
this BigDecimal . 
Throws  

NumberFormatException 
if in does not contain a valid string representation
of a big decimal.

BigDecimal
BigDecimal (char[] in, MathContext mc)
Constructs a new BigDecimal
instance from a string representation
given as a character array. The result is rounded according to the
specified math context.
Parameters  

in 
char : array of characters containing the string representation of
this BigDecimal . 
mc 
MathContext : rounding mode and precision for the result of this operation. 
Throws  

NumberFormatException 
if in does not contain a valid string representation
of a big decimal. 
ArithmeticException 
if mc.precision > 0 and mc.roundingMode ==
UNNECESSARY and the new big decimal cannot be represented
within the given precision without rounding.

BigDecimal
BigDecimal (String val)
Constructs a new BigDecimal
instance from a string
representation.
Parameters  

val 
String 
Throws  

NumberFormatException 
if val does not contain a valid string representation
of a big decimal.

BigDecimal
BigDecimal (String val, MathContext mc)
Constructs a new BigDecimal
instance from a string
representation. The result is rounded according to the specified math
context.
Parameters  

val 
String 
mc 
MathContext : rounding mode and precision for the result of this operation. 
Throws  

NumberFormatException 
if val does not contain a valid string representation
of a big decimal. 
ArithmeticException 
if mc.precision > 0 and mc.roundingMode ==
UNNECESSARY and the new big decimal cannot be represented
within the given precision without rounding.

BigDecimal
BigDecimal (double val)
Constructs a new BigDecimal
instance from the 64bit double
val
. The constructed big decimal is equivalent to the given
double. For example, new BigDecimal(0.1)
is equal to 0.1000000000000000055511151231257827021181583404541015625
. This happens
as 0.1
cannot be represented exactly in binary.
To generate a big decimal instance which is equivalent to 0.1
use
the BigDecimal(String)
constructor.
Parameters  

val 
double : double value to be converted to a BigDecimal instance. 
Throws  

NumberFormatException 
if val is infinity or not a number.

BigDecimal
BigDecimal (double val, MathContext mc)
Constructs a new BigDecimal
instance from the 64bit double
val
. The constructed big decimal is equivalent to the given
double. For example, new BigDecimal(0.1)
is equal to 0.1000000000000000055511151231257827021181583404541015625
. This happens
as 0.1
cannot be represented exactly in binary.
To generate a big decimal instance which is equivalent to 0.1
use
the BigDecimal(String)
constructor.
Parameters  

val 
double : double value to be converted to a BigDecimal instance. 
mc 
MathContext : rounding mode and precision for the result of this operation. 
Throws  

NumberFormatException 
if val is infinity or not a number. 
ArithmeticException 
if mc.precision > 0 and mc.roundingMode ==
UNNECESSARY and the new big decimal cannot be represented
within the given precision without rounding.

BigDecimal
BigDecimal (BigInteger val)
Constructs a new BigDecimal
instance from the given big integer
val
. The scale of the result is 0
.
Parameters  

val 
BigInteger 
BigDecimal
BigDecimal (BigInteger val, MathContext mc)
Constructs a new BigDecimal
instance from the given big integer
val
. The scale of the result is 0
.
Parameters  

val 
BigInteger 
mc 
MathContext : rounding mode and precision for the result of this operation. 
Throws  

ArithmeticException 
if mc.precision > 0 and mc.roundingMode ==
UNNECESSARY and the new big decimal cannot be represented
within the given precision without rounding.

BigDecimal
BigDecimal (BigInteger unscaledVal, int scale)
Constructs a new BigDecimal
instance from a given unscaled value
unscaledVal
and a given scale. The value of this instance is
unscaledVal * 10<sup>scale</sup>
).
Parameters  

unscaledVal 
BigInteger 
scale 
int 
Throws  

NullPointerException 
if unscaledVal == null .

BigDecimal
BigDecimal (BigInteger unscaledVal, int scale, MathContext mc)
Constructs a new BigDecimal
instance from a given unscaled value
unscaledVal
and a given scale. The value of this instance is
{@code unscaledVal * 10^{scale}). The result is rounded according
to the specified math context.
Parameters  

unscaledVal 
BigInteger 
scale 
int 
mc 
MathContext : rounding mode and precision for the result of this operation. 
Throws  

ArithmeticException 
if mc.precision > 0 and mc.roundingMode ==
UNNECESSARY and the new big decimal cannot be represented
within the given precision without rounding. 
NullPointerException 
if unscaledVal == null .

BigDecimal
BigDecimal (int val)
Constructs a new BigDecimal
instance from the given int
val
. The scale of the result is 0.
Parameters  

val 
int : int value to be converted to a BigDecimal instance.

BigDecimal
BigDecimal (int val, MathContext mc)
Constructs a new BigDecimal
instance from the given int val
. The scale of the result is 0
. The result is rounded
according to the specified math context.
Parameters  

val 
int : int value to be converted to a BigDecimal instance. 
mc 
MathContext : rounding mode and precision for the result of this operation. 
Throws  

ArithmeticException 
if mc.precision > 0 and c.roundingMode ==
UNNECESSARY and the new big decimal cannot be represented
within the given precision without rounding.

BigDecimal
BigDecimal (long val)
Constructs a new BigDecimal
instance from the given long val
. The scale of the result is 0
.
Parameters  

val 
long : long value to be converted to a BigDecimal instance.

BigDecimal
BigDecimal (long val, MathContext mc)
Constructs a new BigDecimal
instance from the given long val
. The scale of the result is 0
. The result is rounded
according to the specified math context.
Parameters  

val 
long : long value to be converted to a BigDecimal instance. 
mc 
MathContext : rounding mode and precision for the result of this operation. 
Throws  

ArithmeticException 
if mc.precision > 0 and mc.roundingMode ==
UNNECESSARY and the new big decimal cannot be represented
within the given precision without rounding.

Public methods
abs
BigDecimal abs (MathContext mc)
Returns a BigDecimal
whose value is the absolute value of
this
. The result is rounded according to the passed context
mc
.
Parameters  

mc 
MathContext 
Returns  

BigDecimal 
abs
BigDecimal abs ()
Returns a BigDecimal
whose value is the absolute value of
this
. The scale of the result is the same as the scale of this.
Returns  

BigDecimal 
add
BigDecimal add (BigDecimal augend)
Returns a new BigDecimal
whose value is this + augend
.
The scale of the result is the maximum of the scales of the two
arguments.
Parameters  

augend 
BigDecimal : value to be added to this . 
Returns  

BigDecimal 
this + augend . 
Throws  

NullPointerException 
if augend == null .

add
BigDecimal add (BigDecimal augend, MathContext mc)
Returns a new BigDecimal
whose value is this + augend
.
The result is rounded according to the passed context mc
.
Parameters  

augend 
BigDecimal : value to be added to this . 
mc 
MathContext : rounding mode and precision for the result of this operation. 
Returns  

BigDecimal 
this + augend . 
Throws  

NullPointerException 
if augend == null or mc == null .

byteValueExact
byte byteValueExact ()
Returns this BigDecimal
as a byte value if it has no fractional
part and if its value fits to the byte range ([128..127]). If these
conditions are not met, an ArithmeticException
is thrown.
Returns  

byte 
Throws  

ArithmeticException 
if rounding is necessary or the number doesn't fit in a byte. 
compareTo
int compareTo (BigDecimal val)
Compares this BigDecimal
with val
. Returns one of the
three values 1
, 0
, or 1
. The method behaves as
if this.subtract(val)
is computed. If this difference is > 0 then
1 is returned, if the difference is < 0 then 1 is returned, and if the
difference is 0 then 0 is returned. This means, that if two decimal
instances are compared which are equal in value but differ in scale, then
these two instances are considered as equal.
Parameters  

val 
BigDecimal : value to be compared with this . 
Returns  

int 
1 if this > val , 1 if this < val ,
0 if this == val . 
Throws  

NullPointerException 
if val == null .

divide
BigDecimal divide (BigDecimal divisor, int scale, int roundingMode)
Returns a new BigDecimal
whose value is this / divisor
.
As scale of the result the parameter scale
is used. If rounding
is required to meet the specified scale, then the specified rounding mode
roundingMode
is applied.
Parameters  

divisor 
BigDecimal : value by which this is divided. 
scale 
int : the scale of the result returned. 
roundingMode 
int : rounding mode to be used to round the result. 
Returns  

BigDecimal 
this / divisor rounded according to the given rounding
mode. 
Throws  

NullPointerException 
if divisor == null . 
IllegalArgumentException 
if roundingMode is not a valid rounding mode. 
ArithmeticException 
if divisor == 0 . 
ArithmeticException 
if roundingMode == ROUND_UNNECESSARY and rounding is
necessary according to the given scale.

divide
BigDecimal divide (BigDecimal divisor, int scale, RoundingMode roundingMode)
Returns a new BigDecimal
whose value is this / divisor
.
As scale of the result the parameter scale
is used. If rounding
is required to meet the specified scale, then the specified rounding mode
roundingMode
is applied.
Parameters  

divisor 
BigDecimal : value by which this is divided. 
scale 
int : the scale of the result returned. 
roundingMode 
RoundingMode : rounding mode to be used to round the result. 
Returns  

BigDecimal 
this / divisor rounded according to the given rounding
mode. 
Throws  

NullPointerException 
if divisor == null or roundingMode == null . 
ArithmeticException 
if divisor == 0 . 
ArithmeticException 
if roundingMode == RoundingMode.UNNECESSAR Y and
rounding is necessary according to the given scale and given
precision.

divide
BigDecimal divide (BigDecimal divisor, int roundingMode)
Returns a new BigDecimal
whose value is this / divisor
.
The scale of the result is the scale of this
. If rounding is
required to meet the specified scale, then the specified rounding mode
roundingMode
is applied.
Parameters  

divisor 
BigDecimal : value by which this is divided. 
roundingMode 
int : rounding mode to be used to round the result. 
Returns  

BigDecimal 
this / divisor rounded according to the given rounding
mode. 
Throws  

NullPointerException 
if divisor == null . 
IllegalArgumentException 
if roundingMode is not a valid rounding mode. 
ArithmeticException 
if divisor == 0 . 
ArithmeticException 
if roundingMode == ROUND_UNNECESSARY and rounding is
necessary according to the scale of this.

divide
BigDecimal divide (BigDecimal divisor, MathContext mc)
Returns a new BigDecimal
whose value is this / divisor
.
The result is rounded according to the passed context mc
. If the
passed math context specifies precision 0
, then this call is
equivalent to this.divide(divisor)
.
Parameters  

divisor 
BigDecimal : value by which this is divided. 
mc 
MathContext : rounding mode and precision for the result of this operation. 
Returns  

BigDecimal 
this / divisor . 
Throws  

NullPointerException 
if divisor == null or mc == null . 
ArithmeticException 
if divisor == 0 . 
ArithmeticException 
if mc.getRoundingMode() == UNNECESSARY and rounding
is necessary according mc.getPrecision() .

divide
BigDecimal divide (BigDecimal divisor, RoundingMode roundingMode)
Returns a new BigDecimal
whose value is this / divisor
.
The scale of the result is the scale of this
. If rounding is
required to meet the specified scale, then the specified rounding mode
roundingMode
is applied.
Parameters  

divisor 
BigDecimal : value by which this is divided. 
roundingMode 
RoundingMode : rounding mode to be used to round the result. 
Returns  

BigDecimal 
this / divisor rounded according to the given rounding
mode. 
Throws  

NullPointerException 
if divisor == null or roundingMode == null . 
ArithmeticException 
if divisor == 0 . 
ArithmeticException 
if roundingMode == RoundingMode.UNNECESSARY and
rounding is necessary according to the scale of this.

divide
BigDecimal divide (BigDecimal divisor)
Returns a new BigDecimal
whose value is this / divisor
.
The scale of the result is the difference of the scales of this
and divisor
. If the exact result requires more digits, then the
scale is adjusted accordingly. For example, 1/128 = 0.0078125
which has a scale of 7
and precision 5
.
Parameters  

divisor 
BigDecimal : value by which this is divided. 
Returns  

BigDecimal 
this / divisor . 
Throws  

NullPointerException 
if divisor == null . 
ArithmeticException 
if divisor == 0 . 
ArithmeticException 
if the result cannot be represented exactly. 
divideAndRemainder
BigDecimal[] divideAndRemainder (BigDecimal divisor, MathContext mc)
Returns a BigDecimal
array which contains the integral part of
this / divisor
at index 0 and the remainder this %
divisor
at index 1. The quotient is rounded down towards zero to the
next integer. The rounding mode passed with the parameter mc
is
not considered. But if the precision of mc > 0
and the integral
part requires more digits, then an ArithmeticException
is thrown.
Parameters  

divisor 
BigDecimal : value by which this is divided. 
mc 
MathContext : math context which determines the maximal precision of the
result. 
Returns  

BigDecimal[] 
[this.divideToIntegralValue(divisor),
this.remainder(divisor)] . 
Throws  

NullPointerException 
if divisor == null . 
ArithmeticException 
if divisor == 0 . 
divideAndRemainder
BigDecimal[] divideAndRemainder (BigDecimal divisor)
Returns a BigDecimal
array which contains the integral part of
this / divisor
at index 0 and the remainder this %
divisor
at index 1. The quotient is rounded down towards zero to the
next integer.
Parameters  

divisor 
BigDecimal : value by which this is divided. 
Returns  

BigDecimal[] 
[this.divideToIntegralValue(divisor),
this.remainder(divisor)] . 
Throws  

NullPointerException 
if divisor == null . 
ArithmeticException 
if divisor == 0 . 
divideToIntegralValue
BigDecimal divideToIntegralValue (BigDecimal divisor, MathContext mc)
Returns a new BigDecimal
whose value is the integral part of
this / divisor
. The quotient is rounded down towards zero to the
next integer. The rounding mode passed with the parameter mc
is
not considered. But if the precision of mc > 0
and the integral
part requires more digits, then an ArithmeticException
is thrown.
Parameters  

divisor 
BigDecimal : value by which this is divided. 
mc 
MathContext : math context which determines the maximal precision of the
result. 
Returns  

BigDecimal 
integral part of this / divisor . 
Throws  

NullPointerException 
if divisor == null or mc == null . 
ArithmeticException 
if divisor == 0 . 
ArithmeticException 
if mc.getPrecision() > 0 and the result requires more
digits to be represented.

divideToIntegralValue
BigDecimal divideToIntegralValue (BigDecimal divisor)
Returns a new BigDecimal
whose value is the integral part of
this / divisor
. The quotient is rounded down towards zero to the
next integer. For example, 0.5/0.2 = 2
.
Parameters  

divisor 
BigDecimal : value by which this is divided. 
Returns  

BigDecimal 
integral part of this / divisor . 
Throws  

NullPointerException 
if divisor == null . 
ArithmeticException 
if divisor == 0 .

doubleValue
double doubleValue ()
Returns this BigDecimal
as a double value. If this
is too
big to be represented as an float, then Double.POSITIVE_INFINITY
or Double.NEGATIVE_INFINITY
is returned.
Note, that if the unscaled value has more than 53 significant digits, then this decimal cannot be represented exactly in a double variable. In this case the result is rounded.
For example, if the instance x1 = new BigDecimal("0.1")
cannot be
represented exactly as a double, and thus x1.equals(new
BigDecimal(x1.doubleValue())
returns false
for this case.
Similarly, if the instance new BigDecimal(9007199254740993L)
is
converted to a double, the result is 9.007199254740992E15
.
Returns  

double 
this BigDecimal as a double value.

equals
boolean equals (Object x)
Returns true
if x
is a BigDecimal
instance and if
this instance is equal to this big decimal. Two big decimals are equal if
their unscaled value and their scale is equal. For example, 1.0
(10*10^{1}) is not equal to 1.00 (100*10^{2}). Similarly, zero
instances are not equal if their scale differs.
Parameters  

x 
Object : the reference object with which to compare. 
Returns  

boolean 
true if this object is the same as the obj
argument; false otherwise. 
floatValue
float floatValue ()
Returns this BigDecimal
as a float value. If this
is too
big to be represented as an float, then Float.POSITIVE_INFINITY
or Float.NEGATIVE_INFINITY
is returned.
Note, that if the unscaled value has more than 24 significant digits, then this decimal cannot be represented exactly in a float variable. In this case the result is rounded.
For example, if the instance x1 = new BigDecimal("0.1")
cannot be
represented exactly as a float, and thus x1.equals(new
BigDecimal(x1.floatValue())
returns false
for this case.
Similarly, if the instance new BigDecimal(16777217)
is converted
to a float, the result is 1.6777216E
7.
Returns  

float 
this BigDecimal as a float value.

hashCode
int hashCode ()
Returns a hash code for this BigDecimal
.
Returns  

int 
hash code for this .

intValue
int intValue ()
Returns this BigDecimal
as an int value. Any fractional part is
discarded. If the integral part of this
is too big to be
represented as an int, then this % 2<sup>32</sup>
is returned.
Returns  

int 
the numeric value represented by this object after conversion
to type int .

intValueExact
int intValueExact ()
Returns this BigDecimal
as a int value if it has no fractional
part and if its value fits to the int range ([2^{31}..2^{31}1]). If
these conditions are not met, an ArithmeticException
is thrown.
Returns  

int 
Throws  

ArithmeticException 
if rounding is necessary or the number doesn't fit in an int. 
longValue
long longValue ()
Returns this BigDecimal
as an long value. Any fractional part is
discarded. If the integral part of this
is too big to be
represented as an long, then this % 2<sup>64</sup>
is returned.
Returns  

long 
the numeric value represented by this object after conversion
to type long .

longValueExact
long longValueExact ()
Returns this BigDecimal
as a long value if it has no fractional
part and if its value fits to the int range ([2^{63}..2^{63}1]). If
these conditions are not met, an ArithmeticException
is thrown.
Returns  

long 
Throws  

ArithmeticException 
if rounding is necessary or the number doesn't fit in a long. 
max
BigDecimal max (BigDecimal val)
Returns the maximum of this BigDecimal
and val
.
Parameters  

val 
BigDecimal : value to be used to compute the maximum with this. 
Returns  

BigDecimal 
max(this, val . 
Throws  

NullPointerException 
if val == null .

min
BigDecimal min (BigDecimal val)
Returns the minimum of this BigDecimal
and val
.
Parameters  

val 
BigDecimal : value to be used to compute the minimum with this. 
Returns  

BigDecimal 
min(this, val . 
Throws  

NullPointerException 
if val == null .

movePointLeft
BigDecimal movePointLeft (int n)
Returns a new BigDecimal
instance where the decimal point has
been moved n
places to the left. If n < 0
then the
decimal point is moved n
places to the right.
The result is obtained by changing its scale. If the scale of the result becomes negative, then its precision is increased such that the scale is zero.
Note, that movePointLeft(0)
returns a result which is
mathematically equivalent, but which has scale >= 0
.
Parameters  

n 
int 
Returns  

BigDecimal 
movePointRight
BigDecimal movePointRight (int n)
Returns a new BigDecimal
instance where the decimal point has
been moved n
places to the right. If n < 0
then the
decimal point is moved n
places to the left.
The result is obtained by changing its scale. If the scale of the result becomes negative, then its precision is increased such that the scale is zero.
Note, that movePointRight(0)
returns a result which is
mathematically equivalent, but which has scale >= 0.
Parameters  

n 
int 
Returns  

BigDecimal 
multiply
BigDecimal multiply (BigDecimal multiplicand, MathContext mc)
Returns a new BigDecimal
whose value is this *
multiplicand
. The result is rounded according to the passed context
mc
.
Parameters  

multiplicand 
BigDecimal : value to be multiplied with this . 
mc 
MathContext : rounding mode and precision for the result of this operation. 
Returns  

BigDecimal 
this * multiplicand . 
Throws  

NullPointerException 
if multiplicand == null or mc == null .

multiply
BigDecimal multiply (BigDecimal multiplicand)
Returns a new BigDecimal
whose value is this *
multiplicand
. The scale of the result is the sum of the scales of the
two arguments.
Parameters  

multiplicand 
BigDecimal : value to be multiplied with this . 
Returns  

BigDecimal 
this * multiplicand . 
Throws  

NullPointerException 
if multiplicand == null .

negate
BigDecimal negate ()
Returns a new BigDecimal
whose value is the this
. The
scale of the result is the same as the scale of this.
Returns  

BigDecimal 
this

negate
BigDecimal negate (MathContext mc)
Returns a new BigDecimal
whose value is the this
. The
result is rounded according to the passed context mc
.
Parameters  

mc 
MathContext : rounding mode and precision for the result of this operation. 
Returns  

BigDecimal 
this

plus
BigDecimal plus ()
Returns a new BigDecimal
whose value is +this
. The scale
of the result is the same as the scale of this.
Returns  

BigDecimal 
this

plus
BigDecimal plus (MathContext mc)
Returns a new BigDecimal
whose value is +this
. The result
is rounded according to the passed context mc
.
Parameters  

mc 
MathContext : rounding mode and precision for the result of this operation. 
Returns  

BigDecimal 
this , rounded

pow
BigDecimal pow (int n, MathContext mc)
Returns a new BigDecimal
whose value is this<sup>n</sup>
. The
result is rounded according to the passed context mc
.
Implementation Note: The implementation is based on the ANSI standard X3.2741996 algorithm.
Parameters  

n 
int 
mc 
MathContext : rounding mode and precision for the result of this operation. 
Returns  

BigDecimal 
Throws  

ArithmeticException 
if n < 0 or n > 999999999 .

pow
BigDecimal pow (int n)
Returns a new BigDecimal
whose value is this<sup>n</sup>
. The
scale of the result is n * this.scale()
.
x.pow(0)
returns 1
, even if x == 0
.
Implementation Note: The implementation is based on the ANSI standard X3.2741996 algorithm.
Parameters  

n 
int 
Returns  

BigDecimal 
Throws  

ArithmeticException 
if n < 0 or n > 999999999 .

precision
int precision ()
Returns the precision of this BigDecimal
. The precision is the
number of decimal digits used to represent this decimal. It is equivalent
to the number of digits of the unscaled value. The precision of 0
is 1
(independent of the scale).
Returns  

int 
the precision of this BigDecimal .

remainder
BigDecimal remainder (BigDecimal divisor)
Returns a new BigDecimal
whose value is this % divisor
.
The remainder is defined as this 
this.divideToIntegralValue(divisor) * divisor
.
Parameters  

divisor 
BigDecimal : value by which this is divided. 
Returns  

BigDecimal 
this % divisor . 
Throws  

NullPointerException 
if divisor == null . 
ArithmeticException 
if divisor == 0 .

remainder
BigDecimal remainder (BigDecimal divisor, MathContext mc)
Returns a new BigDecimal
whose value is this % divisor
.
The remainder is defined as this 
this.divideToIntegralValue(divisor) * divisor
.
The specified rounding mode mc
is used for the division only.
Parameters  

divisor 
BigDecimal : value by which this is divided. 
mc 
MathContext : rounding mode and precision to be used. 
Returns  

BigDecimal 
this % divisor . 
Throws  

NullPointerException 
if divisor == null . 
ArithmeticException 
if divisor == 0 . 
ArithmeticException 
if mc.getPrecision() > 0 and the result of this.divideToIntegralValue(divisor, mc) requires more digits
to be represented.

round
BigDecimal round (MathContext mc)
Returns a new BigDecimal
whose value is this
, rounded
according to the passed context mc
.
If mc.precision = 0
, then no rounding is performed.
If mc.precision > 0
and mc.roundingMode == UNNECESSARY
,
then an ArithmeticException
is thrown if the result cannot be
represented exactly within the given precision.
Parameters  

mc 
MathContext : rounding mode and precision for the result of this operation. 
Returns  

BigDecimal 
this rounded according to the passed context. 
Throws  

ArithmeticException 
if mc.precision > 0 and mc.roundingMode ==
UNNECESSARY and this cannot be represented within the given
precision.

scale
int scale ()
Returns the scale of this BigDecimal
. The scale is the number of
digits behind the decimal point. The value of this BigDecimal
is
the unsignedValue * 10<sup>scale</sup>
. If the scale is negative,
then this BigDecimal
represents a big integer.
Returns  

int 
the scale of this BigDecimal .

scaleByPowerOfTen
BigDecimal scaleByPowerOfTen (int n)
Returns a new BigDecimal
whose value is this * 10<sup>n</sup>
.
The scale of the result is this.scale()
 n
.
The precision of the result is the precision of this
.
This method has the same effect as movePointRight(int)
, except that
the precision is not changed.
Parameters  

n 
int 
Returns  

BigDecimal 
setScale
BigDecimal setScale (int newScale, int roundingMode)
Returns a new BigDecimal
instance with the specified scale.
If the new scale is greater than the old scale, then additional zeros are added to the unscaled value. In this case no rounding is necessary.
If the new scale is smaller than the old scale, then trailing digits are removed. If these trailing digits are not zero, then the remaining unscaled value has to be rounded. For this rounding operation the specified rounding mode is used.
Parameters  

newScale 
int : scale of the result returned. 
roundingMode 
int : rounding mode to be used to round the result. 
Returns  

BigDecimal 
a new BigDecimal instance with the specified scale. 
Throws  

IllegalArgumentException 
if roundingMode is not a valid rounding mode. 
ArithmeticException 
if roundingMode == ROUND_UNNECESSARY and rounding is
necessary according to the given scale.

setScale
BigDecimal setScale (int newScale)
Returns a new BigDecimal
instance with the specified scale. If
the new scale is greater than the old scale, then additional zeros are
added to the unscaled value. If the new scale is smaller than the old
scale, then trailing zeros are removed. If the trailing digits are not
zeros then an ArithmeticException is thrown.
If no exception is thrown, then the following equation holds: x.setScale(s).compareTo(x) == 0
.
Parameters  

newScale 
int : scale of the result returned. 
Returns  

BigDecimal 
a new BigDecimal instance with the specified scale. 
Throws  

ArithmeticException 
if rounding would be necessary. 
setScale
BigDecimal setScale (int newScale, RoundingMode roundingMode)
Returns a new BigDecimal
instance with the specified scale.
If the new scale is greater than the old scale, then additional zeros are added to the unscaled value. In this case no rounding is necessary.
If the new scale is smaller than the old scale, then trailing digits are removed. If these trailing digits are not zero, then the remaining unscaled value has to be rounded. For this rounding operation the specified rounding mode is used.
Parameters  

newScale 
int : scale of the result returned. 
roundingMode 
RoundingMode : rounding mode to be used to round the result. 
Returns  

BigDecimal 
a new BigDecimal instance with the specified scale. 
Throws  

NullPointerException 
if roundingMode == null . 
ArithmeticException 
if roundingMode == ROUND_UNNECESSARY and rounding is
necessary according to the given scale.

shortValueExact
short shortValueExact ()
Returns this BigDecimal
as a short value if it has no fractional
part and if its value fits to the short range ([2^{15}..2^{15}1]). If
these conditions are not met, an ArithmeticException
is thrown.
Returns  

short 
Throws  

ArithmeticException 
if rounding is necessary of the number doesn't fit in a short. 
signum
int signum ()
Returns the sign of this BigDecimal
.
Returns  

int 
1 if this < 0 ,
0 if this == 0 ,
1 if this > 0 .

stripTrailingZeros
BigDecimal stripTrailingZeros ()
Returns a new BigDecimal
instance with the same value as this
but with a unscaled value where the trailing zeros have been
removed. If the unscaled value of this
has n trailing zeros, then
the scale and the precision of the result has been reduced by n.
Returns  

BigDecimal 
a new BigDecimal instance equivalent to this where the
trailing zeros of the unscaled value have been removed.

subtract
BigDecimal subtract (BigDecimal subtrahend)
Returns a new BigDecimal
whose value is this  subtrahend
.
The scale of the result is the maximum of the scales of the two arguments.
Parameters  

subtrahend 
BigDecimal : value to be subtracted from this . 
Returns  

BigDecimal 
this  subtrahend . 
Throws  

NullPointerException 
if subtrahend == null .

subtract
BigDecimal subtract (BigDecimal subtrahend, MathContext mc)
Returns a new BigDecimal
whose value is this  subtrahend
.
The result is rounded according to the passed context mc
.
Parameters  

subtrahend 
BigDecimal : value to be subtracted from this . 
mc 
MathContext : rounding mode and precision for the result of this operation. 
Returns  

BigDecimal 
this  subtrahend . 
Throws  

NullPointerException 
if subtrahend == null or mc == null .

toBigInteger
BigInteger toBigInteger ()
Returns this BigDecimal
as a big integer instance. A fractional
part is discarded.
Returns  

BigInteger 
this BigDecimal as a big integer instance.

toBigIntegerExact
BigInteger toBigIntegerExact ()
Returns this BigDecimal
as a big integer instance if it has no
fractional part. If this BigDecimal
has a fractional part, i.e.
if rounding would be necessary, an ArithmeticException
is thrown.
Returns  

BigInteger 
this BigDecimal as a big integer value. 
Throws  

ArithmeticException 
if rounding is necessary. 
toEngineeringString
String toEngineeringString ()
Returns a string representation of this BigDecimal
. This
representation always prints all significant digits of this value.
If the scale is negative or if scale  precision >= 6
then
engineering notation is used. Engineering notation is similar to the
scientific notation except that the exponent is made to be a multiple of
3 such that the integer part is >= 1 and < 1000.
Returns  

String 
a string representation of this in engineering notation
if necessary.

toPlainString
String toPlainString ()
Returns a string representation of this BigDecimal
. No scientific
notation is used. This methods adds zeros where necessary.
If this string representation is used to create a new instance, this
instance is generally not identical to this
as the precision
changes.
x.equals(new BigDecimal(x.toPlainString())
usually returns
false
.
x.compareTo(new BigDecimal(x.toPlainString())
returns 0
.
Returns  

String 
a string representation of this without exponent part.

toString
String toString ()
Returns a canonical string representation of this BigDecimal
. If
necessary, scientific notation is used. This representation always prints
all significant digits of this value.
If the scale is negative or if scale  precision >= 6
then
scientific notation is used.
Returns  

String 
a string representation of this in scientific notation if
necessary.

ulp
BigDecimal ulp ()
Returns the unit in the last place (ULP) of this BigDecimal
instance. An ULP is the distance to the nearest big decimal with the same
precision.
The amount of a rounding error in the evaluation of a floatingpoint operation is often expressed in ULPs. An error of 1 ULP is often seen as a tolerable error.
For class BigDecimal
, the ULP of a number is simply 10^{scale}.
For example, new BigDecimal(0.1).ulp()
returns 1E55
.
Returns  

BigDecimal 
unit in the last place (ULP) of this BigDecimal instance.

unscaledValue
BigInteger unscaledValue ()
Returns the unscaled value (mantissa) of this BigDecimal
instance
as a BigInteger
. The unscaled value can be computed as
this * 10<sup>scale</sup>
.
Returns  

BigInteger 
valueOf
BigDecimal valueOf (double val)
Returns a new BigDecimal
instance whose value is equal to val
. The new decimal is constructed as if the BigDecimal(String)
constructor is called with an argument which is equal to Double.toString(val)
. For example, valueOf("0.1")
is converted to
(unscaled=1, scale=1), although the double 0.1
cannot be
represented exactly as a double value. In contrast to that, a new BigDecimal(0.1)
instance has the value 0.1000000000000000055511151231257827021181583404541015625
with an
unscaled value 1000000000000000055511151231257827021181583404541015625
and the scale 55
.
Parameters  

val 
double : double value to be converted to a BigDecimal . 
Returns  

BigDecimal 
BigDecimal instance with the value val . 
Throws  

NumberFormatException 
if val is infinite or val is not a number

valueOf
BigDecimal valueOf (long unscaledVal)
Returns a new BigDecimal
instance whose value is equal to unscaledVal
. The scale of the result is 0
, and its unscaled
value is unscaledVal
.
Parameters  

unscaledVal 
long : value to be converted to a BigDecimal . 
Returns  

BigDecimal 
BigDecimal instance with the value unscaledVal .

valueOf
BigDecimal valueOf (long unscaledVal, int scale)
Returns a new BigDecimal
instance whose value is equal to unscaledVal * 10<sup>scale</sup>
). The scale of the result is scale
, and its unscaled value is unscaledVal
.
Parameters  

unscaledVal 
long 
scale 
int 
Returns  

BigDecimal 