English | Site Directory

Android - An Open Handset Alliance Project

java.math
public class

java.math.BigDecimal

java.lang.Object
java.lang.Number Serializable
java.math.BigDecimal Serializable Comparable

Class which represents immutable arbritary precision decimal numbers. Each BigDecimal instance is represented with a unscaled arbitrary precision mantissa (the unscaled value) and a scale. The value of the BigDecimal is unscaledValue * 10^{-scale}.

Summary

Constants

      Value  
BigDecimal  ONE  The constant one as a BigDecimal.     
int  ROUND_CEILING  Rounding mode to round towards positive infinity.  0x00000002 
int  ROUND_DOWN  Rounding mode where the values are rounded towards zero.  0x00000001 
int  ROUND_FLOOR  Rounding mode to round towards negative infinity.  0x00000003 
int  ROUND_HALF_DOWN  Rounding mode where values are rounded towards the nearest neighbour.  0x00000005 
int  ROUND_HALF_EVEN  Rounding mode where values are rounded towards the nearest neighbour.  0x00000006 
int  ROUND_HALF_UP  Rounding mode where values are rounded towards the nearest neighbour.  0x00000004 
int  ROUND_UNNECESSARY  Rounding mode where the rounding operations throws an ArithmeticException for the case that rounding is necessary, i.e.  0x00000007 
int  ROUND_UP  Rounding mode where positive values are rounded towards positive infinity and negative values towards negative infinity.  0x00000000 
BigDecimal  TEN  The constant ten as a BigDecimal.     
BigDecimal  ZERO  The constant zero as a BigDecimal.     

Public Constructors

          BigDecimal(char[] in, int offset, int len)
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 BigDecimal.
        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 unscaledVal.
      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.
Methods inherited from class java.lang.Number
Methods inherited from class java.lang.Object
Methods inherited from interface java.lang.Comparable

Details

Constants

public static final BigDecimal ONE

The constant one as a BigDecimal.

public static final int ROUND_CEILING

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

See Also

Constant Value: 2 (0x00000002)

public static final int ROUND_DOWN

Rounding mode where the values are rounded towards zero.

See Also

Constant Value: 1 (0x00000001)

public static final int ROUND_FLOOR

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

See Also

Constant Value: 3 (0x00000003)

public static final int ROUND_HALF_DOWN

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

See Also

Constant Value: 5 (0x00000005)

public static final int ROUND_HALF_EVEN

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

See Also

Constant Value: 6 (0x00000006)

public static final int ROUND_HALF_UP

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

See Also

Constant Value: 4 (0x00000004)

public static final int ROUND_UNNECESSARY

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

See Also

Constant Value: 7 (0x00000007)

public static final int ROUND_UP

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

See Also

Constant Value: 0 (0x00000000)

public static final BigDecimal TEN

The constant ten as a BigDecimal.

public static final BigDecimal ZERO

The constant zero as a BigDecimal.

Public Constructors

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

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

Parameters

in array of characters containing the string representation of this BigDecimal
offset first index to be copied
len number of characters to be used

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 scale is out of range
NumberFormatException if in does not contain a valid string representation of a big decimal.

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

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

Parameters

in array of characters containing the string representation of this BigDecimal
offset first index to be copied
len number of characters to be used
mc rounding mode and precision for the result of this operation.

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 scale is out of range
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)

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 scale is out of range
NumberFormatException if in does not contain a valid string representation of a big decimal.

public BigDecimal(char[] in, MathContext mc)

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

Parameters

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

Throws

NullPointerException if in == null
NumberFormatException if scale is out of range
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)

Constructs a new BigDecimal instance from a string representation.

Parameters

val string containing the string representation of this BigDecimal.

Throws

NumberFormatException if scale is out of range
NumberFormatException if val does not contain a valid string representation of a big decimal.

public 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 containing the string representation of this BigDecimal.
mc rounding mode and precision for the result of this operation.

Throws

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

public BigDecimal(double val)

Constructs a new BigDecimal instance from the 64bit double val. The constructed big decimal is equivalent to the double. For example, new BigDecimal(0.1) is equal to 0.1000000000000000055511151231257827021181583404541015625. This happens as 0.1 cannot be represented exactly in binary. To generate a big decimal instance which is equivalent to 0.1 use the BigDecimal(String) constructor.

Parameters

val double value to be converted to a BigDecimal instance.

Throws

NumberFormatException if val is infinity or not a number.

public BigDecimal(double val, MathContext mc)

Constructs a new BigDecimal instance from the 64bit double val. The constructed big decimal is equivalent to the double. For example, new BigDecimal(0.1) is equal to 0.1000000000000000055511151231257827021181583404541015625. This happens as 0.1 cannot be represented exactly in binary. To generate a big decimal instance which is equivalent to 0.1 use the BigDecimal(String) constructor.

Parameters

val double value to be converted to a BigDecimal instance.
mc rounding mode and precision for the result of this operation.

Throws

NumberFormatException if val is infinity or not a number.
ArithmeticException if mc.precision > 0 and mc.roundingMode == UNNECESSARY and the new big decimal cannot be represented within the given precision without rounding.

public BigDecimal(BigInteger val)

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

Parameters

val BigInteger value to be converted to a BigDecimal instance.

public 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 value to be converted to a BigDecimal instance.
mc rounding mode and precision for the result of this operation.

Throws

ArithmeticException if mc.precision > 0 and mc.roundingMode == UNNECESSARY and the new big decimal cannot be represented within the given precision without rounding.

public BigDecimal(BigInteger unscaledVal, int scale)

Constructs a new BigDecimal instance from a given unscaled value unscaledVal and a given scale. The value of this instance is unscaledVal * 10^{-scale}.

Parameters

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

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

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

Parameters

unscaledVal BigInteger representing the unscaled value of this BigDecimal instance.
scale scale of this BigDecimal instance.
mc rounding mode and precision for the result of this operation.

Throws

ArithmeticException if mc.precision > 0 and mc.roundingMode == UNNECESSARY and the new big decimal cannot be represented within the given precision without rounding.

public BigDecimal(int val)

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

Parameters

val int value to be converted to a BigDecimal instance.

public BigDecimal(int val, MathContext mc)

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

Parameters

val int value to be converted to a BigDecimal instance.
mc rounding mode and precision for the result of this operation.

Throws

ArithmeticException if mc.precision > 0 and mc.roundingMode == UNNECESSARY and the new big decimal cannot be represented within the given precision without rounding.

public BigDecimal(long val)

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

Parameters

val long value to be converted to a BigDecimal instance.

public BigDecimal(long val, MathContext mc)

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

Parameters

val long value to be converted to a BigDecimal instance.
mc rounding mode and precision for the result of this operation.

Throws

ArithmeticException if mc.precision > 0 and mc.roundingMode == UNNECESSARY and the new big decimal cannot be represented within the given precision without rounding.

Public Methods

public BigDecimal abs()

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)

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)

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)

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

public byte byteValueExact()

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

Returns

  • this BigDecimal as a byte value.

Throws

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

public int compareTo(BigDecimal val)

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

Parameters

val value to be compared with this.

Returns

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

Throws

NullPointerException if val == null

public 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 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.UNNECESSARY and rounding is necessary according to the given scale and given precision.

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