public class BigDecimal extends Number implements Comparable<BigDecimal>, Serializable
Since the class was modeled to offer all the functionality as the Integer
class does, it provides even methods that operate bitwise on a two's
complement representation of large integers. Note however that the
implementations favors an internal representation where magnitude and sign
are treated separately. Hence such operations are inefficient and should be
discouraged. In simple words: Do NOT implement any bit fields based on
BigInteger.
Modifier and Type  Field and Description 

static BigDecimal 
ONE
The constant one as a
BigDecimal . 
static int 
ROUND_CEILING
Rounding mode to round towards positive infinity.

static int 
ROUND_DOWN
Rounding mode where the values are rounded towards zero.

static int 
ROUND_FLOOR
Rounding mode to round towards negative infinity.

static int 
ROUND_HALF_DOWN
Rounding mode where values are rounded towards the nearest neighbor.

static int 
ROUND_HALF_EVEN
Rounding mode where values are rounded towards the nearest neighbor.

static int 
ROUND_HALF_UP
Rounding mode where values are rounded towards the nearest neighbor.

static int 
ROUND_UNNECESSARY
Rounding mode where the rounding operations throws an
ArithmeticException for the case that rounding is necessary, i.e. 
static int 
ROUND_UP
Rounding mode where positive values are rounded towards positive infinity
and negative values towards negative infinity.

static BigDecimal 
TEN
The constant ten as a
BigDecimal . 
static BigDecimal 
ZERO
The constant zero as a
BigDecimal . 
Constructor and Description 

BigDecimal(BigInteger val)
Constructs a new
BigDecimal instance from the given big integer
val . 
BigDecimal(BigInteger unscaledVal,
int scale)
Constructs a new
BigDecimal instance from a given unscaled value
unscaledVal and a given scale. 
BigDecimal(BigInteger unscaledVal,
int scale,
MathContext mc)
Constructs a new
BigDecimal instance from a given unscaled value
unscaledVal and a given scale. 
BigDecimal(BigInteger val,
MathContext mc)
Constructs a new
BigDecimal instance from the given big integer
val . 
BigDecimal(char[] in)
Constructs a new
BigDecimal instance from a string representation
given as a character array. 
BigDecimal(char[] in,
int offset,
int len)
Constructs a new
BigDecimal instance from a string representation
given as a character array. 
BigDecimal(char[] in,
int offset,
int len,
MathContext mc)
Constructs a new
BigDecimal instance from a string representation
given as a character array. 
BigDecimal(char[] in,
MathContext mc)
Constructs a new
BigDecimal instance from a string representation
given as a character array. 
BigDecimal(double val)
Constructs a new
BigDecimal instance from the 64bit double
val . 
BigDecimal(double val,
MathContext mc)
Constructs a new
BigDecimal instance from the 64bit double
val . 
BigDecimal(int val)
Constructs a new
BigDecimal instance from the given int
val . 
BigDecimal(int val,
MathContext mc)
Constructs a new
BigDecimal instance from the given int val . 
BigDecimal(long val)
Constructs a new
BigDecimal instance from the given long val . 
BigDecimal(long val,
MathContext mc)
Constructs a new
BigDecimal instance from the given long val . 
BigDecimal(String val)
Constructs a new
BigDecimal instance from a string
representation. 
BigDecimal(String val,
MathContext mc)
Constructs a new
BigDecimal instance from a string
representation. 
Modifier and Type  Method and Description 

