java.lang.Object | ||
↳ | java.lang.Number | |
↳ | java.math.BigDecimal |
This class represents immutable integer numbers of arbitrary length. Large numbers are typically used in security applications and therefore BigIntegers offer dedicated functionality like the generation of large prime numbers or the computation of modular inverse.
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.
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
BigDecimal | ONE | The constant one as a BigDecimal . | |||||||||
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 ArithmeticException for the case that rounding is necessary, i.e. | |||||||||
int | ROUND_UP | Rounding mode where positive values are rounded towards positive infinity and negative values towards negative infinity. | |||||||||
BigDecimal | TEN | The constant ten as a BigDecimal . | |||||||||
BigDecimal | ZERO | The constant zero as a BigDecimal . |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Constructs a new
BigDecimal instance from a string representation
given as a character array. | |||||||||||
Constructs a new
BigDecimal instance from a string representation
given as a character array. | |||||||||||
Constructs a new
BigDecimal instance from a string representation
given as a character array. | |||||||||||
Constructs a new
BigDecimal instance from a string representation
given as a character array. | |||||||||||
Constructs a new
BigDecimal instance from a string
representation. | |||||||||||
Constructs a new
BigDecimal instance from a string
representation. | |||||||||||
Constructs a new
BigDecimal instance from the 64bit double
val . | |||||||||||
Constructs a new
BigDecimal instance from the 64bit double
val . | |||||||||||
Constructs a new
BigDecimal instance from the given big integer
val . | |||||||||||
Constructs a new
BigDecimal instance from the given big integer
val . | |||||||||||
Constructs a new
BigDecimal instance from a given unscaled value
unscaledVal and a given scale. | |||||||||||
Constructs a new
BigDecimal instance from a given unscaled value
unscaledVal and a given scale. | |||||||||||
Constructs a new
BigDecimal instance from the given int
val . | |||||||||||
Constructs a new
BigDecimal instance from the given int val . | |||||||||||
Constructs a new
BigDecimal instance from the given long val . | |||||||||||
Constructs a new
BigDecimal instance from the given long val . |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Returns a new
BigDecimal whose value is the absolute value of
this . | |||||||||||
Returns a new
BigDecimal whose value is the absolute value of
this . | |||||||||||
Returns a new
BigDecimal whose value is this + augend . | |||||||||||
Returns a new
BigDecimal whose value is this + augend . | |||||||||||
Returns this
BigDecimal as a byte value if it has no fractional
part and if its value fits to the byte range ([-128..127]). | |||||||||||
Compares this
BigDecimal with val . | |||||||||||
Returns a new
BigDecimal whose value is this / divisor . | |||||||||||
Returns a new
BigDecimal whose value is this / divisor . | |||||||||||
Returns a new
BigDecimal whose value is this / divisor . | |||||||||||
Returns a new
BigDecimal whose value is this / divisor . | |||||||||||
Returns a new
BigDecimal whose value is this / divisor . | |||||||||||
Returns a new
BigDecimal whose value is this / divisor . | |||||||||||
Returns a
BigDecimal array which contains the integral part of
this / divisor at index 0 and the remainder this %
divisor at index 1. | |||||||||||
Returns a
BigDecimal array which contains the integral part of
this / divisor at index 0 and the remainder this %
divisor at index 1. | |||||||||||
Returns a new
BigDecimal whose value is the integral part of
this / divisor . | |||||||||||
Returns a new
BigDecimal whose value is the integral part of
this / divisor . | |||||||||||
Returns this
BigDecimal as a double value. | |||||||||||
Returns
true if x is a BigDecimal instance and if
this instance is equal to this big decimal. | |||||||||||
Returns this
BigDecimal as a float value. | |||||||||||
Returns a hash code for this
BigDecimal . | |||||||||||
Returns this
BigDecimal as an int value. | |||||||||||
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]). | |||||||||||
Returns this
BigDecimal as an long value. | |||||||||||
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]). | |||||||||||
Returns the maximum of this
BigDecimal and val . | |||||||||||
Returns the minimum of this
BigDecimal and val . | |||||||||||
Returns a new
BigDecimal instance where the decimal point has
been moved n places to the left. | |||||||||||
Returns a new
BigDecimal instance where the decimal point has
been moved n places to the right. | |||||||||||
Returns a new
BigDecimal whose value is this *
multiplicand . | |||||||||||
Returns a new
BigDecimal whose value is this *
multiplicand . | |||||||||||
Returns a new
BigDecimal whose value is the -this . | |||||||||||
Returns a new
BigDecimal whose value is the -this . | |||||||||||
Returns a new
BigDecimal whose value is +this . | |||||||||||
Returns a new
BigDecimal whose value is +this . | |||||||||||
Returns a new
BigDecimal whose value is this ^ n . | |||||||||||
Returns a new
BigDecimal whose value is this ^ n . | |||||||||||
Returns the precision of this
BigDecimal . | |||||||||||
Returns a new
BigDecimal whose value is this % divisor . | |||||||||||
Returns a new
BigDecimal whose value is this % divisor . | |||||||||||
Returns a new
BigDecimal whose value is this , rounded
according to the passed context mc . | |||||||||||
Returns the scale of this
BigDecimal . | |||||||||||
Returns a new
BigDecimal whose value is this 10^n . | |||||||||||
Returns a new
BigDecimal instance with the specified scale. | |||||||||||
Returns a new
BigDecimal instance with the specified scale. | |||||||||||
Returns a new
BigDecimal instance with the specified scale. | |||||||||||
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]). | |||||||||||
Returns the sign of this
BigDecimal . | |||||||||||
Returns a new
BigDecimal instance with the same value as this but with a unscaled value where the trailing zeros have been
removed. | |||||||||||
Returns a new
BigDecimal whose value is this - subtrahend . | |||||||||||
Returns a new
BigDecimal whose value is this - subtrahend . | |||||||||||
Returns this
BigDecimal as a big integer instance. | |||||||||||
Returns this
BigDecimal as a big integer instance if it has no
fractional part. | |||||||||||
Returns a string representation of this
BigDecimal . | |||||||||||
Returns a string representation of this
BigDecimal . | |||||||||||
Returns a canonical string representation of this
BigDecimal . | |||||||||||
Returns the unit in the last place (ULP) of this
BigDecimal
instance. | |||||||||||
Returns the unscaled value (mantissa) of this
BigDecimal instance
as a BigInteger . | |||||||||||
Returns a new
BigDecimal instance whose value is equal to unscaledVal . | |||||||||||
Returns a new
BigDecimal instance whose value is equal to unscaledVal 10^(-scale ). | |||||||||||
Returns a new
BigDecimal instance whose value is equal to val . |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
![]() | |||||||||||
![]() | |||||||||||
![]() |
Rounding mode to round towards positive infinity. For positive values
this rounding mode behaves as ROUND_UP
, for negative values as
ROUND_DOWN
.
Rounding mode where the values are rounded towards zero.
Rounding mode to round towards negative infinity. For positive values
this rounding mode behaves as ROUND_DOWN
, for negative values as
ROUND_UP
.
Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding down.
Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding to the even neighbor.
Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding up.
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.
Rounding mode where positive values are rounded towards positive infinity and negative values towards negative infinity.
Constructs a new 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. |
NullPointerException | if in == null . |
---|---|
NumberFormatException | if offset < 0 or len <_ _0="_0" code="code"> or |
NumberFormatException
| if in does not contain a valid string representation of a big
decimal.
|
public
BigDecimal
(char[] in, int offset, int len, MathContext mc)
Since: API Level 1
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 |
---|---|
offset
| first index to be copied. |
len
| number of characters to be used. |
mc
| rounding mode and precision for the result of this operation. |
Throws
NullPointerException
| if |
---|---|
NumberFormatException
| if |
|
|
|
|
public
BigDecimal
(char[] in)
Since: API Level 1
Constructs a new
BigDecimal
instance from a string representation
given as a character array.
Parameters
|
|
---|
Throws
|
|
---|---|
|
|
public
BigDecimal
(char[] in, MathContext mc)
Since: API Level 1
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
|
|
---|---|
|
|
Throws
|
|
---|---|
|
|
|
|
public
BigDecimal
(String val)
Since: API Level 1
Constructs a new
BigDecimal
instance from a string
representation.
Parameters
|
|
---|
Throws
|
|
---|
public
BigDecimal
(String val, MathContext mc)
Since: API Level 1
Constructs a new
BigDecimal
instance from a string
representation. The result is rounded according to the specified math
context.
Parameters
|
|
---|---|
|
|
Throws
|
|
---|---|
|
|
public
BigDecimal
(double val)
Since: API Level 1
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
|
|
---|
public
BigDecimal
(double val, MathContext mc)
Since: API Level 1
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
|
|
---|---|
|
|
Throws
|
|
---|---|
|
|
public
BigDecimal
(BigInteger val)
Since: API Level 1
Constructs a new
BigDecimal
instance from the given big integer
val
. The scale of the result is 0
.
Parameters
|
|
---|
public
BigDecimal
(BigInteger val, MathContext mc)
Since: API Level 1
Constructs a new
BigDecimal
instance from the given big integer
val
. The scale of the result is 0
.
Parameters
|
|
---|---|
|
|
Throws
|
|
---|
public
BigDecimal
(BigInteger unscaledVal, int scale)
Since: API Level 1
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
|
|
---|---|
|
|
public
BigDecimal
(BigInteger unscaledVal, int scale, MathContext mc)
Since: API Level 1
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
|
|
---|---|
|
|
|
|
Throws
|
|
---|---|
|
|
public
BigDecimal
(int val)
Since: API Level 1
Constructs a new
BigDecimal
instance from the given int
val
. The scale of the result is 0.
Parameters
|
|
---|
public
BigDecimal
(int val, MathContext mc)
Since: API Level 1
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
|
|
---|---|
|
|
Throws
|
|
---|
public
BigDecimal
(long val)
Since: API Level 1
Constructs a new
BigDecimal
instance from the given long val
. The scale of the result is 0
.
Parameters
|
|
---|
public
BigDecimal
(long val, MathContext mc)
Since: API Level 1
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
|
|
---|---|
|
|
Throws
|
|
---|
Public Methods
public
BigDecimal
abs
(MathContext mc)
Since: API Level 1
Returns a new
BigDecimal
whose value is the absolute value of
this
. The result is rounded according to the passed context
mc
.
Parameters
|
|
---|
Returns
abs(this)
public
BigDecimal
abs
()
Since: API Level 1
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
abs(this)
public
BigDecimal
add
(BigDecimal augend)
Since: API Level 1
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
|
|
---|
Returns
this + augend
.
public
BigDecimal
add
(BigDecimal augend, MathContext mc)
Since: API Level 1
Returns a new
BigDecimal
whose value is this + augend
.
The result is rounded according to the passed context mc
.
Parameters
|
|
---|---|
|
|
Returns
this + augend
.
public
byte
byteValueExact
()
Since: API Level 1
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)
Since: API Level 1
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
|
|
---|
Returns
1
if this > val
, -1
if this < val
,
0
if this == val
.
public
BigDecimal
divide
(BigDecimal divisor)
Since: API Level 1
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
|
|
---|
Returns
this / divisor
.
Throws
|
|
---|---|
|
|
|
|
public
BigDecimal
divide
(BigDecimal divisor, MathContext mc)
Since: API Level 1
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
|
|
---|---|
|
|
Returns
this / divisor
.
Throws
|
|
---|---|
|
|
|
|
public
BigDecimal
divide
(BigDecimal divisor, int scale, RoundingMode roundingMode)
Since: API Level 1
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
|
|
---|---|
|
|
|
|
Returns
this / divisor
rounded according to the given rounding
mode.
Throws
|
|
---|---|
|
|
|
|
public
BigDecimal
divide
(BigDecimal divisor, int scale, int roundingMode)
Since: API Level 1
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
|
|
---|---|
|
|
|
|
Returns
this / divisor
rounded according to the given rounding
mode.
Throws
|
|
---|---|
|
|
|
|
|
|
public
BigDecimal
divide
(BigDecimal divisor, RoundingMode roundingMode)
Since: API Level 1
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
|
|
---|---|
|
|
Returns
this / divisor
rounded according to the given rounding
mode.
Throws
|
|
---|---|
|
|
|
|
public
BigDecimal
divide
(BigDecimal divisor, int roundingMode)
Since: API Level 1
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
|
|
---|---|
|
|
Returns
this / divisor
rounded according to the given rounding
mode.
Throws
|
|
---|---|
|
|
|
|
|
|
public
BigDecimal[]
divideAndRemainder
(BigDecimal divisor, MathContext mc)
Since: API Level 1
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
|
|
---|---|
|
|
Returns
[this.divideToIntegralValue(divisor),
this.remainder(divisor)]
.
public
BigDecimal[]
divideAndRemainder
(BigDecimal divisor)
Since: API Level 1
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
|
|
---|
Returns
[this.divideToIntegralValue(divisor),
this.remainder(divisor)]
.
public
BigDecimal
divideToIntegralValue
(BigDecimal divisor, MathContext mc)
Since: API Level 1
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
|
|
---|---|
|
|
Returns
integral part of this / divisor
.
Throws
|
|
---|---|
|
|
|
|
public
BigDecimal
divideToIntegralValue
(BigDecimal divisor)
Since: API Level 1
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
|
|
---|
Returns
integral part of this / divisor
.
public
double
doubleValue
()
Since: API Level 1
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)
Since: API Level 1
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
|
|
---|
Returns
true if x
is a BigDecimal
and this == x
.
public
float
floatValue
()
Since: API Level 1
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.6777216E
7.
Returns
this BigDecimal
as a float value.
public
int
hashCode
()
Since: API Level 1
Returns a hash code for this
BigDecimal
.
Returns
hash code for this
.
public
int
intValue
()
Since: API Level 1
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
()
Since: API Level 1
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
()
Since: API Level 1
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
()
Since: API Level 1
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.
public
BigDecimal
max
(BigDecimal val)
Since: API Level 1
Returns the maximum of this
BigDecimal
and val
.
Parameters
|
|
---|
Returns
max(this, val
.
public
BigDecimal
min
(BigDecimal val)
Since: API Level 1
Returns the minimum of this
BigDecimal
and val
.
Parameters
|
|
---|
Returns
min(this, val
.
public
BigDecimal
movePointLeft
(int n)
Since: API Level 1
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
|
|
---|
Returns
this * 10^(-n
).
public
BigDecimal
movePointRight
(int n)
Since: API Level 1
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
|
|
---|
Returns
this * 10^n
.
public
BigDecimal
multiply
(BigDecimal multiplicand)
Since: API Level 1
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
|
|
---|
Returns
this * multiplicand
.
public
BigDecimal
multiply
(BigDecimal multiplicand, MathContext mc)
Since: API Level 1
Returns a new
BigDecimal
whose value is this *
multiplicand
. The result is rounded according to the passed context
mc
.
Parameters
|
|
---|---|
|
|
Returns
this * multiplicand
.
public
BigDecimal
negate
(MathContext mc)
Since: API Level 1
Returns a new
BigDecimal
whose value is the -this
. The
result is rounded according to the passed context mc
.
Parameters
|
|
---|
Returns
-this
public
BigDecimal
negate
()
Since: API Level 1
Returns a new
BigDecimal
whose value is the -this
. The
scale of the result is the same as the scale of this.
Returns
-this
public
BigDecimal
plus
(MathContext mc)
Since: API Level 1
Returns a new
BigDecimal
whose value is +this
. The result
is rounded according to the passed context mc
.
Parameters
|
|
---|
Returns
this
, rounded
public
BigDecimal
plus
()
Since: API Level 1
Returns a new
BigDecimal
whose value is +this
. The scale
of the result is the same as the scale of this.
Returns
this
public
BigDecimal
pow
(int n, MathContext mc)
Since: API Level 1
Returns a new
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.274-1996 algorithm.
Parameters
|
|
---|---|
|
|
Returns
this ^ n
.
public
BigDecimal
pow
(int n)
Since: API Level 1
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
.
Implementation Note: The implementation is based on the ANSI standard
X3.274-1996 algorithm.
Parameters
|
|
---|
Returns
this ^ n
.
public
int
precision
()
Since: API Level 1
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
the precision of this BigDecimal
.
public
BigDecimal
remainder
(BigDecimal divisor)
Since: API Level 1
Returns a new
BigDecimal
whose value is this % divisor
.
The remainder is defined as
this -
this.divideToIntegralValue(divisor) * divisor
.
Parameters
|
|
---|
Returns
this % divisor
.
public
BigDecimal
remainder
(BigDecimal divisor, MathContext mc)
Since: API Level 1
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
|
|
---|---|
|
|
Returns
this % divisor
.
Throws
|
|
---|---|
|
|
|
|
public
BigDecimal
round
(MathContext mc)
Since: API Level 1
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
|
|
---|
Returns
this
rounded according to the passed context.
Throws
|
|
---|
public
int
scale
()
Since: API Level 1
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)
Since: API Level 1
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
movePointRight(int)
, except that
the precision is not changed.
Parameters
|
|
---|
Returns
this * 10^n
public
BigDecimal
setScale
(int newScale)
Since: API Level 1
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
|
|
---|
Returns
a new BigDecimal
instance with the specified scale.
public
BigDecimal
setScale
(int newScale, int roundingMode)
Since: API Level 1
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
|
|
---|---|
|
|
Returns
a new BigDecimal
instance with the specified scale.
Throws
|
|
---|---|
|
|
public
BigDecimal
setScale
(int newScale, RoundingMode roundingMode)
Since: API Level 1
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
|
|
---|---|
|
|
Returns
a new BigDecimal
instance with the specified scale.
Throws
|
|
---|---|
|
|
public
short
shortValueExact
()
Since: API Level 1
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
()
Since: API Level 1
Returns the sign of this
BigDecimal
.
Returns
-1
if this < 0
,
0
if this == 0
,
1
if this > 0
.
public
BigDecimal
stripTrailingZeros
()
Since: API Level 1
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.
public
BigDecimal
subtract
(BigDecimal subtrahend, MathContext mc)
Since: API Level 1
Returns a new
BigDecimal
whose value is this - subtrahend
.
The result is rounded according to the passed context mc
.
Parameters
|
|
---|---|
|
|
Returns
this - subtrahend
.
public
BigDecimal
subtract
(BigDecimal subtrahend)
Since: API Level 1
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
|
|
---|
Returns
this - subtrahend
.
public
BigInteger
toBigInteger
()
Since: API Level 1
Returns this
BigDecimal
as a big integer instance. A fractional
part is discarded.
Returns
this BigDecimal
as a big integer instance.
public
BigInteger
toBigIntegerExact
()
Since: API Level 1
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
()
Since: API Level 1
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
()
Since: API Level 1
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
()
Since: API Level 1
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.
public
BigDecimal
ulp
()
Since: API Level 1
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
()
Since: API Level 1
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
(long unscaledVal)
Since: API Level 1
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
|
|
---|
Returns
BigDecimal
instance with the value unscaledVal
.
public
static
BigDecimal
valueOf
(long unscaledVal, int scale)
Since: API Level 1
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
|
|
---|---|
|
|
Returns
BigDecimal
instance with the value unscaledVal
*
10^(-unscaledVal
).
public
static
BigDecimal
valueOf
(double val)
Since: API Level 1
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
|
|
---|
Returns
BigDecimal
instance with the value val
.