java.math.BigDecimal
Class which represents immutable arbritary precision decimal numbers. Each
BigDecimal
instance is represented with a unscaled arbitrary
precision mantissa (the unscaled value) and a scale. The value of the
BigDecimal
is unscaledValue
* 10^{-scale
}.
Summary
Constants
|
|
|
Value |
|
BigDecimal |
ONE |
The constant one as a BigDecimal. |
|
|
int |
ROUND_CEILING |
Rounding mode to round towards positive infinity. |
2 |
0x00000002 |
int |
ROUND_DOWN |
Rounding mode where the values are rounded towards zero. |
1 |
0x00000001 |
int |
ROUND_FLOOR |
Rounding mode to round towards negative infinity. |
3 |
0x00000003 |
int |
ROUND_HALF_DOWN |
Rounding mode where values are rounded towards the nearest neighbour. |
5 |
0x00000005 |
int |
ROUND_HALF_EVEN |
Rounding mode where values are rounded towards the nearest neighbour. |
6 |
0x00000006 |
int |
ROUND_HALF_UP |
Rounding mode where values are rounded towards the nearest neighbour. |
4 |
0x00000004 |
int |
ROUND_UNNECESSARY |
Rounding mode where the rounding operations throws an ArithmeticException
for the case that rounding is necessary, i.e. |
7 |
0x00000007 |
int |
ROUND_UP |
Rounding mode where positive values are rounded towards positive infinity
and negative values towards negative infinity. |
0 |
0x00000000 |
BigDecimal |
TEN |
The constant ten as a BigDecimal. |
|
|
BigDecimal |
ZERO |
The constant zero as a BigDecimal. |
|
|
Public Constructors
|
|
|
|
|
|
BigDecimal(char[] in, int offset, int len) |
|
|
|
|
|
|
BigDecimal(char[] in, int offset, int len, MathContext mc) |
|
|
|
|
|
|
BigDecimal(char[] in) |
|
|
|
|
|
|
BigDecimal(char[] in, MathContext mc) |
|
|
|
|
|
|
BigDecimal(String val) |
|
|
|
|
|
|
BigDecimal(String val, MathContext mc) |
|
|
|
|
|
|
BigDecimal(double val) |
|
|
|
|
|
|
BigDecimal(double val, MathContext mc) |
|
|
|
|
|
|
BigDecimal(BigInteger val) |
|
|
|
|
|
|
BigDecimal(BigInteger val, MathContext mc) |
|
|
|
|
|
|
BigDecimal(BigInteger unscaledVal, int scale) |
|
|
|
|
|
|
BigDecimal(BigInteger unscaledVal, int scale, MathContext mc) |
|
|
|
|
|
|
BigDecimal(int val) |
|
|
|
|
|
|
BigDecimal(int val, MathContext mc) |
|
|
|
|
|
|
BigDecimal(long val) |
|
|
|
|
|
|
BigDecimal(long val, MathContext mc) |
Public Methods
|
|
|
|
|
BigDecimal |
abs() |
|
|
|
|
|
BigDecimal |
abs(MathContext mc) |
|
|
|
|
|
BigDecimal |
add(BigDecimal augend) |
|
|
|
|
|
BigDecimal |
add(BigDecimal augend, MathContext mc) |
|
|
|
|
|
byte |
byteValueExact() |
|
|
|
|
|
int |
compareTo(BigDecimal val) |
|
|
|
|
|
BigDecimal |
divide(BigDecimal divisor, int scale, RoundingMode roundingMode) |
|
|
|
|
|
BigDecimal |
divide(BigDecimal divisor, RoundingMode roundingMode) |
|
|
|
|
|
BigDecimal |
divide(BigDecimal divisor, MathContext mc) |
|
|
|
|
|
BigDecimal |
divide(BigDecimal divisor) |
|
|
|
|
|
BigDecimal |
divide(BigDecimal divisor, int roundingMode) |
|
|
|
|
|
BigDecimal |
divide(BigDecimal divisor, int scale, int roundingMode) |
|
|
|
|
|
BigDecimal[] |
divideAndRemainder(BigDecimal divisor, MathContext mc) |
|
|
|
|
|
BigDecimal[] |
divideAndRemainder(BigDecimal divisor) |
|
|
|
|
|
BigDecimal |
divideToIntegralValue(BigDecimal divisor, MathContext mc) |
|
|
|
|
|
BigDecimal |
divideToIntegralValue(BigDecimal divisor) |
|
|
|
|
|
double |
doubleValue() |
|
|
|
|
|
boolean |
equals(Object x) |
|
|
|
|
|
float |
floatValue() |
|
|
|
|
|
int |
hashCode() |
|
|
|
|
|
int |
intValue() |
|
|
|
|
|
int |
intValueExact() |
|
|
|
|
|
long |
longValue() |
|
|
|
|
|
long |
longValueExact() |
|
|
|
|
|
BigDecimal |
max(BigDecimal val) |
|
|
|
|
|
BigDecimal |
min(BigDecimal val) |
|
|
|
|
|
BigDecimal |
movePointLeft(int n) |
|
|
|
|
|
BigDecimal |
movePointRight(int n) |
|
|
|
|
|
BigDecimal |
multiply(BigDecimal multiplicand, MathContext mc) |
|
|
|
|
|
BigDecimal |
multiply(BigDecimal multiplicand) |
|
|
|
|
|
BigDecimal |
negate(MathContext mc) |
|
|
|
|
|
BigDecimal |
negate() |
|
|
|
|
|
BigDecimal |
plus() |
|
|
|
|
|
BigDecimal |
plus(MathContext mc) |
|
|
|
|
|
BigDecimal |
pow(int n, MathContext mc) |
|
|
|
|
|
BigDecimal |
pow(int n) |
|
|
|
|
|
int |
precision() |
|
|
|
|
|
BigDecimal |
remainder(BigDecimal divisor, MathContext mc) |
|
|
|
|
|
BigDecimal |
remainder(BigDecimal divisor) |
|
|
|
|
|
BigDecimal |
round(MathContext mc) |
|
|
|
|
|
int |
scale() |
|
|
|
|
|
BigDecimal |
scaleByPowerOfTen(int n) |
|
|
|
|
|
BigDecimal |
setScale(int newScale, RoundingMode roundingMode) |
|
|
|
|
|
BigDecimal |
setScale(int newScale) |
|
|
|
|
|
BigDecimal |
setScale(int newScale, int roundingMode) |
|
|
|
|
|
short |
shortValueExact() |
|
|
|
|
|
int |
signum() |
|
|
|
|
|
BigDecimal |
stripTrailingZeros() |
|
|
|
|
|
BigDecimal |
subtract(BigDecimal subtrahend, MathContext mc) |
|
|
|
|
|
BigDecimal |
subtract(BigDecimal subtrahend) |
|
|
|
|
|
BigInteger |
toBigInteger() |
|
|
|
|
|
BigInteger |
toBigIntegerExact() |
|
|
|
|
|
String |
toEngineeringString() |
|
|
|
|
|
String |
toPlainString() |
|
|
|
|
|
String |
toString() |
|
|
|
|
|
BigDecimal |
ulp() |
|
|
|
|
|
BigInteger |
unscaledValue() |
|
|
|
static |
|
BigDecimal |
valueOf(double val) |
|
|
|
static |
|
BigDecimal |
valueOf(long unscaledVal, int scale) |
|
|
|
static |
|
BigDecimal |
valueOf(long unscaledVal) |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Details
Constants
public
static
final
BigDecimal
ONE
The constant one as a BigDecimal.
public
static
final
int
ROUND_CEILING
Rounding mode to round towards positive infinity. For positive values
this rounding mode behaves as UP, for negative values as DOWN.
Constant Value:
2
(0x00000002)
public
static
final
int
ROUND_DOWN
Rounding mode where the values are rounded towards zero.
Constant Value:
1
(0x00000001)
public
static
final
int
ROUND_FLOOR
Rounding mode to round towards negative infinity. For positive values
this rounding mode behaves as DOWN, for negative values as UP.
Constant Value:
3
(0x00000003)
public
static
final
int
ROUND_HALF_DOWN
Rounding mode where values are rounded towards the nearest neighbour.
Ties are broken by rounding down.
Constant Value:
5
(0x00000005)
public
static
final
int
ROUND_HALF_EVEN
Rounding mode where values are rounded towards the nearest neighbour.
Ties are broken by rounding to the even neighbour.
Constant Value:
6
(0x00000006)
public
static
final
int
ROUND_HALF_UP
Rounding mode where values are rounded towards the nearest neighbour.
Ties are broken by rounding up.
Constant Value:
4
(0x00000004)
public
static
final
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.
Constant Value:
7
(0x00000007)
public
static
final
int
ROUND_UP
Rounding mode where positive values are rounded towards positive infinity
and negative values towards negative infinity.
Constant Value:
0
(0x00000000)
public
static
final
BigDecimal
TEN
The constant ten as a BigDecimal.
public
static
final
BigDecimal
ZERO
The constant zero as a BigDecimal.
Public Constructors
public
BigDecimal(char[] in, int offset, int len)
Constructs a new
BigDecimal
instance from a string representation
given as a character array.
Parameters
in
| array of characters containing the string representation of
this BigDecimal |
offset
| first index to be copied |
len
| number of characters to be used |
public
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
| 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. |
public
BigDecimal(char[] in)
Constructs a new
BigDecimal
instance from a string representation
given as a character array.
Parameters
in
| array of characters containing the string representation of
this BigDecimal . |
public
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
| array of characters containing the string representation of
this BigDecimal . |
mc
| rounding mode and precision for the result of this operation. |
public
BigDecimal(String val)
Constructs a new
BigDecimal
instance from a string
representation.
Parameters
val
| string containing the string representation of this
BigDecimal . |
Constructs a new
BigDecimal
instance from a string
representation. The result is rounded according to the specified math
context.
Parameters
val
| string containing the string representation of this
BigDecimal . |
mc
| rounding mode and precision for the result of this operation. |
Throws
NumberFormatException
| if scale is out of range |
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)
Constructs a new
BigDecimal
instance from the 64bit double
val
. The constructed big decimal is equivalent to the 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 value to be converted to a BigDecimal instance. |
public
BigDecimal(double val, MathContext mc)
Constructs a new
BigDecimal
instance from the 64bit double
val
. The constructed big decimal is equivalent to the 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 value to be converted to a BigDecimal instance. |
mc
| 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.
|
public
BigDecimal(BigInteger val)
Constructs a new
BigDecimal
instance from the given big integer
val
. The scale of the result is 0.
Parameters
val
| BigInteger value to be converted to a
BigDecimal instance.
|
Constructs a new
BigDecimal
instance from the given big integer
val
. The scale of the result is 0.
Parameters
val
| BigInteger value to be converted to a
BigDecimal instance. |
mc
| 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
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^{-
scale
}.
Parameters
unscaledVal
| BigInteger representing the unscaled value of this
BigDecimal instance. |
scale
| scale of this BigDecimal instance.
|
public
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
unscaledVal
* 10^{-
scale
}. The result is rounded
according to the specified math context.
Parameters
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. |
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
BigDecimal(int val)
Constructs a new
BigDecimal
instance from the given int
val
. The scale of the result is 0.
Parameters
val
| int value to be converted to a BigDecimal instance.
|
public
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 value to be converted to a BigDecimal instance. |
mc
| 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
BigDecimal(long val)
Constructs a new
BigDecimal
instance from the given long
val
. The scale of the result is 0.
Parameters
val
| long value to be converted to a BigDecimal instance.
|
public
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 value to be converted to a BigDecimal instance. |
mc
| 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
Returns a new
BigDecimal
whose value is the absolute value of
this
. The scale of the result is the same as the scale of this.
Returns a new
BigDecimal
whose value is the absolute value of
this
. The result is rounded according to the passed context
mc
.
Parameters
mc
| rounding mode and precision for the result of this operation. |
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
| value to be added to this . |
Returns a new
BigDecimal
whose value is
this + augend
.
The result is rounded according to the passed context
mc
.
Parameters
augend
| value to be added to this . |
mc
| rounding mode and precision for the result of this operation. |
public
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
- this
BigDecimal
as a byte value.
public
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
| value to be compared with this . |
Returns
- 1 if this > val, -1 if this < val, 0 if this == val.
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
| value by which this is divided. |
scale
| the scale of the result returned. |
roundingMode
| rounding mode to be used to round the result. |
Returns
this / divisor
rounded according to the given rounding
mode.
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
| value by which this is divided. |
roundingMode
| rounding mode to be used to round the result. |
Returns
this / divisor
rounded according to the given rounding
mode.
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
| value by which this is divided. |
mc
| rounding mode and precision for the result of this operation. |
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
| value by which this is divided. |
public
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
| value by which this is divided. |
roundingMode
| rounding mode to be used to round the result. |
Returns
this / divisor
rounded according to the given rounding
mode.
public
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
| value by which this is divided. |
scale
| the scale of the result returned. |
roundingMode
| rounding mode to be used to round the result. |
Returns
this / divisor
rounded according to the given rounding
mode.
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
| value by which this is divided. |
mc
| math context which determines the maximal precision of the
result. |
Returns
[this.divideToIntegralValue(divisor), this.remainder(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
| value by which this is divided. |
Returns
[this.divideToIntegralValue(divisor), this.remainder(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. 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
| value by which this is divided. |
mc
| math context which determines the maximal precision of the
result. |
Returns
- integral part of
this / 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
| value by which this is divided. |
Returns
- integral part of
this / divisor
.
public
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
- this
BigDecimal
as a double value.
public
boolean
equals(Object x)
Returns
true
if
x
is a BigDecimal instance and if this
instance is equal to this
BigDecimal
. 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 to be compared with this . |
Returns
- true if x is a BigDecimal and this == x.
public
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.folatValue()) returns false for this case.
Similarly, if the instance
new BigDecimal(16777217)
is converted
to a float, the result is 1.6777216E7.
Returns
- this
BigDecimal
as a float value.
public
int
hashCode()
Returns a hash code for this
BigDecimal
.
public
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^32 is returned.
Returns
- this
BigDecimal
as a int value.
public
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
- this
BigDecimal
as a int value.
public
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^64 is returned.
Returns
- this
BigDecimal
as a long value.
public
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
- this
BigDecimal
as a long value.
Returns the maximum of this
BigDecimal
and
val
.
Parameters
val
| value to be used to compute the maximum with this. |
Returns the minimum of this
BigDecimal
and
val
.
Parameters
val
| value to be used to compute the minimum with this. |
public
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
| number of placed the decimal point has to be moved. |
public
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
| number of placed the decimal point has to be moved. |
Returns a new
BigDecimal
whose value is
this * multiplicand
. The result is rounded according to the
passed context
mc
.
Parameters
multiplicand
| value to be multiplied with this . |
mc
| rounding mode and precision for the result of this operation. |
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
| value to be multiplied with this . |
Returns a new
BigDecimal
whose value is the
-this
. The
result is rounded according to the passed context
mc
.
Parameters
mc
| rounding mode and precision for the result of this operation. |
Returns a new
BigDecimal
whose value is the
-this
. The
scale of the result is the same as the scale of this.
Returns a new
BigDecimal
whose value is
+this
. The scale
of the result is the same as the scale of this.
Returns a new
BigDecimal
whose value is
+this
. The
result is rounded according to the passed context
mc
.
Parameters
mc
| rounding mode and precision for the result of this operation. |
Returns a new
BigDecimal
whose value is
this ^ n
. The
result is rounded according to the passed context
mc
. TODO add
algorithm description
Parameters
n
| exponent to which this is raised. |
mc
| rounding mode and precision for the result of this operation. |
Returns a new
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.
Parameters
n
| exponent to which this is raised. |
public
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 tue unscaled value. The precision of 0 is 1
(independent of the scale).
Returns
- the precision of this
BigDecimal
.
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
| value by which this is divided. |
mc
| rounding mode and precision to be used. |
Returns a new
BigDecimal
whose value is
this % divisor
.
The remainder is defined as
this - this.divideToIntegralValue(divisor) * divisor
.
Parameters
divisor
| value by which this is divided. |
Returns a new
BigDecimal
whose value is
this
, rounded
according to the passed context
mc
.
If mc.precision = 0, then no rounding.
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
| rounding mode and precision for the result of this operation. |
Returns
- 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.
|
public
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^{-scale}. If the scale is negative, then this
BigDecimal
represents a big integer.
Returns
- the scale of this
BigDecimal
.
public
BigDecimal
scaleByPowerOfTen(int n)
Returns a new
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 movePointLeft, except that the
precision is not changed.
Parameters
n
| number of placed the decimal point has to be moved. |
public
BigDecimal
setScale(int newScale, RoundingMode roundingMode)
Returns a new
BigDecimal
instance with the specified scale.
If new 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
| scale of the result returned. |
roundingMode
| rounding mode to be used to round the result. |
Returns
- a new
BigDecimal
instance with the specified scale.
public
BigDecimal
setScale(int newScale)
Returns a new
BigDecimal
instance with the specified scale. If
new 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
| scale of the result returned. |
Returns
- a new
BigDecimal
instance with the specified scale.
public
BigDecimal
setScale(int newScale, int roundingMode)
Returns a new
BigDecimal
instance with the specified scale.
If new 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
| scale of the result returned. |
roundingMode
| rounding mode to be used to round the result. |
Returns
- a new
BigDecimal
instance with the specified scale.
public
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
- this
BigDecimal
as a short value.
public
int
signum()
Returns the sign of this
BigDecimal
.
Returns
- -1 if
this < 0
, 0 if this == 0
, 1 if
this > 0
.
public
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
- a new
BigDecimal
instance equivalent to this where the
trailing zeros of the unscaled value have been removed.
Returns a new
BigDecimal
whose value is
this - subtrahend
.
The result is rounded according to the passed context
mc
.
Parameters
subtrahend
| value to be subtracted from this . |
mc
| rounding mode and precision for the result of this operation. |
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
| value to be subtracted from this . |
public
BigInteger
toBigInteger()
Returns this
BigDecimal
as a big integer instance. A fractional
part is discarded.
Returns
- this
BigDecimal
as a big integer instance.
public
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
- this
BigDecimal
as a big integer value.
public
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
- a string representation of
this
in engineering notation
if necessary.
public
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
- a string representation of
this
without exponent part.
public
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
- a string representation of
this
in scientific notation if
necessary.
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 floating-point
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
1E-55
.
Returns
- unit in the last place (ULP) of this
BigDecimal
instance.
public
BigInteger
unscaledValue()
Returns the unscaled value (mantissa) of this
BigDecimal
instance
as a
BigInteger
. The unscaled value can be computed as this *
10^{scale}.
Returns
- unscaled value (this * 10^(scale)).
public
static
BigDecimal
valueOf(double val)
Returns a new
BigDecimal
instance whose value is equal to
unscaledVal
.
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 value to be converted to a BigDecimal . |
Returns
BigDecimal
instance with the value val
.
public
static
BigDecimal
valueOf(long unscaledVal, int scale)
Returns a new
BigDecimal
instance whose value is equal to
unscaledVal
* 10^{-
scale
}. The scale of the result is
scale
, and its unscaled value is
unscaledVal
.
Parameters
unscaledVal
| unscaled value to be used to construct the new
BigDecimal . |
scale
| scale to be used to construct the new BigDecimal . |
Returns
BigDecimal
instance with the value unscaledVal
*10^{-unscaledVal
}.
public
static
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
| value to be converted to a BigDecimal . |
Returns
BigDecimal
instance with the value unscaledVal
.