BigDecimal 
abs()
Returns a new
BigDecimal whose value is the absolute value of
this . 
BigDecimal 
abs(MathContext mc)
Returns a new
BigDecimal whose value is the absolute value of
this . 
BigDecimal 
add(BigDecimal augend)
Returns a new
BigDecimal whose value is this + augend . 
BigDecimal 
add(BigDecimal augend,
MathContext mc)
Returns a new
BigDecimal whose value is this + augend . 
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]). 
int 
compareTo(BigDecimal val)
Compares this
BigDecimal with val . 
BigDecimal 
divide(BigDecimal divisor)
Returns a new
BigDecimal whose value is this / divisor . 
BigDecimal 
divide(BigDecimal divisor,
int roundingMode)
Returns a new
BigDecimal whose value is this / divisor . 
BigDecimal 
divide(BigDecimal divisor,
int scale,
int roundingMode)
Returns a new
BigDecimal whose value is this / divisor . 
BigDecimal 
divide(BigDecimal divisor,
int scale,
RoundingMode roundingMode)
Returns a new
BigDecimal whose value is this / divisor . 
BigDecimal 
divide(BigDecimal divisor,
MathContext mc)
Returns a new
BigDecimal whose value is this / divisor . 
BigDecimal 
divide(BigDecimal divisor,
RoundingMode roundingMode)
Returns a new
BigDecimal whose value is this / divisor . 
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. 
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. 
BigDecimal 
divideToIntegralValue(BigDecimal divisor)
Returns a new
BigDecimal whose value is the integral part of
this / divisor . 
BigDecimal 
divideToIntegralValue(BigDecimal divisor,
MathContext mc)
Returns a new
BigDecimal whose value is the integral part of
this / divisor . 
double 
doubleValue()
Returns this
BigDecimal as a double value. 
boolean 
equals(Object x)
Returns
true if x is a BigDecimal instance and if
this instance is equal to this big decimal. 
float 
floatValue()
Returns this
BigDecimal as a float value. 
int 
hashCode()
Returns a hash code for this
BigDecimal . 
int 
intValue()
Returns this
BigDecimal as an int value. 
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]). 
long 
longValue()
Returns this
BigDecimal as an long value. 
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]). 
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 new
BigDecimal instance where the decimal point has
been moved n places to the left. 
BigDecimal 
movePointRight(int n)
Returns a new
BigDecimal instance where the decimal point has
been moved n places to the right. 
BigDecimal 
multiply(BigDecimal multiplicand)
Returns a new
BigDecimal whose value is this *
multiplicand . 
BigDecimal 
multiply(BigDecimal multiplicand,
MathContext mc)
Returns a new
BigDecimal whose value is this *
multiplicand . 
BigDecimal 
negate()
Returns a new
BigDecimal whose value is the this . 
BigDecimal 
negate(MathContext mc)
Returns a new
BigDecimal whose value is the this . 
BigDecimal 
plus()
Returns a new
BigDecimal whose value is +this . 
BigDecimal 
plus(MathContext mc)
Returns a new
BigDecimal whose value is +this . 
BigDecimal 
pow(int n)
Returns a new
BigDecimal whose value is this ^ n . 
BigDecimal 
pow(int n,
MathContext mc)
Returns a new
BigDecimal whose value is this ^ n . 
int 
precision()
Returns the precision of this
BigDecimal . 
BigDecimal 
remainder(BigDecimal divisor)
Returns a new
BigDecimal whose value is this % divisor . 
BigDecimal 
remainder(BigDecimal divisor,
MathContext mc)
Returns a new
BigDecimal whose value is this % divisor . 
BigDecimal 
round(MathContext mc)
Returns a new
BigDecimal whose value is this , rounded
according to the passed context mc . 
int 
scale()
Returns the scale of this
BigDecimal . 
BigDecimal 
scaleByPowerOfTen(int n)
Returns a new
BigDecimal whose value is this 10^n . 
BigDecimal 
setScale(int newScale)
Returns a new
BigDecimal instance with the specified scale. 
BigDecimal 
setScale(int newScale,
int roundingMode)
Returns a new
BigDecimal instance with the specified scale. 
BigDecimal 
setScale(int newScale,
RoundingMode roundingMode)
Returns a new
BigDecimal instance with the specified scale. 
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]). 
int 
signum()
Returns the sign of this
BigDecimal . 
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. 
BigDecimal 
subtract(BigDecimal subtrahend)
Returns a new
BigDecimal whose value is this  subtrahend . 
BigDecimal 
subtract(BigDecimal subtrahend,
MathContext mc)
Returns a new
BigDecimal whose value is this  subtrahend . 
BigInteger 
toBigInteger()
Returns this
BigDecimal as a big integer instance. 
BigInteger 
toBigIntegerExact()
Returns this
BigDecimal as a big integer instance if it has no
fractional part. 
String 
toEngineeringString()
Returns a string representation of this
BigDecimal . 
String 
toPlainString()
Returns a string representation of this
BigDecimal . 
String 
toString()
Returns a canonical string representation of this
BigDecimal . 
BigDecimal 
ulp()
Returns the unit in the last place (ULP) of this
BigDecimal
instance. 
BigInteger 
unscaledValue()
Returns the unscaled value (mantissa) of this
BigDecimal instance
as a BigInteger . 
static BigDecimal 
valueOf(double val)
Returns a new
BigDecimal instance whose value is equal to val . 
static BigDecimal 
valueOf(long unscaledVal)
Returns a new
BigDecimal instance whose value is equal to unscaledVal . 
static BigDecimal 
valueOf(long unscaledVal,
int scale)
Returns a new
BigDecimal instance whose value is equal to unscaledVal 10^(scale ). 
byteValue, shortValue
public static final int ROUND_UP
RoundingMode.UP
,
Constant Field Valuespublic static final int ROUND_DOWN
RoundingMode.DOWN
,
Constant Field Valuespublic static final int ROUND_CEILING
ROUND_UP
, for negative values as
ROUND_DOWN
.RoundingMode.CEILING
,
Constant Field Valuespublic static final int ROUND_FLOOR
ROUND_DOWN
, for negative values as
ROUND_UP
.RoundingMode.FLOOR
,
Constant Field Valuespublic static final int ROUND_HALF_UP
RoundingMode.HALF_UP
,
Constant Field Valuespublic static final int ROUND_HALF_DOWN
RoundingMode.HALF_DOWN
,
Constant Field Valuespublic static final int ROUND_HALF_EVEN
RoundingMode.HALF_EVEN
,
Constant Field Valuespublic static final int ROUND_UNNECESSARY
ArithmeticException
for the case that rounding is necessary, i.e. for
the case that the value cannot be represented exactly.public static final BigDecimal ZERO
BigDecimal
.public static final BigDecimal ONE
BigDecimal
.public static final BigDecimal TEN
BigDecimal
.public BigDecimal(char[] in, int offset, int len)
BigDecimal
instance from a string representation
given as a character array.in
 array of characters containing the string representation of
