Summary: Constants | Ctors | Methods | Inherited Methods | [Expand All]

public class

BigDecimal

extends Number
implements Serializable Comparable<T>

java.lang.Object
↳	java.lang.Number
	↳	java.math.BigDecimal

Class Overview

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.

Summary

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
	BigDecimal(char[] in, int offset, int len) Constructs a new `BigDecimal` instance from a string representation given as a character array.
	BigDecimal(char[] in, int offset, int len, MathContext mc) Constructs a new `BigDecimal` instance from a string representation given as a character array.
	BigDecimal(char[] in) Constructs a new `BigDecimal` instance from a string representation given as a character array.
	BigDecimal(char[] in, MathContext mc) Constructs a new `BigDecimal` instance from a string representation given as a character array.
	BigDecimal(String val) Constructs a new `BigDecimal` instance from a string representation.
	BigDecimal(String val, MathContext mc) Constructs a new `BigDecimal` instance from a string representation.
	BigDecimal(double val) Constructs a new `BigDecimal` instance from the 64bit double `val`.
	BigDecimal(double val, MathContext mc) Constructs a new `BigDecimal` instance from the 64bit double `val`.
	BigDecimal(BigInteger val) Constructs a new `BigDecimal` instance from the given big integer `val`.
	BigDecimal(BigInteger val, MathContext mc) Constructs a new `BigDecimal` instance from the given big integer `val`.
	BigDecimal(BigInteger unscaledVal, int scale) Constructs a new `BigDecimal` instance from a given unscaled value `unscaledVal` and a given scale.
	BigDecimal(BigInteger unscaledVal, int scale, MathContext mc) Constructs a new `BigDecimal` instance from a given unscaled value `unscaledVal` and a given scale.
	BigDecimal(int val) Constructs a new `BigDecimal` instance from the given int `val`.
	BigDecimal(int val, MathContext mc) Constructs a new `BigDecimal` instance from the given int `val`.
	BigDecimal(long val) Constructs a new `BigDecimal` instance from the given long `val`.
	BigDecimal(long val, MathContext mc) Constructs a new `BigDecimal` instance from the given long `val`.

