java.lang.Object

java.lang.Number

java.math.BigDecimal

All Implemented Interfaces:: Serializable, Comparable<BigDecimal>

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

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-scale. See unscaledValue() and scale.

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

See Also:: Serialized Form

Field Summary

Fields
Modifier and Type	Field	Description
`static BigDecimal`	`ONE`	The constant one as a `BigDecimal`.
`static int`	`ROUND_CEILING`	Rounding mode to round towards positive infinity.
`static int`	`ROUND_DOWN`	Rounding mode where the values are rounded towards zero.
`static int`	`ROUND_FLOOR`	Rounding mode to round towards negative infinity.
`static int`	`ROUND_HALF_DOWN`	Rounding mode where values are rounded towards the nearest neighbor.
`static int`	`ROUND_HALF_EVEN`	Rounding mode where values are rounded towards the nearest neighbor.
`static int`	`ROUND_HALF_UP`	Rounding mode where values are rounded towards the nearest neighbor.
`static int`	`ROUND_UNNECESSARY`	Rounding mode where the rounding operations throws an `ArithmeticException` for the case that rounding is necessary, i.e.
`static int`	`ROUND_UP`	Rounding mode where positive values are rounded towards positive infinity and negative values towards negative infinity.
`static BigDecimal`	`TEN`	The constant ten as a `BigDecimal`.
`static BigDecimal`	`ZERO`	The constant zero as a `BigDecimal`.

Constructor Summary