this BigDecimal
.offset
 first index to be copied.len
 number of characters to be used.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.public BigDecimal(char[] in, int offset, int len, MathContext mc)
BigDecimal
instance from a string representation
given as a character array.in
 array of characters containing the string representation of
this BigDecimal
.offset
 first index to be copied.len
 number of characters to be used.mc
 rounding mode and precision for the result of this operation.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.public BigDecimal(char[] in)
BigDecimal
instance from a string representation
given as a character array.in
 array of characters containing the string representation of
this BigDecimal
.NumberFormatException
 if in
does not contain a valid string representation
of a big decimal.public BigDecimal(char[] in, MathContext mc)
BigDecimal
instance from a string representation
given as a character array. The result is rounded according to the
specified math context.in
 array of characters containing the string representation of
this BigDecimal
.mc
 rounding mode and precision for the result of this operation.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.public BigDecimal(String val)
BigDecimal
instance from a string
representation.val
 string containing the string representation of this BigDecimal
.NumberFormatException
 if val
does not contain a valid string representation
of a big decimal.public BigDecimal(String val, MathContext mc)
BigDecimal
instance from a string
representation. The result is rounded according to the specified math
context.val
 string containing the string representation of this BigDecimal
.mc
 rounding mode and precision for the result of this operation.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.public BigDecimal(double val)
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.
val
 double value to be converted to a BigDecimal
instance.NumberFormatException
 if val
is infinity or not a number.public BigDecimal(double val, MathContext mc)
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.
val
 double value to be converted to a BigDecimal
instance.mc
 rounding mode and precision for the result of this operation.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.public BigDecimal(BigInteger val)
BigDecimal
instance from the given big integer
val
. The scale of the result is 0
.val
 BigInteger
value to be converted to a BigDecimal
instance.public BigDecimal(BigInteger val, MathContext mc)
BigDecimal
instance from the given big integer
val
. The scale of the result is 0
.val
 BigInteger
value to be converted to a BigDecimal
instance.mc
 rounding mode and precision for the result of this operation.ArithmeticException
 if mc.precision > 0
and mc.roundingMode ==
UNNECESSARY
and the new big decimal cannot be represented
within the given precision without rounding.public BigDecimal(BigInteger unscaledVal, int scale)
BigDecimal
instance from a given unscaled value
unscaledVal
and a given scale. The value of this instance is
unscaledVal
10^(scale
).unscaledVal
 BigInteger
representing the unscaled value of this
BigDecimal
instance.scale
 scale of this BigDecimal
instance.NullPointerException
 if unscaledVal == null
.public BigDecimal(BigInteger unscaledVal, int scale, MathContext mc)
BigDecimal
instance from a given unscaled value
unscaledVal
and a given scale. The value of this instance is
unscaledVal
10^(scale
). The result is rounded according
to the specified math context.unscaledVal
 BigInteger
representing the unscaled value of this
BigDecimal
instance.scale
 scale of this BigDecimal
instance.mc
 rounding mode and precision for the result of this operation.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
