Most visited

Recently visited

Added in API level 1

BigDecimal

public class BigDecimal
extends Number implements Comparable<BigDecimal>, Serializable

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


An immutable arbitrary-precision signed decimal.

A value is represented by an arbitrary-precision "unscaled value" and a signed 32-bit "scale", combined thus: unscaled * 10<sup>-scale</sup>. See unscaledValue() and scale().

Most operations allow you to supply a MathContext to specify a desired rounding mode.

Summary

Constants

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.

Fields

public static final BigDecimal ONE

The constant one as a BigDecimal.

public static final BigDecimal TEN

The constant ten as a BigDecimal.

public static final 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(MathContext mc)

Returns a BigDecimal whose value is the absolute value of this.

BigDecimal abs()

Returns a 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, int roundingMode)

Returns a new BigDecimal whose value is this / divisor.

BigDecimal divide(BigDecimal divisor, int scale, RoundingMode roundingMode)

Returns a new BigDecimal whose value is this / divisor.

BigDecimal divide(BigDecimal divisor, int roundingMode)

Returns a new BigDecimal whose value is this / divisor.

BigDecimal divide(BigDecimal divisor, MathContext mc)

Returns a new BigDecimal whose value is this / divisor.

BigDecimal divide(BigDecimal divisor, RoundingMode roundingMode)

Returns a new BigDecimal whose value is this / divisor.

