Class TBigDecimal
- All Implemented Interfaces:
Serializable
,Comparable<TBigDecimal>
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
).- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final TBigDecimal
The constant one as aBigDecimal
.static final int
Rounding mode to round towards positive infinity.static final int
Rounding mode where the values are rounded towards zero.static final int
Rounding mode to round towards negative infinity.static final int
Rounding mode where values are rounded towards the nearest neighbor.static final int
Rounding mode where values are rounded towards the nearest neighbor.static final int
Rounding mode where values are rounded towards the nearest neighbor.static final int
Rounding mode where the rounding operations throws anArithmeticException
for the case that rounding is necessary, i.e.static final int
Rounding mode where positive values are rounded towards positive infinity and negative values towards negative infinity.static final TBigDecimal
The constant ten as aBigDecimal
.static final TBigDecimal
The constant zero as aBigDecimal
. -
Constructor Summary
ConstructorsConstructorDescriptionTBigDecimal
(char[] in) Constructs a newBigDecimal
instance from a string representation given as a character array.TBigDecimal
(char[] in, int offset, int len) Constructs a newBigDecimal
instance from a string representation given as a character array.TBigDecimal
(char[] in, int offset, int len, TMathContext mc) Constructs a newBigDecimal
instance from a string representation given as a character array.TBigDecimal
(char[] in, TMathContext mc) Constructs a newBigDecimal
instance from a string representation given as a character array.TBigDecimal
(double val) Constructs a newBigDecimal
instance from the 64bit doubleval
.TBigDecimal
(double val, TMathContext mc) Constructs a newBigDecimal
instance from the 64bit doubleval
.TBigDecimal
(int val) Constructs a newBigDecimal
instance from the given intval
.TBigDecimal
(int val, TMathContext mc) Constructs a newBigDecimal
instance from the given intval
.TBigDecimal
(long val) Constructs a newBigDecimal
instance from the given longval
.TBigDecimal
(long val, TMathContext mc) Constructs a newBigDecimal
instance from the given longval
.TBigDecimal
(String val) Constructs a newBigDecimal
instance from a string representation.TBigDecimal
(String val, TMathContext mc) Constructs a newBigDecimal
instance from a string representation.TBigDecimal
(TBigInteger val) Constructs a newBigDecimal
instance from the given big integerval
.TBigDecimal
(TBigInteger unscaledVal, int scale) Constructs a newBigDecimal
instance from a given unscaled valueunscaledVal
and a given scale.TBigDecimal
(TBigInteger unscaledVal, int scale, TMathContext mc) Constructs a newBigDecimal
instance from a given unscaled valueunscaledVal
and a given scale.TBigDecimal
(TBigInteger val, TMathContext mc) Constructs a newBigDecimal
instance from the given big integerval
. -
Method Summary
Modifier and TypeMethodDescriptionabs()
Returns a newBigDecimal
whose value is the absolute value ofthis
.abs
(TMathContext mc) Returns a newBigDecimal
whose value is the absolute value ofthis
.add
(TBigDecimal augend) Returns a newBigDecimal
whose value isthis + augend
.add
(TBigDecimal augend, TMathContext mc) Returns a newBigDecimal
whose value isthis + augend
.byte
Returns thisBigDecimal
as a byte value if it has no fractional part and if its value fits to the byte range ([-128..127]).int
compareTo
(TBigDecimal val) Compares thisBigDecimal
withval
.divide
(TBigDecimal divisor) Returns a newBigDecimal
whose value isthis / divisor
.divide
(TBigDecimal divisor, int roundingMode) Returns a newBigDecimal
whose value isthis / divisor
.divide
(TBigDecimal divisor, int scale, int roundingMode) Returns a newBigDecimal
whose value isthis / divisor
.divide
(TBigDecimal divisor, int scale, TRoundingMode roundingMode) Returns a newBigDecimal
whose value isthis / divisor
.divide
(TBigDecimal divisor, TMathContext mc) Returns a newBigDecimal
whose value isthis / divisor
.divide
(TBigDecimal divisor, TRoundingMode roundingMode) Returns a newBigDecimal
whose value isthis / divisor
.divideAndRemainder
(TBigDecimal divisor) Returns aBigDecimal
array which contains the integral part ofthis / divisor
at index 0 and the remainderthis % divisor
at index 1.divideAndRemainder
(TBigDecimal divisor, TMathContext mc) Returns aBigDecimal
array which contains the integral part ofthis / divisor
at index 0 and the remainderthis % divisor
at index 1.divideToIntegralValue
(TBigDecimal divisor) Returns a newBigDecimal
whose value is the integral part ofthis / divisor
.divideToIntegralValue
(TBigDecimal divisor, TMathContext mc) Returns a newBigDecimal
whose value is the integral part ofthis / divisor
.double
Returns thisBigDecimal
as a double value.boolean
Returnstrue
ifx
is aBigDecimal
instance and if this instance is equal to this big decimal.float
Returns thisBigDecimal
as a float value.int
hashCode()
Returns a hash code for thisBigDecimal
.int
intValue()
Returns thisBigDecimal
as an int value.int
Returns thisBigDecimal
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
Returns thisBigDecimal
as an long value.long
Returns thisBigDecimal
as a long value if it has no fractional part and if its value fits to the int range ([-2^{63}..2^{63}-1]).max
(TBigDecimal val) Returns the maximum of thisBigDecimal
andval
.min
(TBigDecimal val) Returns the minimum of thisBigDecimal
andval
.movePointLeft
(int n) Returns a newBigDecimal
instance where the decimal point has been movedn
places to the left.movePointRight
(int n) Returns a newBigDecimal
instance where the decimal point has been movedn
places to the right.multiply
(TBigDecimal multiplicand) Returns a newBigDecimal
whose value isthis * multiplicand
.multiply
(TBigDecimal multiplicand, TMathContext mc) Returns a newBigDecimal
whose value isthis * multiplicand
.negate()
Returns a newBigDecimal
whose value is the-this
.negate
(TMathContext mc) Returns a newBigDecimal
whose value is the-this
.plus()
Returns a newBigDecimal
whose value is+this
.plus
(TMathContext mc) Returns a newBigDecimal
whose value is+this
.pow
(int n) Returns a newBigDecimal
whose value isthis ^ n
.pow
(int n, TMathContext mc) Returns a newBigDecimal
whose value isthis ^ n
.int
Returns the precision of thisBigDecimal
.remainder
(TBigDecimal divisor) Returns a newBigDecimal
whose value isthis % divisor
.remainder
(TBigDecimal divisor, TMathContext mc) Returns a newBigDecimal
whose value isthis % divisor
.round
(TMathContext mc) Returns a newBigDecimal
whose value isthis
, rounded according to the passed contextmc
.int
scale()
Returns the scale of thisBigDecimal
.scaleByPowerOfTen
(int n) Returns a newBigDecimal
whose value isthis
10^n
.setScale
(int newScale) Returns a newBigDecimal
instance with the specified scale.setScale
(int newScale, int roundingMode) Returns a newBigDecimal
instance with the specified scale.setScale
(int newScale, TRoundingMode roundingMode) Returns a newBigDecimal
instance with the specified scale.short
Returns thisBigDecimal
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 thisBigDecimal
.Returns a newBigDecimal
instance with the same value asthis
but with a unscaled value where the trailing zeros have been removed.subtract
(TBigDecimal subtrahend) Returns a newBigDecimal
whose value isthis - subtrahend
.subtract
(TBigDecimal subtrahend, TMathContext mc) Returns a newBigDecimal
whose value isthis - subtrahend
.Returns thisBigDecimal
as a big integer instance.Returns thisBigDecimal
as a big integer instance if it has no fractional part.Returns a string representation of thisBigDecimal
.Returns a string representation of thisBigDecimal
.toString()
Returns a canonical string representation of thisBigDecimal
.ulp()
Returns the unit in the last place (ULP) of thisBigDecimal
instance.Returns the unscaled value (mantissa) of thisBigDecimal
instance as aBigInteger
.static TBigDecimal
valueOf
(double val) Returns a newBigDecimal
instance whose value is equal toval
.static TBigDecimal
valueOf
(long unscaledVal) Returns a newBigDecimal
instance whose value is equal tounscaledVal
.static TBigDecimal
valueOf
(long unscaledVal, int scale) Returns a newBigDecimal
instance whose value is equal tounscaledVal
10^(-scale
).Methods inherited from class java.lang.Number
byteValue, shortValue
-
Field Details
-
ZERO
The constant zero as aBigDecimal
. -
ONE
The constant one as aBigDecimal
. -
TEN
The constant ten as aBigDecimal
. -
ROUND_UP
public static final int ROUND_UPRounding mode where positive values are rounded towards positive infinity and negative values towards negative infinity.- See Also:
-
ROUND_DOWN
public static final int ROUND_DOWNRounding mode where the values are rounded towards zero.- See Also:
-
ROUND_CEILING
public static final int ROUND_CEILINGRounding mode to round towards positive infinity. For positive values this rounding mode behaves asROUND_UP
, for negative values asROUND_DOWN
.- See Also:
-
ROUND_FLOOR
public static final int ROUND_FLOORRounding mode to round towards negative infinity. For positive values this rounding mode behaves asROUND_DOWN
, for negative values asROUND_UP
.- See Also:
-
ROUND_HALF_UP
public static final int ROUND_HALF_UPRounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding up.- See Also:
-
ROUND_HALF_DOWN
public static final int ROUND_HALF_DOWNRounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding down.- See Also:
-
ROUND_HALF_EVEN
public static final int ROUND_HALF_EVENRounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding to the even neighbor.- See Also:
-
ROUND_UNNECESSARY
public static final int ROUND_UNNECESSARYRounding mode where the rounding operations throws anArithmeticException
for the case that rounding is necessary, i.e. for the case that the value cannot be represented exactly.
-
-
Constructor Details
-
TBigDecimal
public TBigDecimal(char[] in, int offset, int len) Constructs a newBigDecimal
instance from a string representation given as a character array.- Parameters:
in
- array of characters containing the string representation of thisBigDecimal
.offset
- first index to be copied.len
- number of characters to be used.- Throws:
NullPointerException
- ifin == null
.NumberFormatException
- ifoffset < 0
orlen <= 0
oroffset+len-1 < 0
oroffset+len-1 >= in.length
.NumberFormatException
- if in does not contain a valid string representation of a big decimal.
-
TBigDecimal
Constructs a newBigDecimal
instance from a string representation given as a character array.- Parameters:
in
- array of characters containing the string representation of thisBigDecimal
.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
- ifin == null
.NumberFormatException
- ifoffset < 0
orlen <= 0
oroffset+len-1 < 0
oroffset+len-1 >= in.length
.NumberFormatException
- ifin
does not contain a valid string representation of a big decimal.ArithmeticException
- ifmc.precision > 0
andmc.roundingMode == UNNECESSARY
and the new big decimal cannot be represented within the given precision without rounding.
-
TBigDecimal
public TBigDecimal(char[] in) Constructs a newBigDecimal
instance from a string representation given as a character array.- Parameters:
in
- array of characters containing the string representation of thisBigDecimal
.- Throws:
NullPointerException
- ifin == null
.NumberFormatException
- ifin
does not contain a valid string representation of a big decimal.
-
TBigDecimal
Constructs a newBigDecimal
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 thisBigDecimal
.mc
- rounding mode and precision for the result of this operation.- Throws:
NullPointerException
- ifin == null
.NumberFormatException
- ifin
does not contain a valid string representation of a big decimal.ArithmeticException
- ifmc.precision > 0
andmc.roundingMode == UNNECESSARY
and the new big decimal cannot be represented within the given precision without rounding.
-
TBigDecimal
Constructs a newBigDecimal
instance from a string representation.- Parameters:
val
- string containing the string representation of thisBigDecimal
.- Throws:
NumberFormatException
- ifval
does not contain a valid string representation of a big decimal.
-
TBigDecimal
Constructs a newBigDecimal
instance from a string representation. The result is rounded according to the specified math context.- Parameters:
val
- string containing the string representation of thisBigDecimal
.mc
- rounding mode and precision for the result of this operation.- Throws:
NumberFormatException
- ifval
does not contain a valid string representation of a big decimal.ArithmeticException
- ifmc.precision > 0
andmc.roundingMode == UNNECESSARY
and the new big decimal cannot be represented within the given precision without rounding.
-
TBigDecimal
public TBigDecimal(double val) Constructs a newBigDecimal
instance from the 64bit doubleval
. The constructed big decimal is equivalent to the given double. For example,new BigDecimal(0.1)
is equal to0.1000000000000000055511151231257827021181583404541015625
. This happens as0.1
cannot be represented exactly in binary.To generate a big decimal instance which is equivalent to
0.1
use theBigDecimal(String)
constructor.- Parameters:
val
- double value to be converted to aBigDecimal
instance.- Throws:
NumberFormatException
- ifval
is infinity or not a number.
-
TBigDecimal
Constructs a newBigDecimal
instance from the 64bit doubleval
. The constructed big decimal is equivalent to the given double. For example,new BigDecimal(0.1)
is equal to0.1000000000000000055511151231257827021181583404541015625
. This happens as0.1
cannot be represented exactly in binary.To generate a big decimal instance which is equivalent to
0.1
use theBigDecimal(String)
constructor.- Parameters:
val
- double value to be converted to aBigDecimal
instance.mc
- rounding mode and precision for the result of this operation.- Throws:
NumberFormatException
- ifval
is infinity or not a number.ArithmeticException
- ifmc.precision > 0
andmc.roundingMode == UNNECESSARY
and the new big decimal cannot be represented within the given precision without rounding.
-
TBigDecimal
Constructs a newBigDecimal
instance from the given big integerval
. The scale of the result is0
.- Parameters:
val
-BigInteger
value to be converted to aBigDecimal
instance.
-
TBigDecimal
Constructs a newBigDecimal
instance from the given big integerval
. The scale of the result is0
.- Parameters:
val
-BigInteger
value to be converted to aBigDecimal
instance.mc
- rounding mode and precision for the result of this operation.- Throws:
ArithmeticException
- ifmc.precision > 0
andmc.roundingMode == UNNECESSARY
and the new big decimal cannot be represented within the given precision without rounding.
-
TBigDecimal
Constructs a newBigDecimal
instance from a given unscaled valueunscaledVal
and a given scale. The value of this instance isunscaledVal
10^(-scale
).- Parameters:
unscaledVal
-BigInteger
representing the unscaled value of thisBigDecimal
instance.scale
- scale of thisBigDecimal
instance.- Throws:
NullPointerException
- ifunscaledVal == null
.
-
TBigDecimal
Constructs a newBigDecimal
instance from a given unscaled valueunscaledVal
and a given scale. The value of this instance isunscaledVal
10^(-scale
). The result is rounded according to the specified math context.- Parameters:
unscaledVal
-BigInteger
representing the unscaled value of thisBigDecimal
instance.scale
- scale of thisBigDecimal
instance.mc
- rounding mode and precision for the result of this operation.- Throws:
ArithmeticException
- ifmc.precision > 0
andmc.roundingMode == UNNECESSARY
and the new big decimal cannot be represented within the given precision without rounding.NullPointerException
- ifunscaledVal == null
.
-
TBigDecimal
public TBigDecimal(int val) Constructs a newBigDecimal
instance from the given intval
. The scale of the result is 0.- Parameters:
val
- int value to be converted to aBigDecimal
instance.
-
TBigDecimal
Constructs a newBigDecimal
instance from the given intval
. The scale of the result is0
. The result is rounded according to the specified math context.- Parameters:
val
- int value to be converted to aBigDecimal
instance.mc
- rounding mode and precision for the result of this operation.- Throws:
ArithmeticException
- ifmc.precision > 0
andc.roundingMode == UNNECESSARY
and the new big decimal cannot be represented within the given precision without rounding.
-
TBigDecimal
public TBigDecimal(long val) Constructs a newBigDecimal
instance from the given longval
. The scale of the result is0
.- Parameters:
val
- long value to be converted to aBigDecimal
instance.
-
TBigDecimal
Constructs a newBigDecimal
instance from the given longval
. The scale of the result is0
. The result is rounded according to the specified math context.- Parameters:
val
- long value to be converted to aBigDecimal
instance.mc
- rounding mode and precision for the result of this operation.- Throws:
ArithmeticException
- ifmc.precision > 0
andmc.roundingMode == UNNECESSARY
and the new big decimal cannot be represented within the given precision without rounding.
-
-
Method Details
-
valueOf
Returns a newBigDecimal
instance whose value is equal tounscaledVal
10^(-scale
). The scale of the result isscale
, and its unscaled value isunscaledVal
.- Parameters:
unscaledVal
- unscaled value to be used to construct the newBigDecimal
.scale
- scale to be used to construct the newBigDecimal
.- Returns:
BigDecimal
instance with the valueunscaledVal
* 10^(-unscaledVal
).
-
valueOf
Returns a newBigDecimal
instance whose value is equal tounscaledVal
. The scale of the result is0
, and its unscaled value isunscaledVal
.- Parameters:
unscaledVal
- value to be converted to aBigDecimal
.- Returns:
BigDecimal
instance with the valueunscaledVal
.
-
valueOf
Returns a newBigDecimal
instance whose value is equal toval
. The new decimal is constructed as if theBigDecimal(String)
constructor is called with an argument which is equal toDouble.toString(val)
. For example,valueOf("0.1")
is converted to (unscaled=1, scale=1), although the double0.1
cannot be represented exactly as a double value. In contrast to that, a newBigDecimal(0.1)
instance has the value0.1000000000000000055511151231257827021181583404541015625
with an unscaled value1000000000000000055511151231257827021181583404541015625
and the scale55
.- Parameters:
val
- double value to be converted to aBigDecimal
.- Returns:
BigDecimal
instance with the valueval
.- Throws:
NumberFormatException
- ifval
is infinite orval
is not a number
-
add
Returns a newBigDecimal
whose value isthis + augend
. The scale of the result is the maximum of the scales of the two arguments.- Parameters:
augend
- value to be added tothis
.- Returns:
this + augend
.- Throws:
NullPointerException
- ifaugend == null
.
-
add
Returns a newBigDecimal
whose value isthis + augend
. The result is rounded according to the passed contextmc
.- Parameters:
augend
- value to be added tothis
.mc
- rounding mode and precision for the result of this operation.- Returns:
this + augend
.- Throws:
NullPointerException
- ifaugend == null
ormc == null
.
-
subtract
Returns a newBigDecimal
whose value isthis - subtrahend
. The scale of the result is the maximum of the scales of the two arguments.- Parameters:
subtrahend
- value to be subtracted fromthis
.- Returns:
this - subtrahend
.- Throws:
NullPointerException
- ifsubtrahend == null
.
-
subtract
Returns a newBigDecimal
whose value isthis - subtrahend
. The result is rounded according to the passed contextmc
.- Parameters:
subtrahend
- value to be subtracted fromthis
.mc
- rounding mode and precision for the result of this operation.- Returns:
this - subtrahend
.- Throws:
NullPointerException
- ifsubtrahend == null
ormc == null
.
-
multiply
Returns a newBigDecimal
whose value isthis * multiplicand
. The scale of the result is the sum of the scales of the two arguments.- Parameters:
multiplicand
- value to be multiplied withthis
.- Returns:
this * multiplicand
.- Throws:
NullPointerException
- ifmultiplicand == null
.
-
multiply
Returns a newBigDecimal
whose value isthis * multiplicand
. The result is rounded according to the passed contextmc
.- Parameters:
multiplicand
- value to be multiplied withthis
.mc
- rounding mode and precision for the result of this operation.- Returns:
this * multiplicand
.- Throws:
NullPointerException
- ifmultiplicand == null
ormc == null
.
-
divide
Returns a newBigDecimal
whose value isthis / divisor
. As scale of the result the parameterscale
is used. If rounding is required to meet the specified scale, then the specified rounding moderoundingMode
is applied.- Parameters:
divisor
- value by whichthis
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.- Throws:
NullPointerException
- ifdivisor == null
.IllegalArgumentException
- ifroundingMode
is not a valid rounding mode.ArithmeticException
- ifdivisor == 0
.ArithmeticException
- ifroundingMode == ROUND_UNNECESSARY
and rounding is necessary according to the given scale.
-
divide
Returns a newBigDecimal
whose value isthis / divisor
. As scale of the result the parameterscale
is used. If rounding is required to meet the specified scale, then the specified rounding moderoundingMode
is applied.- Parameters:
divisor
- value by whichthis
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.- Throws:
NullPointerException
- ifdivisor == null
orroundingMode == null
.ArithmeticException
- ifdivisor == 0
.ArithmeticException
- ifroundingMode == RoundingMode.UNNECESSAR
Y and rounding is necessary according to the given scale and given precision.
-
divide
Returns a newBigDecimal
whose value isthis / divisor
. The scale of the result is the scale ofthis
. If rounding is required to meet the specified scale, then the specified rounding moderoundingMode
is applied.- Parameters:
divisor
- value by whichthis
is divided.roundingMode
- rounding mode to be used to round the result.- Returns:
this / divisor
rounded according to the given rounding mode.- Throws:
NullPointerException
- ifdivisor == null
.IllegalArgumentException
- ifroundingMode
is not a valid rounding mode.ArithmeticException
- ifdivisor == 0
.ArithmeticException
- ifroundingMode == ROUND_UNNECESSARY
and rounding is necessary according to the scale of this.
-
divide
Returns a newBigDecimal
whose value isthis / divisor
. The scale of the result is the scale ofthis
. If rounding is required to meet the specified scale, then the specified rounding moderoundingMode
is applied.- Parameters:
divisor
- value by whichthis
is divided.roundingMode
- rounding mode to be used to round the result.- Returns:
this / divisor
rounded according to the given rounding mode.- Throws:
NullPointerException
- ifdivisor == null
orroundingMode == null
.ArithmeticException
- ifdivisor == 0
.ArithmeticException
- ifroundingMode == RoundingMode.UNNECESSARY
and rounding is necessary according to the scale of this.
-
divide
Returns a newBigDecimal
whose value isthis / divisor
. The scale of the result is the difference of the scales ofthis
anddivisor
. If the exact result requires more digits, then the scale is adjusted accordingly. For example,1/128 = 0.0078125
which has a scale of7
and precision5
.- Parameters:
divisor
- value by whichthis
is divided.- Returns:
this / divisor
.- Throws:
NullPointerException
- ifdivisor == null
.ArithmeticException
- ifdivisor == 0
.ArithmeticException
- if the result cannot be represented exactly.
-
divide
Returns a newBigDecimal
whose value isthis / divisor
. The result is rounded according to the passed contextmc
. If the passed math context specifies precision0
, then this call is equivalent tothis.divide(divisor)
.- Parameters:
divisor
- value by whichthis
is divided.mc
- rounding mode and precision for the result of this operation.- Returns:
this / divisor
.- Throws:
NullPointerException
- ifdivisor == null
ormc == null
.ArithmeticException
- ifdivisor == 0
.ArithmeticException
- ifmc.getRoundingMode() == UNNECESSARY
and rounding is necessary accordingmc.getPrecision()
.
-
divideToIntegralValue
Returns a newBigDecimal
whose value is the integral part ofthis / divisor
. The quotient is rounded down towards zero to the next integer. For example,0.5/0.2 = 2
.- Parameters:
divisor
- value by whichthis
is divided.- Returns:
- integral part of
this / divisor
. - Throws:
NullPointerException
- ifdivisor == null
.ArithmeticException
- ifdivisor == 0
.
-
divideToIntegralValue
Returns a newBigDecimal
whose value is the integral part ofthis / divisor
. The quotient is rounded down towards zero to the next integer. The rounding mode passed with the parametermc
is not considered. But if the precision ofmc > 0
and the integral part requires more digits, then anArithmeticException
is thrown.- Parameters:
divisor
- value by whichthis
is divided.mc
- math context which determines the maximal precision of the result.- Returns:
- integral part of
this / divisor
. - Throws:
NullPointerException
- ifdivisor == null
ormc == null
.ArithmeticException
- ifdivisor == 0
.ArithmeticException
- ifmc.getPrecision() > 0
and the result requires more digits to be represented.
-
remainder
Returns a newBigDecimal
whose value isthis % divisor
.The remainder is defined as
this - this.divideToIntegralValue(divisor) * divisor
.- Parameters:
divisor
- value by whichthis
is divided.- Returns:
this % divisor
.- Throws:
NullPointerException
- ifdivisor == null
.ArithmeticException
- ifdivisor == 0
.
-
remainder
Returns a newBigDecimal
whose value isthis % 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 whichthis
is divided.mc
- rounding mode and precision to be used.- Returns:
this % divisor
.- Throws:
NullPointerException
- ifdivisor == null
.ArithmeticException
- ifdivisor == 0
.ArithmeticException
- ifmc.getPrecision() > 0
and the result ofthis.divideToIntegralValue(divisor, mc)
requires more digits to be represented.
-
divideAndRemainder
Returns aBigDecimal
array which contains the integral part ofthis / divisor
at index 0 and the remainderthis % divisor
at index 1. The quotient is rounded down towards zero to the next integer.- Parameters:
divisor
- value by whichthis
is divided.- Returns:
[this.divideToIntegralValue(divisor), this.remainder(divisor)]
.- Throws:
NullPointerException
- ifdivisor == null
.ArithmeticException
- ifdivisor == 0
.- See Also:
-
divideAndRemainder
Returns aBigDecimal
array which contains the integral part ofthis / divisor
at index 0 and the remainderthis % divisor
at index 1. The quotient is rounded down towards zero to the next integer. The rounding mode passed with the parametermc
is not considered. But if the precision ofmc > 0
and the integral part requires more digits, then anArithmeticException
is thrown.- Parameters:
divisor
- value by whichthis
is divided.mc
- math context which determines the maximal precision of the result.- Returns:
[this.divideToIntegralValue(divisor), this.remainder(divisor)]
.- Throws:
NullPointerException
- ifdivisor == null
.ArithmeticException
- ifdivisor == 0
.- See Also:
-
pow
Returns a newBigDecimal
whose value isthis ^ n
. The scale of the result isn
times the scales ofthis
.x.pow(0)
returns1
, even ifx == 0
.Implementation Note: The implementation is based on the ANSI standard X3.274-1996 algorithm.
- Parameters:
n
- exponent to whichthis
is raised.- Returns:
this ^ n
.- Throws:
ArithmeticException
- ifn < 0
orn > 999999999
.
-
pow
Returns a newBigDecimal
whose value isthis ^ n
. The result is rounded according to the passed contextmc
.Implementation Note: The implementation is based on the ANSI standard X3.274-1996 algorithm.
- Parameters:
n
- exponent to whichthis
is raised.mc
- rounding mode and precision for the result of this operation.- Returns:
this ^ n
.- Throws:
ArithmeticException
- ifn < 0
orn > 999999999
.
-
abs
Returns a newBigDecimal
whose value is the absolute value ofthis
. The scale of the result is the same as the scale of this.- Returns:
abs(this)
-
abs
Returns a newBigDecimal
whose value is the absolute value ofthis
. The result is rounded according to the passed contextmc
.- Parameters:
mc
- rounding mode and precision for the result of this operation.- Returns:
abs(this)
-
negate
Returns a newBigDecimal
whose value is the-this
. The scale of the result is the same as the scale of this.- Returns:
-this
-
negate
Returns a newBigDecimal
whose value is the-this
. The result is rounded according to the passed contextmc
.- Parameters:
mc
- rounding mode and precision for the result of this operation.- Returns:
-this
-
plus
Returns a newBigDecimal
whose value is+this
. The scale of the result is the same as the scale of this.- Returns:
this
-
plus
Returns a newBigDecimal
whose value is+this
. The result is rounded according to the passed contextmc
.- Parameters:
mc
- rounding mode and precision for the result of this operation.- Returns:
this
, rounded
-
signum
public int signum()Returns the sign of thisBigDecimal
.- Returns:
-1
ifthis < 0
,0
ifthis == 0
,1
ifthis > 0
.
-
scale
public int scale()Returns the scale of thisBigDecimal
. The scale is the number of digits behind the decimal point. The value of thisBigDecimal
is the unsignedValue * 10^(-scale). If the scale is negative, then thisBigDecimal
represents a big integer.- Returns:
- the scale of this
BigDecimal
.
-
precision
public int precision()Returns the precision of thisBigDecimal
. 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 of0
is1
(independent of the scale).- Returns:
- the precision of this
BigDecimal
.
-
unscaledValue
Returns the unscaled value (mantissa) of thisBigDecimal
instance as aBigInteger
. The unscaled value can be computed asthis
10^(scale).- Returns:
- unscaled value (this * 10^(scale)).
-
round
Returns a newBigDecimal
whose value isthis
, rounded according to the passed contextmc
.If
mc.precision = 0
, then no rounding is performed.If
mc.precision > 0
andmc.roundingMode == UNNECESSARY
, then anArithmeticException
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
- ifmc.precision > 0
andmc.roundingMode == UNNECESSARY
and this cannot be represented within the given precision.
-
setScale
Returns a newBigDecimal
instance with the specified scale.If the new scale is greater than the old scale, then additional zeros are added to the unscaled value. In this case no rounding is necessary.
If the new scale is smaller than the old scale, then trailing digits are removed. If these trailing digits are not zero, then the remaining unscaled value has to be rounded. For this rounding operation the specified rounding mode is used.
- Parameters:
newScale
- scale of the result returned.roundingMode
- rounding mode to be used to round the result.- Returns:
- a new
BigDecimal
instance with the specified scale. - Throws:
NullPointerException
- ifroundingMode == null
.ArithmeticException
- ifroundingMode == ROUND_UNNECESSARY
and rounding is necessary according to the given scale.
-
setScale
Returns a newBigDecimal
instance with the specified scale.If the new scale is greater than the old scale, then additional zeros are added to the unscaled value. In this case no rounding is necessary.
If the new scale is smaller than the old scale, then trailing digits are removed. If these trailing digits are not zero, then the remaining unscaled value has to be rounded. For this rounding operation the specified rounding mode is used.
- Parameters:
newScale
- scale of the result returned.roundingMode
- rounding mode to be used to round the result.- Returns:
- a new
BigDecimal
instance with the specified scale. - Throws:
IllegalArgumentException
- ifroundingMode
is not a valid rounding mode.ArithmeticException
- ifroundingMode == ROUND_UNNECESSARY
and rounding is necessary according to the given scale.
-
setScale
Returns a newBigDecimal
instance with the specified scale. If the new scale is greater than the old scale, then additional zeros are added to the unscaled value. If the new scale is smaller than the old scale, then trailing zeros are removed. If the trailing digits are not zeros then an ArithmeticException is thrown.If no exception is thrown, then the following equation holds:
x.setScale(s).compareTo(x) == 0
.- Parameters:
newScale
- scale of the result returned.- Returns:
- a new
BigDecimal
instance with the specified scale. - Throws:
ArithmeticException
- if rounding would be necessary.
-
movePointLeft
Returns a newBigDecimal
instance where the decimal point has been movedn
places to the left. Ifn < 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 hasscale >= 0
.- Parameters:
n
- number of placed the decimal point has to be moved.- Returns:
this * 10^(-n
).
-
movePointRight
Returns a newBigDecimal
instance where the decimal point has been movedn
places to the right. Ifn < 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:
this * 10^n
.
-
scaleByPowerOfTen
Returns a newBigDecimal
whose value isthis
10^n
. The scale of the result isthis.scale()
-n
. The precision of the result is the precision ofthis
.This method has the same effect as
movePointRight(int)
, except that the precision is not changed.- Parameters:
n
- number of places the decimal point has to be moved.- Returns:
this * 10^n
-
stripTrailingZeros
Returns a newBigDecimal
instance with the same value asthis
but with a unscaled value where the trailing zeros have been removed. If the unscaled value ofthis
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.
-
compareTo
Compares thisBigDecimal
withval
. Returns one of the three values1
,0
, or-1
. The method behaves as ifthis.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.- Specified by:
compareTo
in interfaceComparable<TBigDecimal>
- Parameters:
val
- value to be compared withthis
.- Returns:
1
ifthis > val
,-1
ifthis < val
,0
ifthis == val
.- Throws:
NullPointerException
- ifval == null
.
-
equals
Returnstrue
ifx
is aBigDecimal
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. -
min
Returns the minimum of thisBigDecimal
andval
.- Parameters:
val
- value to be used to compute the minimum with this.- Returns:
min(this, val
.- Throws:
NullPointerException
- ifval == null
.
-
max
Returns the maximum of thisBigDecimal
andval
.- Parameters:
val
- value to be used to compute the maximum with this.- Returns:
max(this, val
.- Throws:
NullPointerException
- ifval == null
.
-
hashCode
public int hashCode()Returns a hash code for thisBigDecimal
. -
toString
Returns a canonical string representation of thisBigDecimal
. 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. -
toEngineeringString
Returns a string representation of thisBigDecimal
. 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.
-
toPlainString
Returns a string representation of thisBigDecimal
. 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 returnsfalse
.x.compareTo(new BigDecimal(x.toPlainString())
returns0
.- Returns:
- a string representation of
this
without exponent part.
-
toBigInteger
Returns thisBigDecimal
as a big integer instance. A fractional part is discarded.- Returns:
- this
BigDecimal
as a big integer instance.
-
toBigIntegerExact
Returns thisBigDecimal
as a big integer instance if it has no fractional part. If thisBigDecimal
has a fractional part, i.e. if rounding would be necessary, anArithmeticException
is thrown.- Returns:
- this
BigDecimal
as a big integer value. - Throws:
ArithmeticException
- if rounding is necessary.
-
longValue
public long longValue()Returns thisBigDecimal
as an long value. Any fractional part is discarded. If the integral part ofthis
is too big to be represented as an long, thenthis
% 2^64 is returned. -
longValueExact
public long longValueExact()Returns thisBigDecimal
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, anArithmeticException
is thrown.- Returns:
- this
BigDecimal
as a long value. - Throws:
ArithmeticException
- if rounding is necessary or the number doesn't fit in a long.
-
intValue
public int intValue()Returns thisBigDecimal
as an int value. Any fractional part is discarded. If the integral part ofthis
is too big to be represented as an int, thenthis
% 2^32 is returned. -
intValueExact
public int intValueExact()Returns thisBigDecimal
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, anArithmeticException
is thrown.- Returns:
- this
BigDecimal
as a int value. - Throws:
ArithmeticException
- if rounding is necessary or the number doesn't fit in a int.
-
shortValueExact
public short shortValueExact()Returns thisBigDecimal
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, anArithmeticException
is thrown.- Returns:
- this
BigDecimal
as a short value. - Throws:
ArithmeticException
- if rounding is necessary of the number doesn't fit in a short.
-
byteValueExact
public byte byteValueExact()Returns thisBigDecimal
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, anArithmeticException
is thrown.- Returns:
- this
BigDecimal
as a byte value. - Throws:
ArithmeticException
- if rounding is necessary or the number doesn't fit in a byte.
-
floatValue
public float floatValue()Returns thisBigDecimal
as a float value. Ifthis
is too big to be represented as an float, thenFloat.POSITIVE_INFINITY
orFloat.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 thusx1.equals(new BigDecimal(x1.folatValue())
returnsfalse
for this case.Similarly, if the instance
new BigDecimal(16777217)
is converted to a float, the result is1.6777216E
7.- Specified by:
floatValue
in classNumber
- Returns:
- this
BigDecimal
as a float value.
-
doubleValue
public double doubleValue()Returns thisBigDecimal
as a double value. Ifthis
is too big to be represented as an float, thenDouble.POSITIVE_INFINITY
orDouble.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 thusx1.equals(new BigDecimal(x1.doubleValue())
returnsfalse
for this case.Similarly, if the instance
new BigDecimal(9007199254740993L)
is converted to a double, the result is9.007199254740992E15
.- Specified by:
doubleValue
in classNumber
- Returns:
- this
BigDecimal
as a double value.
-
ulp
Returns the unit in the last place (ULP) of thisBigDecimal
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()
returns1E-55
.- Returns:
- unit in the last place (ULP) of this
BigDecimal
instance.
-