.public BigDecimal(int val)
BigDecimal
instance from the given int
val
. The scale of the result is 0.val
 int value to be converted to a BigDecimal
instance.public BigDecimal(int val, MathContext mc)
BigDecimal
instance from the given int val
. The scale of the result is 0
. The result is rounded
according to the specified math context.val
 int value to be converted to a BigDecimal
instance.mc
 rounding mode and precision for the result of this operation.ArithmeticException
 if mc.precision > 0
and c.roundingMode ==
UNNECESSARY
and the new big decimal cannot be represented
within the given precision without rounding.public BigDecimal(long val)
BigDecimal
instance from the given long val
. The scale of the result is 0
.val
 long value to be converted to a BigDecimal
instance.public BigDecimal(long val, MathContext mc)
BigDecimal
instance from the given long val
. The scale of the result is 0
. The result is rounded
according to the specified math context.val
 long value to be converted to a BigDecimal
instance.mc
 rounding mode and precision for the result of this operation.ArithmeticException
 if mc.precision > 0
and mc.roundingMode ==
UNNECESSARY
and the new big decimal cannot be represented
within the given precision without rounding.public static BigDecimal valueOf(long unscaledVal, int scale)
BigDecimal
instance whose value is equal to unscaledVal
10^(scale
). The scale of the result is scale
, and its unscaled value is unscaledVal
.unscaledVal
 unscaled value to be used to construct the new BigDecimal
.scale
 scale to be used to construct the new BigDecimal
.BigDecimal
instance with the value unscaledVal
*
10^(unscaledVal
).public static BigDecimal valueOf(long unscaledVal)
BigDecimal
instance whose value is equal to unscaledVal
. The scale of the result is 0
, and its unscaled
value is unscaledVal
.unscaledVal
 value to be converted to a BigDecimal
.BigDecimal
instance with the value unscaledVal
.public static BigDecimal valueOf(double val)
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
.val
 double value to be converted to a BigDecimal
.BigDecimal
instance with the value val
.NumberFormatException
 if val
is infinite or val
is not a numberpublic BigDecimal add(BigDecimal augend)
BigDecimal
whose value is this + augend
.
The scale of the result is the maximum of the scales of the two
arguments.augend
 value to be added to this
.this + augend
.NullPointerException
 if augend == null
.public BigDecimal add(BigDecimal augend, MathContext mc)
BigDecimal
whose value is this + augend
.
The result is rounded according to the passed context mc
.augend
 value to be added to this
.mc
 rounding mode and precision for the result of this operation.this + augend
.NullPointerException
 if augend == null
or mc == null
.public BigDecimal subtract(BigDecimal subtrahend)
BigDecimal
whose value is this  subtrahend
.
The scale of the result is the maximum of the scales of the two arguments.subtrahend
 value to be subtracted from this
.this  subtrahend
.NullPointerException
 if subtrahend == null
.public BigDecimal subtract(BigDecimal subtrahend, MathContext mc)
BigDecimal
whose value is this  subtrahend
.
The result is rounded according to the passed context mc
.subtrahend
 value to be subtracted from this
.mc
 rounding mode and precision for the result of this operation.this  subtrahend
.NullPointerException
 if subtrahend == null
or mc == null
.public BigDecimal multiply(BigDecimal multiplicand)
BigDecimal
whose value is this *
multiplicand
. The scale of the result is the sum of the scales of the
two arguments.multiplicand
 value to be multiplied with this
.this * multiplicand
.NullPointerException
 if multiplicand == null
.public BigDecimal multiply(BigDecimal multiplicand, MathContext mc)
BigDecimal
whose value is this *
multiplicand
. The result is rounded according to the passed context
mc
.multiplicand
 value to be multiplied with this
.mc
 rounding mode and precision for the result of this operation.this * multiplicand
.NullPointerException
 if multiplicand == null
or mc == null
.public BigDecimal divide(BigDecimal divisor, int scale, int roundingMode)
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.divisor
 value by which this
is divided.scale
 the scale of the result returned.roundingMode
 rounding mode to be used to round the result.this / divisor
rounded according to the given rounding
mode.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.public BigDecimal divide(BigDecimal divisor, int scale, RoundingMode roundingMode)
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.divisor
 value by which this
is divided.scale
 the scale of the result returned.roundingMode
 rounding mode to be used to round the result.this / divisor
rounded according to the given rounding
mode.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.public BigDecimal divide(BigDecimal divisor, int roundingMode)
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.divisor
 value by which this