BigDecimal divide(BigDecimal divisor)

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 ([-231..231-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 ([-263..263-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()

Returns a new BigDecimal whose value is the -this.

BigDecimal negate(MathContext mc)

Returns a new BigDecimal whose value is the -this.

BigDecimal plus()

Returns a new BigDecimal whose value is +this.

BigDecimal plus(MathContext mc)

Returns a new BigDecimal whose value is +this.

BigDecimal pow(int n, MathContext mc)

Returns a new BigDecimal whose value is this<sup>n</sup>.

BigDecimal pow(int n)

Returns a new BigDecimal whose value is this<sup>n</sup>.

int precision()

Returns the precision of this BigDecimal.

BigDecimal remainder(BigDecimal divisor)

Returns a new BigDecimal whose value is this % divisor.

BigDecimal remainder(BigDecimal divisor, MathContext mc)

Returns a new BigDecimal whose value is this % divisor.

BigDecimal round(MathContext mc)

Returns a new BigDecimal whose value is this, rounded according to the passed context mc.

int scale()

Returns the scale of this BigDecimal.

BigDecimal scaleByPowerOfTen(int n)

Returns a new BigDecimal whose value is this * 10<sup>n</sup>.

BigDecimal setScale(int newScale, int 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, RoundingMode roundingMode)

Returns a new BigDecimal instance with the specified scale.

short shortValueExact()

Returns this BigDecimal as a short value if it has no fractional part and if its value fits to the short range ([-215..215-1]).

int signum()

Returns the sign of this BigDecimal.

BigDecimal stripTrailingZeros()

Returns a new BigDecimal instance with the same value as this but with a unscaled value where the trailing zeros have been removed.

BigDecimal subtract(BigDecimal subtrahend)

Returns a new BigDecimal whose value is this - subtrahend.

BigDecimal subtract(BigDecimal subtrahend, MathContext mc)

Returns a new BigDecimal whose value is this - subtrahend.

BigInteger toBigInteger()

Returns this BigDecimal as a big integer instance.

BigInteger toBigIntegerExact()

Returns this BigDecimal as a big integer instance if it has no fractional part.

String toEngineeringString()

Returns a string representation of this BigDecimal.

String toPlainString()

Returns a string representation of this BigDecimal.

String toString()

Returns a canonical string representation of this BigDecimal.

BigDecimal ulp()

Returns the unit in the last place (ULP) of this BigDecimal instance.

BigInteger unscaledValue()

Returns the unscaled value (mantissa) of this BigDecimal instance as a BigInteger.

static BigDecimal valueOf(double val)

Returns a new BigDecimal instance whose value is equal to val.

static BigDecimal valueOf(long unscaledVal)

Returns a new BigDecimal instance whose value is equal to unscaledVal.

static BigDecimal valueOf(long unscaledVal, int scale)

Returns a new BigDecimal instance whose value is equal to unscaledVal * 10<sup>-scale</sup>).

Inherited methods

From class java.lang.Number
From class java.lang.Object
From interface java.lang.Comparable

Constants

ROUND_CEILING

Added in API level 1
int ROUND_CEILING

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

See also:

Constant Value: 2 (0x00000002)

ROUND_DOWN

Added in API level 1
int ROUND_DOWN

Rounding mode where the values are rounded towards zero.

See also:

Constant Value: 1 (0x00000001)

ROUND_FLOOR

Added in API level 1
int ROUND_FLOOR

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

See also:

Constant Value: 3 (0x00000003)

ROUND_HALF_DOWN

Added in API level 1
int ROUND_HALF_DOWN

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

See also:

Constant Value: 5 (0x00000005)

ROUND_HALF_EVEN

Added in API level 1
int ROUND_HALF_EVEN

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

See also:

Constant Value: 6 (0x00000006)

ROUND_HALF_UP

Added in API level 1
int ROUND_HALF_UP

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

See also:

Constant Value: 4 (0x00000004)

ROUND_UNNECESSARY

Added in API level 1
int ROUND_UNNECESSARY

Rounding mode where the rounding operations throws an ArithmeticException for the case that rounding is necessary, i.e. for the case that the value cannot be represented exactly.

See also:

Constant Value: 7 (0x00000007)

ROUND_UP

Added in API level 1
int ROUND_UP

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

See also:

Constant Value: 0 (0x00000000)

Fields

ONE

Added in API level 1
BigDecimal ONE

The constant one as a BigDecimal.

TEN

Added in API level 1
BigDecimal TEN

The constant ten as a BigDecimal.

ZERO

Added in API level 1
BigDecimal ZERO

The constant zero as a BigDecimal.

Public constructors

BigDecimal

Added in API level 1
BigDecimal (char[] in, 
                int offset, 
                int len)

Constructs a new BigDecimal instance from a string representation given as a character array.

Parameters
in char: array of characters containing the string representation of this BigDecimal.
offset int: first index to be copied.
len int: number of characters to be used.
Throws
NumberFormatException if offset < 0 || len <= 0 || offset+len-1 < 0 || offset+len-1 >= in.length, or if in does not contain a valid string representation of a big decimal.

BigDecimal

Added in API level 1
BigDecimal (char[] in, 
                int offset, 
                int len, 
                MathContext mc)

Constructs a new BigDecimal instance from a string representation given as a character array.

Parameters
in char: array of characters containing the string representation of this BigDecimal.
offset int: first index to be copied.
len int: number of characters to be used.
mc MathContext: rounding mode and precision for the result of this operation.
Throws
NumberFormatException if offset < 0 || len <= 0 || offset+len-1 < 0 || offset+len-1 >= in.length, or if in does not contain a valid string representation of a big decimal.
ArithmeticException if mc.precision > 0 and mc.roundingMode == UNNECESSARY and the new big decimal cannot be represented within the given precision without rounding.

BigDecimal

Added in API level 1
BigDecimal (char[] in)

Constructs a new BigDecimal instance from a string representation given as a character array.

Parameters
in char: array of characters containing the string representation of this BigDecimal.
Throws
NumberFormatException if in does not contain a valid string representation of a big decimal.

BigDecimal

Added in API level 1
BigDecimal (char[] in, 
                MathContext mc)

Constructs a new BigDecimal instance from a string representation given as a character array. The result is rounded according to the specified math context.

Parameters
in char: array of characters containing the string representation of this BigDecimal.
mc MathContext: rounding mode and precision for the result of this operation.
Throws
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.

BigDecimal

Added in API level 1
BigDecimal (String val)

Constructs a new BigDecimal instance from a string representation.

Parameters
val String
Throws
NumberFormatException if val does not contain a valid string representation of a big decimal.

BigDecimal

Added in API level 1
BigDecimal (String val, 
                MathContext mc)

Constructs a new BigDecimal instance from a string representation. The result is rounded according to the specified math context.

Parameters
val String
mc MathContext: 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.

BigDecimal

Added in API level 1
BigDecimal (double val)

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: double value to be converted to a BigDecimal instance.
Throws
NumberFormatException if val is infinity or not a number.

BigDecimal

Added in API level 1
BigDecimal (double val, 
                MathContext mc)

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: double value to be converted to a BigDecimal instance.
mc MathContext: 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.

BigDecimal

Added in API level 1
BigDecimal (BigInteger val)

Constructs a new BigDecimal instance from the given big integer val. The scale of the result is 0.

Parameters
val BigInteger

BigDecimal

Added in API level 1
BigDecimal (BigInteger val, 
                MathContext mc)

Constructs a new BigDecimal instance from the given big integer val. The scale of the result is 0.

Parameters
val BigInteger
mc MathContext: 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.

BigDecimal

Added in API level 1
BigDecimal (BigInteger unscaledVal, 
                int scale)

Constructs a new BigDecimal instance from a given unscaled value unscaledVal and a given scale. The value of this instance is unscaledVal * 10<sup>-scale</sup>).

Parameters
unscaledVal BigInteger
scale int
Throws
NullPointerException if unscaledVal == null.

BigDecimal

Added in API level 1
BigDecimal (BigInteger unscaledVal, 
                int scale, 
                MathContext mc)

Constructs a new BigDecimal instance from a given unscaled value unscaledVal and a given scale. The value of this instance is {@code unscaledVal * 10-scale). The result is rounded according to the specified math context.

Parameters
unscaledVal BigInteger
scale int
mc MathContext: 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.

BigDecimal

Added in API level 1
BigDecimal (int val)

Constructs a new BigDecimal instance from the given int val. The scale of the result is 0.

Parameters
val int: int value to be converted to a BigDecimal instance.

BigDecimal

Added in API level 1
BigDecimal (int val, 
                MathContext mc)

Constructs a new BigDecimal instance from the given int val. The scale of the result is 0. The result is rounded according to the specified math context.

Parameters
val int: int value to be converted to a BigDecimal instance.
mc MathContext: 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.

BigDecimal

Added in API level 1
BigDecimal (long val)

Constructs a new BigDecimal instance from the given long val. The scale of the result is 0.

Parameters
val long: long value to be converted to a BigDecimal instance.

BigDecimal

Added in API level 1
BigDecimal (long val, 
                MathContext mc)

Constructs a new BigDecimal instance from the given long val. The scale of the result is 0. The result is rounded according to the specified math context.

Parameters
val long: long value to be converted to a BigDecimal instance.
mc MathContext: 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

abs

Added in API level 1
BigDecimal abs (MathContext mc)

Returns a BigDecimal whose value is the absolute value of this. The result is rounded according to the passed context mc.

Parameters
mc MathContext
Returns
BigDecimal

abs

Added in API level 1
BigDecimal abs ()

Returns a BigDecimal whose value is the absolute value of this. The scale of the result is the same as the scale of this.

Returns
BigDecimal

add

Added in API level 1
BigDecimal add (BigDecimal augend)

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 BigDecimal: value to be added to this.
Returns
BigDecimal this + augend.
Throws
NullPointerException if augend == null.

add

Added in API level 1
BigDecimal add (BigDecimal augend, 
                MathContext mc)

Returns a new BigDecimal whose value is this + augend. The result is rounded according to the passed context mc.

Parameters
augend BigDecimal: value to be added to this.
mc MathContext: rounding mode and precision for the result of this operation.
Returns
BigDecimal this + augend.
Throws
NullPointerException if augend == null or mc == null.

byteValueExact

Added in API level 1
byte byteValueExact ()

Returns this BigDecimal as a byte value if it has no fractional part and if its value fits to the byte range ([-128..127]). If these conditions are not met, an ArithmeticException is thrown.

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

compareTo

Added in API level 1
int compareTo (BigDecimal val)

Compares this BigDecimal with val. Returns one of the three values 1, 0, or -1. The method behaves as if this.subtract(val) is computed. If this difference is > 0 then 1 is returned, if the difference is < 0 then -1 is returned, and if the difference is 0 then 0 is returned. This means, that if two decimal instances are compared which are equal in value but differ in scale, then these two instances are considered as equal.

Parameters
val BigDecimal: value to be compared with this.
Returns
int 1 if this > val, -1 if this < val, 0 if this == val.
Throws
NullPointerException if val == null.

divide

Added in API level 1
BigDecimal divide (BigDecimal divisor, 
                int scale, 
                int roundingMode)

Returns a new BigDecimal whose value is this / divisor. As scale of the result the parameter scale is used. If rounding is required to meet the specified scale, then the specified rounding mode roundingMode is applied.

Parameters
divisor BigDecimal: value by which this is divided.
scale int: the scale of the result returned.
roundingMode int: rounding mode to be used to round the result.
Returns
BigDecimal 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.

divide

Added in API level 1
BigDecimal divide (BigDecimal divisor, 
                int scale, 
                RoundingMode roundingMode)

Returns a new BigDecimal whose value is this / divisor. As scale of the result the parameter scale is used. If rounding is required to meet the specified scale, then the specified rounding mode roundingMode is applied.

Parameters
divisor BigDecimal: value by which this is divided.
scale int: the scale of the result returned.
roundingMode RoundingMode: rounding mode to be used to round the result.
Returns
BigDecimal 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 given scale and given precision.

divide

Added in API level 1
BigDecimal divide (BigDecimal divisor, 
                int roundingMode)

Returns a new BigDecimal whose value is this / divisor. The scale of the result is the scale of this. If rounding is required to meet the specified scale, then the specified rounding mode roundingMode is applied.

Parameters
divisor BigDecimal: value by which this is divided.
roundingMode int: rounding mode to be used to round the result.
Returns
BigDecimal 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.

divide

Added in API level 1
BigDecimal divide (BigDecimal divisor, 
                MathContext mc)

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 BigDecimal: value by which this is divided.
mc MathContext: rounding mode and precision for the result of this operation.
Returns
BigDecimal 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().

divide

Added in API level 1
BigDecimal divide (BigDecimal divisor, 
                RoundingMode roundingMode)

Returns a new BigDecimal whose value is this / divisor. The scale of the result is the scale of this. If rounding is required to meet the specified scale, then the specified rounding mode roundingMode is applied.

Parameters
divisor BigDecimal: value by which this is divided.
roundingMode RoundingMode: rounding mode to be used to round the result.
Returns
BigDecimal 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.

divide

Added in API level 1
BigDecimal divide (BigDecimal divisor)

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 BigDecimal: value by which this is divided.
Returns
BigDecimal this / divisor.
Throws
NullPointerException if divisor == null.
ArithmeticException if divisor == 0.
ArithmeticException if the result cannot be represented exactly.

divideAndRemainder

Added in API level 1
BigDecimal[] divideAndRemainder (BigDecimal divisor, 
                MathContext mc)

Returns a BigDecimal array which contains the integral part of this / divisor at index 0 and the remainder this % divisor at index 1. 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 BigDecimal: value by which this is divided.
mc MathContext: math context which determines the maximal precision of the result.
Returns
BigDecimal[] [this.divideToIntegralValue(divisor), this.remainder(divisor)].
Throws
NullPointerException if divisor == null.
ArithmeticException if divisor == 0.

See also:

divideAndRemainder

Added in API level 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. The quotient is rounded down towards zero to the next integer.

Parameters
divisor BigDecimal: value by which this is divided.
Returns
BigDecimal[] [this.divideToIntegralValue(divisor), this.remainder(divisor)].
Throws
NullPointerException if divisor == null.
ArithmeticException if divisor == 0.

See also:

divideToIntegralValue

Added in API level 1
BigDecimal divideToIntegralValue (BigDecimal divisor, 
                MathContext mc)

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 BigDecimal: value by which this is divided.
mc MathContext: math context which determines the maximal precision of the result.
Returns
BigDecimal 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.

divideToIntegralValue

Added in API level 1
BigDecimal divideToIntegralValue (BigDecimal divisor)

Returns a new BigDecimal whose value is the integral part of this / divisor. The quotient is rounded down towards zero to the next integer. For example, 0.5/0.2 = 2.

Parameters
divisor BigDecimal: value by which this is divided.
Returns
BigDecimal integral part of this / divisor.
Throws
NullPointerException if divisor == null.
ArithmeticException if divisor == 0.

doubleValue

Added in API level 1
double doubleValue ()

Returns this BigDecimal as a double value. If this is too big to be represented as an float, then Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY is returned.

Note, that if the unscaled value has more than 53 significant digits, then this decimal cannot be represented exactly in a double variable. In this case the result is rounded.

For example, if the instance x1 = new BigDecimal("0.1") cannot be represented exactly as a double, and thus x1.equals(new BigDecimal(x1.doubleValue()) returns false for this case.

Similarly, if the instance new BigDecimal(9007199254740993L) is converted to a double, the result is 9.007199254740992E15.

Returns
double this BigDecimal as a double value.

equals

Added in API level 1
boolean equals (Object x)

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: the reference object with which to compare.
Returns
boolean true if this object is the same as the obj argument; false otherwise.

floatValue

Added in API level 1
float floatValue ()

Returns this BigDecimal as a float value. If this is too big to be represented as an float, then Float.POSITIVE_INFINITY or Float.NEGATIVE_INFINITY is returned.

Note, that if the unscaled value has more than 24 significant digits, then this decimal cannot be represented exactly in a float variable. In this case the result is rounded.

For example, if the instance x1 = new BigDecimal("0.1") cannot be represented exactly as a float, and thus x1.equals(new BigDecimal(x1.floatValue()) returns false for this case.

Similarly, if the instance new BigDecimal(16777217) is converted to a float, the result is 1.6777216E7.

Returns
float this BigDecimal as a float value.

hashCode

Added in API level 1
int hashCode ()

Returns a hash code for this BigDecimal.

Returns
int hash code for this.

intValue

Added in API level 1
int intValue ()

Returns this BigDecimal as an int value. Any fractional part is discarded. If the integral part of this is too big to be represented as an int, then this % 2<sup>32</sup> is returned.

Returns
int the numeric value represented by this object after conversion to type int.

intValueExact

Added in API level 1
int intValueExact ()

Returns this BigDecimal as a int value if it has no fractional part and if its value fits to the int range ([-231..231-1]). If these conditions are not met, an ArithmeticException is thrown.

Returns
int
Throws
ArithmeticException if rounding is necessary or the number doesn't fit in an int.

longValue

Added in API level 1
long longValue ()

Returns this BigDecimal as an long value. Any fractional part is discarded. If the integral part of this is too big to be represented as an long, then this % 2<sup>64</sup> is returned.

Returns
long the numeric value represented by this object after conversion to type long.

longValueExact

Added in API level 1
long longValueExact ()

Returns this BigDecimal as a long value if it has no fractional part and if its value fits to the int range ([-263..263-1]). If these conditions are not met, an ArithmeticException is thrown.

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

max

Added in API level 1
BigDecimal max (BigDecimal val)

Returns the maximum of this BigDecimal and val.

Parameters
val BigDecimal: value to be used to compute the maximum with this.
Returns
BigDecimal max(this, val.
Throws
NullPointerException if val == null.

min

Added in API level 1
BigDecimal min (BigDecimal val)

Returns the minimum of this BigDecimal and val.

Parameters
val BigDecimal: value to be used to compute the minimum with this.
Returns
BigDecimal min(this, val.
Throws
NullPointerException if val == null.

movePointLeft

Added in API level 1
BigDecimal movePointLeft (int n)

Returns a new BigDecimal instance where the decimal point has been moved n places to the left. If n < 0 then the decimal point is moved -n places to the right.

The result is obtained by changing its scale. If the scale of the result becomes negative, then its precision is increased such that the scale is zero.

Note, that movePointLeft(0) returns a result which is mathematically equivalent, but which has scale >= 0.

Parameters
n int
Returns
BigDecimal

movePointRight

Added in API level 1
BigDecimal movePointRight (int n)

Returns a new BigDecimal instance where the decimal point has been moved n places to the right. If n < 0 then the decimal point is moved -n places to the left.

The result is obtained by changing its scale. If the scale of the result becomes negative, then its precision is increased such that the scale is zero.

Note, that movePointRight(0) returns a result which is mathematically equivalent, but which has scale >= 0.

Parameters
n int
Returns
BigDecimal

multiply

Added in API level 1
BigDecimal multiply (BigDecimal multiplicand, 
                MathContext mc)

Returns a new BigDecimal whose value is this * multiplicand. The result is rounded according to the passed context mc.

Parameters
multiplicand BigDecimal: value to be multiplied with this.
mc MathContext: rounding mode and precision for the result of this operation.
Returns
BigDecimal this * multiplicand.
Throws
NullPointerException if multiplicand == null or mc == null.

multiply

Added in API level 1
BigDecimal multiply (BigDecimal multiplicand)

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 BigDecimal: value to be multiplied with this.
Returns
BigDecimal this * multiplicand.
Throws
NullPointerException if multiplicand == null.

negate

Added in API level 1
BigDecimal negate ()

Returns a new BigDecimal whose value is the -this. The scale of the result is the same as the scale of this.

Returns
BigDecimal -this

negate

Added in API level 1
BigDecimal negate (MathContext mc)

Returns a new BigDecimal whose value is the -this. The result is rounded according to the passed context mc.

Parameters
mc MathContext: rounding mode and precision for the result of this operation.
Returns
BigDecimal -this

plus

Added in API level 1
BigDecimal plus ()

Returns a new BigDecimal whose value is +this. The scale of the result is the same as the scale of this.

Returns
BigDecimal this

plus

Added in API level 1
BigDecimal plus (MathContext mc)

Returns a new BigDecimal whose value is +this. The result is rounded according to the passed context mc.

Parameters
mc MathContext: rounding mode and precision for the result of this operation.
Returns
BigDecimal this, rounded

pow

Added in API level 1
BigDecimal pow (int n, 
                MathContext mc)

Returns a new BigDecimal whose value is this<sup>n</sup>. 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 int
mc MathContext: rounding mode and precision for the result of this operation.
Returns
BigDecimal
Throws
ArithmeticException if n < 0 or n > 999999999.

pow

Added in API level 1
BigDecimal pow (int n)

Returns a new BigDecimal whose value is this<sup>n</sup>. The scale of the result is n * this.scale().

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 int
Returns
BigDecimal
Throws
ArithmeticException if n < 0 or n > 999999999.

precision

Added in API level 1
int precision ()

Returns the precision of this BigDecimal. The precision is the number of decimal digits used to represent this decimal. It is equivalent to the number of digits of the unscaled value. The precision of 0 is 1 (independent of the scale).

Returns
int the precision of this BigDecimal.

remainder

Added in API level 1
BigDecimal remainder (BigDecimal divisor)

Returns a new BigDecimal whose value is this % divisor.

The remainder is defined as this - this.divideToIntegralValue(divisor) * divisor.

Parameters
divisor BigDecimal: value by which this is divided.
Returns
BigDecimal this % divisor.
Throws
NullPointerException if divisor == null.
ArithmeticException if divisor == 0.

remainder

Added in API level 1
BigDecimal remainder (BigDecimal divisor, 
                MathContext mc)

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 BigDecimal: value by which this is divided.
mc MathContext: rounding mode and precision to be used.
Returns
BigDecimal 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.

round

Added in API level 1
BigDecimal round (MathContext mc)

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 MathContext: rounding mode and precision for the result of this operation.
Returns
BigDecimal 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.

scale

Added in API level 1
int scale ()

Returns the scale of this BigDecimal. The scale is the number of digits behind the decimal point. The value of this BigDecimal is the unsignedValue * 10<sup>-scale</sup>. If the scale is negative, then this BigDecimal represents a big integer.

Returns
int the scale of this BigDecimal.

scaleByPowerOfTen

Added in API level 1
BigDecimal scaleByPowerOfTen (int n)

Returns a new BigDecimal whose value is this * 10<sup>n</sup>. 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 int
Returns
BigDecimal

setScale

Added in API level 1
BigDecimal setScale (int newScale, 
                int roundingMode)

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 int: scale of the result returned.
roundingMode int: rounding mode to be used to round the result.
Returns
BigDecimal 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.

setScale

Added in API level 1
BigDecimal setScale (int newScale)

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 int: scale of the result returned.
Returns
BigDecimal a new BigDecimal instance with the specified scale.
Throws
ArithmeticException if rounding would be necessary.

setScale

Added in API level 1
BigDecimal setScale (int newScale, 
                RoundingMode roundingMode)

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 int: scale of the result returned.
roundingMode RoundingMode: rounding mode to be used to round the result.
Returns
BigDecimal 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.

shortValueExact

Added in API level 1
short shortValueExact ()

Returns this BigDecimal as a short value if it has no fractional part and if its value fits to the short range ([-215..215-1]). If these conditions are not met, an ArithmeticException is thrown.

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

signum

Added in API level 1
int signum ()

Returns the sign of this BigDecimal.

Returns
int -1 if this < 0, 0 if this == 0, 1 if this > 0.

stripTrailingZeros

Added in API level 1
BigDecimal stripTrailingZeros ()

Returns a new BigDecimal instance with the same value as this but with a unscaled value where the trailing zeros have been removed. If the unscaled value of this has n trailing zeros, then the scale and the precision of the result has been reduced by n.

Returns
BigDecimal a new BigDecimal instance equivalent to this where the trailing zeros of the unscaled value have been removed.

subtract

Added in API level 1
BigDecimal subtract (BigDecimal subtrahend)

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 BigDecimal: value to be subtracted from this.
Returns
BigDecimal this - subtrahend.
Throws
NullPointerException if subtrahend == null.

subtract

Added in API level 1
BigDecimal subtract (BigDecimal subtrahend, 
                MathContext mc)

Returns a new BigDecimal whose value is this - subtrahend. The result is rounded according to the passed context mc.

Parameters
subtrahend BigDecimal: value to be subtracted from this.
mc MathContext: rounding mode and precision for the result of this operation.
Returns
BigDecimal this - subtrahend.
Throws
NullPointerException if subtrahend == null or mc == null.

toBigInteger

Added in API level 1
BigInteger toBigInteger ()

Returns this BigDecimal as a big integer instance. A fractional part is discarded.

Returns
BigInteger this BigDecimal as a big integer instance.

toBigIntegerExact

Added in API level 1
BigInteger toBigIntegerExact ()

Returns this BigDecimal as a big integer instance if it has no fractional part. If this BigDecimal has a fractional part, i.e. if rounding would be necessary, an ArithmeticException is thrown.

Returns
BigInteger this BigDecimal as a big integer value.
Throws
ArithmeticException if rounding is necessary.

toEngineeringString

Added in API level 1
String toEngineeringString ()

Returns a string representation of this BigDecimal. This representation always prints all significant digits of this value.

If the scale is negative or if scale - precision >= 6 then engineering notation is used. Engineering notation is similar to the scientific notation except that the exponent is made to be a multiple of 3 such that the integer part is >= 1 and < 1000.

Returns
String a string representation of this in engineering notation if necessary.

toPlainString

Added in API level 1
String toPlainString ()

Returns a string representation of this BigDecimal. No scientific notation is used. This methods adds zeros where necessary.

If this string representation is used to create a new instance, this instance is generally not identical to this as the precision changes.

x.equals(new BigDecimal(x.toPlainString()) usually returns false.

x.compareTo(new BigDecimal(x.toPlainString()) returns 0.

Returns
String a string representation of this without exponent part.

toString

Added in API level 1
String toString ()

Returns a canonical string representation of this BigDecimal. If necessary, scientific notation is used. This representation always prints all significant digits of this value.

If the scale is negative or if scale - precision >= 6 then scientific notation is used.

Returns
String a string representation of this in scientific notation if necessary.

ulp

Added in API level 1
BigDecimal ulp ()

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
BigDecimal unit in the last place (ULP) of this BigDecimal instance.

unscaledValue

Added in API level 1
BigInteger unscaledValue ()

Returns the unscaled value (mantissa) of this BigDecimal instance as a BigInteger. The unscaled value can be computed as this * 10<sup>scale</sup>.

Returns
BigInteger

valueOf

Added in API level 1
BigDecimal valueOf (double val)

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: double value to be converted to a BigDecimal.
Returns
BigDecimal BigDecimal instance with the value val.
Throws
NumberFormatException if val is infinite or val is not a number

valueOf

Added in API level 1
BigDecimal valueOf (long unscaledVal)

Returns a new BigDecimal instance whose value is equal to unscaledVal. The scale of the result is 0, and its unscaled value is unscaledVal.

Parameters
unscaledVal long: value to be converted to a BigDecimal.
Returns
BigDecimal BigDecimal instance with the value unscaledVal.

valueOf

Added in API level 1
BigDecimal valueOf (long unscaledVal, 
                int scale)

Returns a new BigDecimal instance whose value is equal to unscaledVal * 10<sup>-scale</sup>). The scale of the result is scale, and its unscaled value is unscaledVal.

Parameters
unscaledVal long
scale int
Returns
BigDecimal

Hooray!