Public Methods
BigDecimal	abs() Returns a new `BigDecimal` whose value is the absolute value of `this`.
BigDecimal	abs(MathContext mc) Returns a new `BigDecimal` whose value is the absolute value of `this`.
BigDecimal	add(BigDecimal augend) Returns a new `BigDecimal` whose value is `this + augend`.
BigDecimal	add(BigDecimal augend, MathContext mc) Returns a new `BigDecimal` whose value is `this + augend`.
byte	byteValueExact() Returns this `BigDecimal` as a byte value if it has no fractional part and if its value fits to the byte range ([-128..127]).
int	compareTo(BigDecimal val) Compares this `BigDecimal` with `val`.
BigDecimal	divide(BigDecimal divisor, int scale, RoundingMode roundingMode) Returns a new `BigDecimal` whose value is `this / divisor`.
BigDecimal	divide(BigDecimal divisor, RoundingMode roundingMode) Returns a new `BigDecimal` whose value is `this / divisor`.
BigDecimal	divide(BigDecimal divisor, MathContext mc) Returns a new `BigDecimal` whose value is `this / divisor`.
BigDecimal	divide(BigDecimal divisor) Returns a new `BigDecimal` whose value is `this / divisor`.
BigDecimal	divide(BigDecimal divisor, int roundingMode) Returns a new `BigDecimal` whose value is `this / divisor`.
BigDecimal	divide(BigDecimal divisor, int scale, int roundingMode) Returns a new `BigDecimal` whose value is `this / divisor`.
BigDecimal[]	divideAndRemainder(BigDecimal divisor, MathContext mc) Returns a `BigDecimal` array which contains the integral part of `this / divisor` at index 0 and the remainder `this % divisor` at index 1.
BigDecimal[]	divideAndRemainder(BigDecimal divisor) Returns a `BigDecimal` array which contains the integral part of `this / divisor` at index 0 and the remainder `this % divisor` at index 1.
BigDecimal	divideToIntegralValue(BigDecimal divisor, MathContext mc) Returns a new `BigDecimal` whose value is the integral part of `this / divisor`.
BigDecimal	divideToIntegralValue(BigDecimal divisor) Returns a new `BigDecimal` whose value is the integral part of `this / divisor`.
double	doubleValue() Returns this `BigDecimal` as a double value.
boolean	equals(Object x) Returns `true` if `x` is a `BigDecimal` instance and if this instance is equal to this big decimal.
float	floatValue() Returns this `BigDecimal` as a float value.
int	hashCode() Returns a hash code for this `BigDecimal`.
int	intValue() Returns this `BigDecimal` as an int value.
int	intValueExact() Returns this `BigDecimal` as a int value if it has no fractional part and if its value fits to the int range ([-2^{31}..2^{31}-1]).
long	longValue() Returns this `BigDecimal` as an long value.
long	longValueExact() Returns this `BigDecimal` as a long value if it has no fractional part and if its value fits to the int range ([-2^{63}..2^{63}-1]).
BigDecimal	max(BigDecimal val) Returns the maximum of this `BigDecimal` and `val`.
BigDecimal	min(BigDecimal val) Returns the minimum of this `BigDecimal` and `val`.
BigDecimal	movePointLeft(int n) Returns a new `BigDecimal` instance where the decimal point has been moved `n` places to the left.
BigDecimal	movePointRight(int n) Returns a new `BigDecimal` instance where the decimal point has been moved `n` places to the right.
BigDecimal	multiply(BigDecimal multiplicand, MathContext mc) Returns a new `BigDecimal` whose value is `this * multiplicand`.
BigDecimal	multiply(BigDecimal multiplicand) Returns a new `BigDecimal` whose value is `this * multiplicand`.
BigDecimal	negate(MathContext mc) Returns a new `BigDecimal` whose value is the `-this`.
BigDecimal	negate() Returns a new `BigDecimal` whose value is the `-this`.
BigDecimal	plus() Returns a new `BigDecimal` whose value is `+this`.
BigDecimal	plus(MathContext mc) Returns a new `BigDecimal` whose value is `+this`.
BigDecimal	pow(int n, MathContext mc) Returns a new `BigDecimal` whose value is `this ^ n`.
BigDecimal	pow(int n) Returns a new `BigDecimal` whose value is `this ^ n`.
int	precision() Returns the precision of this `BigDecimal`.
BigDecimal	remainder(BigDecimal divisor, MathContext mc) Returns a new `BigDecimal` whose value is `this % divisor`.
BigDecimal	remainder(BigDecimal divisor) Returns a new `BigDecimal` whose value is `this % divisor`.
BigDecimal	round(MathContext mc) Returns a new `BigDecimal` whose value is `this`, rounded according to the passed context `mc`.
int	scale() Returns the scale of this `BigDecimal`.
BigDecimal	scaleByPowerOfTen(int n) Returns a new `BigDecimal` whose value is `this` 10^`n`.
BigDecimal	setScale(int newScale, RoundingMode roundingMode) Returns a new `BigDecimal` instance with the specified scale.
BigDecimal	setScale(int newScale) Returns a new `BigDecimal` instance with the specified scale.
BigDecimal	setScale(int newScale, int roundingMode) Returns a new `BigDecimal` instance with the specified scale.
short	shortValueExact() Returns this `BigDecimal` as a short value if it has no fractional part and if its value fits to the short range ([-2^{15}..2^{15}-1]).
int	signum() Returns the sign of this `BigDecimal`.
BigDecimal	stripTrailingZeros() Returns a new `BigDecimal` instance with the same value as `this` but with a unscaled value where the trailing zeros have been removed.
BigDecimal	subtract(BigDecimal subtrahend, MathContext mc) Returns a new `BigDecimal` whose value is `this - subtrahend`.
BigDecimal	subtract(BigDecimal subtrahend) Returns a new `BigDecimal` whose value is `this - subtrahend`.
BigInteger	toBigInteger() Returns this `BigDecimal` as a big integer instance.
BigInteger	toBigIntegerExact() Returns this `BigDecimal` as a big integer instance if it has no fractional part.
String	toEngineeringString() Returns a string representation of this `BigDecimal`.
String	toPlainString() Returns a string representation of this `BigDecimal`.
String	toString() Returns a canonical string representation of this `BigDecimal`.
BigDecimal	ulp() Returns the unit in the last place (ULP) of this `BigDecimal` instance.
BigInteger	unscaledValue() Returns the unscaled value (mantissa) of this `BigDecimal` instance as a `BigInteger`.
static BigDecimal	valueOf(double val) Returns a new `BigDecimal` instance whose value is equal to `val`.
static BigDecimal	valueOf(long unscaledVal, int scale) Returns a new `BigDecimal` instance whose value is equal to `unscaledVal` 10^(-`scale`).
static BigDecimal	valueOf(long unscaledVal) Returns a new `BigDecimal` instance whose value is equal to `unscaledVal`.

[Expand]

Inherited Methods

From class java.lang.Number

From class java.lang.Object

Object	clone() Creates and returns a copy of this `Object`.
boolean	equals(Object o) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Is called before the object's memory is being reclaimed by the VM.
final Class<? extends Object>	getClass() Returns the unique instance of `Class` which represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait(long millis) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.