is divided.roundingMode
 rounding mode to be used to round the result.this / divisor
rounded according to the given rounding
mode.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.public BigDecimal divide(BigDecimal divisor, RoundingMode roundingMode)
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.divisor
 value by which this
is divided.roundingMode
 rounding mode to be used to round the result.this / divisor
rounded according to the given rounding
mode.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.public BigDecimal divide(BigDecimal divisor)
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
.divisor
 value by which this
is divided.this / divisor
.NullPointerException
 if divisor == null
.ArithmeticException
 if divisor == 0
.ArithmeticException
 if the result cannot be represented exactly.public BigDecimal divide(BigDecimal divisor, MathContext mc)
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)
.divisor
 value by which this
is divided.mc
 rounding mode and precision for the result of this operation.this / divisor
.NullPointerException
 if divisor == null
or mc == null
.ArithmeticException
 if divisor == 0
.ArithmeticException
 if mc.getRoundingMode() == UNNECESSARY
and rounding
is necessary according mc.getPrecision()
.public BigDecimal divideToIntegralValue(BigDecimal divisor)
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
.divisor
 value by which this
is divided.this / divisor
.NullPointerException
 if divisor == null
.ArithmeticException
 if divisor == 0
.public BigDecimal divideToIntegralValue(BigDecimal divisor, MathContext mc)
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.divisor
 value by which this
is divided.mc
 math context which determines the maximal precision of the
result.this / divisor
.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.public BigDecimal remainder(BigDecimal divisor)
BigDecimal
whose value is this % divisor
.
The remainder is defined as this 
this.divideToIntegralValue(divisor) * divisor
.
divisor
 value by which this
is divided.this % divisor
.NullPointerException
 if divisor == null
.ArithmeticException
 if divisor == 0
.public BigDecimal remainder(BigDecimal divisor, MathContext mc)
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.
divisor
 value by which this
is divided.mc
 rounding mode and precision to be used.this % divisor
.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.public BigDecimal[] divideAndRemainder(BigDecimal divisor)
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.divisor
 value by which this
is divided.[this.divideToIntegralValue(divisor),
this.remainder(divisor)]
.NullPointerException
 if divisor == null
.ArithmeticException
 if divisor == 0
.divideToIntegralValue(java.math.BigDecimal)
,
remainder(java.math.BigDecimal)
public BigDecimal[] divideAndRemainder(BigDecimal divisor, MathContext mc)
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.divisor
 value by which this
is divided.mc
 math context which determines the maximal precision of the
result.[this.divideToIntegralValue(divisor),
this.remainder(divisor)]
.NullPointerException
 if divisor == null
.ArithmeticException
 if divisor == 0
.divideToIntegralValue(java.math.BigDecimal)
,
remainder(java.math.BigDecimal)
public BigDecimal pow(int n)
BigDecimal
whose value is this ^ n
. The
scale of the result is n
times the scales of this
.
x.pow(0)
returns 1
, even if x == 0
.
Implementation Note: The implementation is based on the ANSI standard X3.2741996 algorithm.
n
 exponent to which this
is raised.this ^ n
.ArithmeticException
 if n < 0
or n > 999999999
.public BigDecimal pow(int n, MathContext mc)
BigDecimal
whose value is this ^ n
. The
result is rounded according to the passed context mc
.
Implementation Note: The implementation is based on the ANSI standard X3.2741996 algorithm.
n
 exponent to which this
is raised.mc
 rounding mode and precision for the result of this operation.this ^ n
.ArithmeticException
 if n < 0
or n > 999999999
.public BigDecimal abs()
BigDecimal
whose value is the absolute value of
this
. The scale of the result is the same as the scale of this.abs(this)
public BigDecimal abs(MathContext mc)
BigDecimal
whose value is the absolute value of
this
. The result is rounded according to the passed context
mc
.mc
 rounding mode and precision for the result of this operation.abs(this)
public BigDecimal negate()
BigDecimal
whose value is the this
. The
scale of the result is the same as the scale of this.this
public BigDecimal negate(MathContext mc)
BigDecimal
whose value is the this
. The
result is rounded according to the passed context mc
.mc
 rounding mode and precision for the result of this operation.this
public BigDecimal plus()
BigDecimal
whose value is +this
. The scale
of the result is the same as the scale of this.this
public BigDecimal plus(MathContext mc)
BigDecimal
whose value is +this
. The result
is rounded according to the passed context mc
.mc
 rounding mode and precision for the result of this operation.this