Constructors
Constructor	Description
`BigDecimal(char[] in)`	Constructs a new `BigDecimal` instance from a string representation given as a character array.
`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, MathContext mc)`	Constructs a new `BigDecimal` instance from a string representation given as a character array.
`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(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`.
`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(BigInteger val)`	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(BigInteger val, MathContext mc)`	Constructs a new `BigDecimal` instance from the given big integer `val`.

Method Summary

Modifier and Type	Method	Description
`BigDecimal`	`abs()`	Returns a `BigDecimal` whose value is the absolute value of `this`.
`BigDecimal`	`abs(MathContext mc)`	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)`	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`	`divide(BigDecimal divisor, int scale, 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, RoundingMode roundingMode)`	Returns a new `BigDecimal` whose value is `this / divisor`.
`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[]`	`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`	`divideToIntegralValue(BigDecimal divisor)`	Returns a new `BigDecimal` whose value is the integral part of `this / divisor`.
`BigDecimal`	`divideToIntegralValue(BigDecimal divisor, MathContext mc)`	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³¹..2³¹-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⁶³..2⁶³-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)`	Returns a new `BigDecimal` whose value is `this * multiplicand`.
`BigDecimal`	`multiply(BigDecimal multiplicand, MathContext mc)`	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)`	Returns a new `BigDecimal` whose value is `this<sup>n</sup>`.
`BigDecimal`	`pow(int n, MathContext mc)`	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)`	Returns a new `BigDecimal` instance with the specified scale.
`BigDecimal`	`setScale(int newScale, int roundingMode)`	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 ([-2¹⁵..2¹⁵-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>`).

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details
- ROUND_UP
  
  public static final int ROUND_UP
  
  Rounding mode where positive values are rounded towards positive infinity and negative values towards negative infinity.
  
  See Also:
  
  RoundingMode.UP, Constant Field Values
- ROUND_DOWN
  
  public static final int ROUND_DOWN
  
  Rounding mode where the values are rounded towards zero.
  
  See Also:
  
  RoundingMode.DOWN, Constant Field Values
- ROUND_CEILING
  
  public static final 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:
  
  RoundingMode.CEILING, Constant Field Values
- ROUND_FLOOR
  
  public static final 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:
  
  RoundingMode.FLOOR, Constant Field Values
- ROUND_HALF_UP
  
  public static final int ROUND_HALF_UP
  
  Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding up.
  
  See Also:
  
  RoundingMode.HALF_UP, Constant Field Values
- ROUND_HALF_DOWN
  
  public static final int ROUND_HALF_DOWN
  
  Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding down.
  
  See Also:
  
  RoundingMode.HALF_DOWN, Constant Field Values
- ROUND_HALF_EVEN
  
  public static final 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:
  
  RoundingMode.HALF_EVEN, Constant Field Values
- ROUND_UNNECESSARY
  
  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:
  
  RoundingMode.UNNECESSARY, Constant Field Values
- ZERO
  
  public static final BigDecimal ZERO
  
  The constant zero as a BigDecimal.
- ONE
  
  public static final BigDecimal ONE
  
  The constant one as a BigDecimal.
- TEN
  
  public static final BigDecimal TEN
  
  The constant ten as a BigDecimal.
Constructor Details
- BigDecimal
 
 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:
 
 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
 
 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:
 
 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
 
 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:
 
 NumberFormatException - if in does not contain a valid string representation of a big decimal.
- BigDecimal
 
 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:
 
 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
 
 public BigDecimal(String val)
 
 Constructs a new BigDecimal instance from a string representation.
 
 Throws:
 
 NumberFormatException - if val does not contain a valid string representation of a big decimal.
- BigDecimal
 
 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:
 
 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.
- BigDecimal
 
 public 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 value to be converted to a BigDecimal instance.
 
 Throws:
 
 NumberFormatException - if val is infinity or not a number.
- BigDecimal
 
 public 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 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.
- BigDecimal
 
 public BigDecimal(BigInteger val)
 
 Constructs a new BigDecimal instance from the given big integer val. The scale of the result is 0.
- BigDecimal
 
 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:
 
 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.
- BigDecimal
 
 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).
 
 Throws:
 
 NullPointerException - if unscaledVal == null.
- BigDecimal
 
 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 {@code unscaledVal * 10^-scale). The result is rounded according to the specified math context. @param mc rounding mode and precision for the result of this operation. @throws ArithmeticException if {@code mc.precision > 0} and {@code mc.roundingMode == UNNECESSARY} and the new big decimal cannot be represented within the given precision without rounding. @throws NullPointerException if {@code unscaledVal == null}.
- BigDecimal
 
 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.
- BigDecimal
 
 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 c.roundingMode == UNNECESSARY and the new big decimal cannot be represented within the given precision without rounding.
- BigDecimal
 
 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.
- BigDecimal
 
 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.
Method Details
- valueOf
 
 public static BigDecimal valueOf(long unscaledVal, int scale)
 
 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.
- valueOf
 
 public static 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 - value to be converted to a BigDecimal.
 
 Returns:
 
 BigDecimal instance with the value unscaledVal.
- valueOf
 
 public static 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 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
- add
 
 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.
- add
 
 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 or mc == null.
- subtract
 
 public 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 - value to be subtracted from this.
 
 Returns:
 
 this - subtrahend.
 
 Throws:
 
 NullPointerException - if subtrahend == null.
- subtract
 
 public 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 - 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.
- multiply
 
 public 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 - value to be multiplied with this.
 
 Returns:
 
 this * multiplicand.
 
 Throws:
 
 NullPointerException - if multiplicand == null.
- multiply
 
 public 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 - 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.
- divide
 
 public 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 - 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.
- divide
 
 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.
- divide
 
 public 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 - 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.
- divide
 
 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.
- divide
 
 public 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 - 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.
- divide
 
 public 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 - 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().
- divideToIntegralValue
 
 public 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 - value by which this is divided.
 
 Returns:
 
 integral part of this / divisor.
 
 Throws:
 
 NullPointerException - if divisor == null.
 
 ArithmeticException - if divisor == 0.
- divideToIntegralValue
 
 public 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 - 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.
- remainder
 
 public 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 - value by which this is divided.
 
 Returns:
 
 this % divisor.
 
 Throws:
 
 NullPointerException - if divisor == null.
 
 ArithmeticException - if divisor == 0.
- remainder
 
 public 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 - 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.
- divideAndRemainder
 
 public 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 - value by which this is divided.
 
 Returns:
 
 [this.divideToIntegralValue(divisor), this.remainder(divisor)].
 
 Throws:
 
 NullPointerException - if divisor == null.
 
 ArithmeticException - if divisor == 0.
 
 See Also:
 
 divideToIntegralValue(java.math.BigDecimal), remainder(java.math.BigDecimal)
- divideAndRemainder
 
 public 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 - 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.
 
 See Also:
 
 divideToIntegralValue(java.math.BigDecimal), remainder(java.math.BigDecimal)
- pow
 
 public BigDecimal pow(int n)
 
 Returns a new BigDecimal whose value is thisn. 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.
 
 Throws:
 
 ArithmeticException - if n < 0 or n > 999999999.
- pow
 
 public BigDecimal pow(int n, MathContext mc)
 
 Returns a new BigDecimal whose value is thisn. 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:
 
 mc - rounding mode and precision for the result of this operation.
 
 Throws:
 
 ArithmeticException - if n < 0 or n > 999999999.
- abs
 
 public 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.
- abs
 
 public 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.
- negate
 
 public 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:
 
 -this
- negate
 
 public 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 - rounding mode and precision for the result of this operation.
 
 Returns:
 
 -this
- plus
 
 public BigDecimal plus()
 
 Returns a new BigDecimal whose value is +this. The scale of the result is the same as the scale of this.
 
 Returns:
 
 this
- plus
 
 public BigDecimal plus(MathContext mc)
 
 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
- signum
 
 public int signum()
 
 Returns the sign of this BigDecimal.
 
 Returns:
 
 -1 if this < 0, 0 if this == 0, 1 if this > 0.
- scale
 
 public 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-scale. If the scale is negative, then this BigDecimal represents a big integer.
 
 Returns:
 
 the scale of this BigDecimal.
- precision
 
 public 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:
 
 the precision of this BigDecimal.
- unscaledValue
 
 public BigInteger unscaledValue()
 
 Returns the unscaled value (mantissa) of this BigDecimal instance as a BigInteger. The unscaled value can be computed as this * 10scale.
- round
 
 public 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 - 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.
- setScale
 
 public 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 - 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.
- setScale
 
 public 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 - 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.
- setScale
 
 public 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 - scale of the result returned.
 
 Returns:
 
 a new BigDecimal instance with the specified scale.
 
 Throws:
 
 ArithmeticException - if rounding would be necessary.
- movePointLeft
 
 public 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.
- movePointRight
 
 public 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.
- scaleByPowerOfTen
 
 public BigDecimal scaleByPowerOfTen(int n)
 
 Returns a new BigDecimal whose value is this * 10n. 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.
- stripTrailingZeros
 
 public 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:
 
 a new BigDecimal instance equivalent to this where the trailing zeros of the unscaled value have been removed.
- compareTo
 
 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.
 
 Specified by:
 
 compareTo in interface Comparable<BigDecimal>
 
 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.
- equals
 
 public 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.
 
 Overrides:
 
 equals in class Object
 
 Parameters:
 
 x - the object to compare this instance with.
 
 Returns:
 
 true if the specified object is equal to this Object; false otherwise.
 
 See Also:
 
 Object.hashCode()
- min
 
 public BigDecimal min(BigDecimal val)
 
 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.
- max
 
 public BigDecimal max(BigDecimal val)
 
 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.
- hashCode
 
 public int hashCode()
 
 Returns a hash code for this BigDecimal.
 
 Overrides:
 
 hashCode in class Object
 
 Returns:
 
 hash code for this.
 
 See Also:
 
 Object.equals(java.lang.Object)
- toString
 
 public 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.
 
 Overrides:
 
 toString in class Object
 
 Returns:
 
 a string representation of this in scientific notation if necessary.
- toEngineeringString
 
 public 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:
 
 a string representation of this in engineering notation if necessary.
- toPlainString
 
 public 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:
 
 a string representation of this without exponent part.
- toBigInteger
 
 public BigInteger toBigInteger()
 
 Returns this BigDecimal as a big integer instance. A fractional part is discarded.
 
 Returns:
 
 this BigDecimal as a big integer instance.
- toBigIntegerExact
 
 public 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:
 
 this BigDecimal as a big integer value.
 
 Throws:
 
 ArithmeticException - if rounding is necessary.
- longValue
 
 public 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 % 264 is returned.
 
 Specified by:
 
 longValue in class Number
 
 Returns:
 
 the primitive long value of this object.
- longValueExact
 
 public 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⁶³..2⁶³-1]). If these conditions are not met, an ArithmeticException is thrown.
 
 Throws:
 
 ArithmeticException - if rounding is necessary or the number doesn't fit in a long.
- intValue
 
 public 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 % 232 is returned.
 
 Specified by:
 
 intValue in class Number
 
 Returns:
 
 the primitive int value of this object.
- intValueExact
 
 public 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³¹..2³¹-1]). If these conditions are not met, an ArithmeticException is thrown.
 
 Throws:
 
 ArithmeticException - if rounding is necessary or the number doesn't fit in an int.
- shortValueExact
 
 public 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¹⁵..2¹⁵-1]). If these conditions are not met, an ArithmeticException is thrown.
 
 Throws:
 
 ArithmeticException - if rounding is necessary of the number doesn't fit in a short.
- byteValueExact
 
 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.
 
 Throws:
 
 ArithmeticException - if rounding is necessary or the number doesn't fit in a byte.
- floatValue
 
 public 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.
 
 Specified by:
 
 floatValue in class Number
 
 Returns:
 
 this BigDecimal as a float value.
- doubleValue
 
 public 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.
 
 Specified by:
 
 doubleValue in class Number
 
 Returns:
 
 this BigDecimal as a double value.
- ulp
 
 public 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:
 
 unit in the last place (ULP) of this BigDecimal instance.

Class BigDecimal

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Number

Methods inherited from class java.lang.Object

Field Details

ROUND_UP

ROUND_DOWN

ROUND_CEILING

ROUND_FLOOR

ROUND_HALF_UP

ROUND_HALF_DOWN

ROUND_HALF_EVEN

ROUND_UNNECESSARY

ZERO

ONE

TEN

Constructor Details

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

Method Details

valueOf

valueOf

valueOf

add

add

subtract

subtract

multiply

multiply

divide

divide

divide

divide

divide

divide

divideToIntegralValue

divideToIntegralValue

remainder

remainder

divideAndRemainder

divideAndRemainder

pow

pow

abs

abs

negate

negate

plus

plus

signum

scale

precision

unscaledValue

round

setScale

setScale

setScale

movePointLeft

movePointRight

scaleByPowerOfTen

stripTrailingZeros

compareTo

equals

min