From interface java.lang.Comparable

Constants

public static final BigDecimal ONE

Since: API Level 1

The constant one as a BigDecimal.

public static final int ROUND_CEILING

Since: API Level 1

Rounding mode to round towards positive infinity. For positive values this rounding mode behaves as ROUND_UP, for negative values as ROUND_DOWN.

public static final int ROUND_DOWN

Since: API Level 1

Rounding mode where the values are rounded towards zero.

public static final int ROUND_FLOOR

Since: API Level 1

Rounding mode to round towards negative infinity. For positive values this rounding mode behaves as ROUND_DOWN, for negative values as ROUND_UP.

public static final int ROUND_HALF_DOWN

Since: API Level 1

Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding down.

public static final int ROUND_HALF_EVEN

Since: API Level 1

Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding to the even neighbor.

public static final int ROUND_HALF_UP

Since: API Level 1

Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding up.

public static final int ROUND_UNNECESSARY

Since: API Level 1

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.

public static final int ROUND_UP

Since: API Level 1

Rounding mode where positive values are rounded towards positive infinity and negative values towards negative infinity.

public static final BigDecimal TEN

Since: API Level 1

The constant ten as a BigDecimal.

public static final BigDecimal ZERO

Since: API Level 1

The constant zero as a BigDecimal.

Public Constructors

public BigDecimal (char[] in, int offset, int len)

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 `BigDecimal`.
offset	first index to be copied.
len	number of characters to be used.

Throws