, roundedpublic int signum()
BigDecimal
.1
if this < 0
,
0
if this == 0
,
1
if this > 0
.public int scale()
BigDecimal
. The scale is the number of
digits behind the decimal point. The value of this BigDecimal
is
the unsignedValue * 10^(scale). If the scale is negative, then this
BigDecimal
represents a big integer.BigDecimal
.public int precision()
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).BigDecimal
.public BigInteger unscaledValue()
BigDecimal
instance
as a BigInteger
. The unscaled value can be computed as this
10^(scale).public BigDecimal round(MathContext mc)
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.
mc
 rounding mode and precision for the result of this operation.this
rounded according to the passed context.ArithmeticException
 if mc.precision > 0
and mc.roundingMode ==
UNNECESSARY
and this cannot be represented within the given
precision.public BigDecimal setScale(int newScale, RoundingMode roundingMode)
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.
newScale
 scale of the result returned.roundingMode
 rounding mode to be used to round the result.BigDecimal
instance with the specified scale.NullPointerException
 if roundingMode == null
.ArithmeticException
 if roundingMode == ROUND_UNNECESSARY
and rounding is
necessary according to the given scale.public BigDecimal setScale(int newScale, int roundingMode)
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.
newScale
 scale of the result returned.roundingMode
 rounding mode to be used to round the result.BigDecimal
instance with the specified scale.IllegalArgumentException
 if roundingMode
is not a valid rounding mode.ArithmeticException
 if roundingMode == ROUND_UNNECESSARY
and rounding is
necessary according to the given scale.public BigDecimal setScale(int newScale)
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
.
newScale
 scale of the result returned.BigDecimal
instance with the specified scale.ArithmeticException
 if rounding would be necessary.public BigDecimal movePointLeft(int n)
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
.
n
 number of placed the decimal point has to be moved.this * 10^(n
).public BigDecimal movePointRight(int n)
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.
n
 number of placed the decimal point has to be moved.this * 10^n
.public BigDecimal scaleByPowerOfTen(int n)
BigDecimal
whose value is this
10^n
.
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.
n
 number of places the decimal point has to be moved.this * 10^n
public BigDecimal stripTrailingZeros()
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.BigDecimal
instance equivalent to this where the
trailing zeros of the unscaled value have been removed.public int compareTo(BigDecimal val)
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.compareTo
in interface Comparable<BigDecimal>
val
 value to be compared with this
.1
if this > val
, 1
if this < val
,
0
if this == val
.NullPointerException
 if val == null
.public boolean equals(Object x)
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.equals
in class Object
x
 object to be compared with this
.x
is a BigDecimal
and this == x
.Object.hashCode()
public BigDecimal min(BigDecimal val)
BigDecimal
and val
.val
 value to be used to compute the minimum with this.min(this, val
.NullPointerException
 if val == null
.public BigDecimal max(BigDecimal val)
BigDecimal
and val
.val
 value to be used to compute the maximum with this.max(this, val
.NullPointerException
 if val == null
.public int hashCode()
BigDecimal
.hashCode
in class Object
this
.Object.equals(java.lang.Object)
public String toString()
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.
public String toEngineeringString()
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.
this
in engineering notation
if necessary.public String toPlainString()
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
.
this
without exponent part.public BigInteger toBigInteger()
BigDecimal
as a big integer instance. A fractional
part is discarded.BigDecimal
as a big integer instance.public BigInteger toBigIntegerExact()
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.BigDecimal
as a big integer value.ArithmeticException
 if rounding is necessary.public long longValue()
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^64 is returned.public long longValueExact()
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.BigDecimal
as a long value.ArithmeticException
 if rounding is necessary or the number doesn't fit in a long.public int intValue()
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^32 is returned.public int intValueExact()
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.BigDecimal
as a int value.ArithmeticException
 if rounding is necessary or the number doesn't fit in a int.public short shortValueExact()
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.BigDecimal
as a short value.ArithmeticException
 if rounding is necessary of the number doesn't fit in a
short.public byte byteValueExact()
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.BigDecimal
as a byte value.ArithmeticException
 if rounding is necessary or the number doesn't fit in a byte.public float floatValue()
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.folatValue())
returns false
for this case.
Similarly, if the instance new BigDecimal(16777217)
is converted
to a float, the result is 1.6777216E
7.
floatValue
in class Number
BigDecimal
as a float value.public double doubleValue()
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
.
doubleValue
in class Number
BigDecimal
as a double value.public BigDecimal ulp()
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
.
BigDecimal
instance.