NullPointerException	if `in == null`.
NumberFormatException	if `offset < 0` or `len <= 0` or `offset+len-1 < 0` or `offset+len-1 >= in.length`.
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 `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.

Throws

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

public BigDecimal (char[] in)

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 `BigDecimal`.

Throws

NullPointerException	if `in == null`.
NumberFormatException	if `in` does not contain a valid string representation of a big decimal.

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

in	array of characters containing the string representation of this `BigDecimal`.
mc	rounding mode and precision for the result of this operation.

Throws

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

public BigDecimal (String val)

Since: API Level 1

Constructs a new BigDecimal instance from a string representation.

Parameters

val	string containing the string representation of this `BigDecimal`.

Throws

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

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

val	string containing the string representation of this `BigDecimal`.
mc	rounding mode and precision for the result of this operation.

Throws

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

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

val	double value to be converted to a `BigDecimal` instance.

Throws

NumberFormatException	if `val` is infinity or not a number.

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

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)

Since: API Level 1

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.

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

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)

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

unscaledVal	`BigInteger` representing the unscaled value of this `BigDecimal` instance.
scale	scale of this `BigDecimal` instance.

Throws

NullPointerException	if `unscaledVal == null`.

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

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.
NullPointerException	if `unscaledVal == null`.

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

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

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

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 `c.roundingMode == UNNECESSARY` and the new big decimal cannot be represented within the given precision without rounding.

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

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

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

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

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 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

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

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

augend	value to be added to `this`.

Returns

this + augend.

Throws

NullPointerException	if `augend == null`.

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

augend	value to be added to `this`.
mc	rounding mode and precision for the result of this operation.

Returns

this + augend.

Throws

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

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.

Throws

ArithmeticException	if rounding is necessary or the number doesn't fit in a byte.

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

val	value to be compared with `this`.

Returns

1 if this > val, -1 if this < val, 0 if this == val.

Throws

NullPointerException	if `val == null`.

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

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.

Throws

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

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

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.

Throws

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

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

divisor	value by which `this` is divided.
mc	rounding mode and precision for the result of this operation.

Returns

this / divisor.

Throws

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

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

divisor	value by which `this` is divided.

Returns

this / divisor.

Throws

NullPointerException	if `divisor == null`.
ArithmeticException	if `divisor == 0`.
ArithmeticException	if the result cannot be represented exactly.

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

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.

Throws

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

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

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.

Throws

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

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

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)].

Throws

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

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

divisor	value by which `this` is divided.

Returns

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

Throws

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

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

divisor	value by which `this` is divided.
mc	math context which determines the maximal precision of the result.

Returns

integral part of this / divisor.

Throws

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

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

divisor	value by which `this` is divided.

Returns

integral part of this / divisor.

Throws

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

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

x	object to be compared with `this`.

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.6777216E7.

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.

Throws

ArithmeticException	if rounding is necessary or the number doesn't fit in a int.

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.

Throws

ArithmeticException	if rounding is necessary or the number doesn't fit in a long.

public BigDecimal max (BigDecimal val)

Since: API Level 1

Returns the maximum of this BigDecimal and val.

Parameters

val	value to be used to compute the maximum with this.

Returns

max(this, val.

Throws

NullPointerException	if `val == null`.

public BigDecimal min (BigDecimal val)

Since: API Level 1

Returns the minimum of this BigDecimal and val.

Parameters

val	value to be used to compute the minimum with this.

Returns

min(this, val.

Throws

NullPointerException	if `val == null`.

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

n	number of placed the decimal point has to be moved.

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

n	number of placed the decimal point has to be moved.

Returns

this * 10^n.

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

multiplicand	value to be multiplied with `this`.
mc	rounding mode and precision for the result of this operation.

Returns

this * multiplicand.

Throws

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

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

multiplicand	value to be multiplied with `this`.

Returns

this * multiplicand.

Throws

NullPointerException	if `multiplicand == null`.

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

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

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 ()

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 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

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

Returns

this, rounded

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

n	exponent to which `this` is raised.
mc	rounding mode and precision for the result of this operation.

Returns

this ^ n.

Throws

ArithmeticException	if `n < 0` or `n > 999999999`.

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

n	exponent to which `this` is raised.

Returns

this ^ n.

Throws

ArithmeticException	if `n < 0` or `n > 999999999`.

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, 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

divisor	value by which `this` is divided.
mc	rounding mode and precision to be used.

Returns

this % divisor.

Throws

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

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

divisor	value by which `this` is divided.

Returns

this % divisor.

Throws

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

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

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 ()

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

n	number of places the decimal point has to be moved.

Returns

this * 10^n

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

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	if `roundingMode == null`.
ArithmeticException	if `roundingMode == ROUND_UNNECESSARY` and rounding is necessary according to the given scale.

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

newScale	scale of the result returned.

Returns

a new BigDecimal instance with the specified scale.

Throws

ArithmeticException	if rounding would be necessary.

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

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	if `roundingMode` is not a valid rounding mode.
ArithmeticException	if `roundingMode == ROUND_UNNECESSARY` and rounding is necessary according to the given scale.

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.

Throws

ArithmeticException	if rounding is necessary of the number doesn't fit in a short.

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

subtrahend	value to be subtracted from `this`.
mc	rounding mode and precision for the result of this operation.

Returns

this - subtrahend.

Throws

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

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

subtrahend	value to be subtracted from `this`.

Returns

this - subtrahend.

Throws

NullPointerException	if `subtrahend == null`.

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.

Throws

ArithmeticException	if rounding is necessary.

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 (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

val	double value to be converted to a `BigDecimal`.

Returns

BigDecimal instance with the value val.

Throws

NumberFormatException	if `val` is infinite or `val` is not a number

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

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)

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

unscaledVal	value to be converted to a `BigDecimal`.

Returns

BigDecimal instance with the value unscaledVal.

Classes

Enums

BigDecimal

Class Overview

Summary

Constants

public static final BigDecimal ONE

public static final int ROUND_CEILING

See Also

public static final int ROUND_DOWN

See Also

public static final int ROUND_FLOOR

See Also

public static final int ROUND_HALF_DOWN

See Also

public static final int ROUND_HALF_EVEN

See Also

public static final int ROUND_HALF_UP

See Also

public static final int ROUND_UNNECESSARY

See Also

public static final int ROUND_UP

See Also

public static final BigDecimal TEN

public static final BigDecimal ZERO

Public Constructors

public BigDecimal (char[] in, int offset, int len)

Parameters

Throws

public BigDecimal (char[] in, int offset, int len, MathContext mc)

Parameters

Throws

public BigDecimal (char[] in)

Parameters

Throws

public BigDecimal (char[] in, MathContext mc)

Parameters

Throws

public BigDecimal (String val)

Parameters

Throws

public BigDecimal (String val, MathContext mc)

Parameters

Throws

public BigDecimal (double val)

Parameters

Throws

public BigDecimal (double val, MathContext mc)

Parameters

Throws

public BigDecimal (BigInteger val)

Parameters

public BigDecimal (BigInteger val, MathContext mc)

Parameters

Throws

public BigDecimal (BigInteger unscaledVal, int scale)

Parameters

Throws

public BigDecimal (BigInteger unscaledVal, int scale, MathContext mc)

Parameters

Throws

public BigDecimal (int val)

Parameters

public BigDecimal (int val, MathContext mc)

Parameters

Throws

public BigDecimal (long val)

Parameters

public BigDecimal (long val, MathContext mc)

Parameters

Throws

Public Methods

public BigDecimal abs ()

Returns

public BigDecimal abs (MathContext mc)

Parameters

Returns

public BigDecimal add (BigDecimal augend)

Parameters

Returns