Class BigDecimal

public static final BigDecimal ONE

The constant one as a BigDecimal with scale zero.

Since:

1.5

public static final int ROUND_CEILING

Field Value:

2

public static final int ROUND_DOWN

Field Value:

1

public static final int ROUND_FLOOR

Field Value:

3

public static final int ROUND_HALF_DOWN

Field Value:

5

public static final int ROUND_HALF_EVEN

Field Value:

6

public static final int ROUND_HALF_UP

Field Value:

4

public static final int ROUND_UNNECESSARY

Field Value:

7

public static final int ROUND_UP

Field Value:

0

public static final BigDecimal TEN

The constant ten as a BigDecimal with scale zero.

Since:

1.5

public static final BigDecimal ZERO

The constant zero as a BigDecimal with scale zero.

Since:

1.5

public BigDecimal(char[] in)

Constructs a BigDecimal from the given char array, accepting the same sequence of characters as the BigDecimal(String) constructor.

Parameters:

in - the char array

Throws:

NumberFormatException - if in is not a valid BigDecimal representation

Since:

1.5

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

Constructs a BigDecimal from a char subarray, accepting the same sequence of characters as the BigDecimal(String) constructor.

Parameters:

in - the char array

offset - the start of the subarray

len - the length of the subarray

Throws:

NumberFormatException - if in is not a valid BigDecimal representation.

Since:

1.5

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

Constructs a BigDecimal from the char subarray and rounding according to the MathContext.

Parameters:

in - the char array

offset - the start of the subarray

len - the length of the subarray

mc - the MathContext for rounding

Throws:

NumberFormatException - if the char subarray is not a valid BigDecimal representation

ArithmeticException - if the result is inexact but the rounding mode is RoundingMode.UNNECESSARY

Since:

1.5

public BigDecimal(char[] in,
                  MathContext mc)

Constructs a BigDecimal from the char array and rounding according to the MathContext.

Parameters:

in - the char array

mc - the MathContext

Throws:

NumberFormatException - if in is not a valid BigDecimal representation

ArithmeticException - if the result is inexact but the rounding mode is RoundingMode.UNNECESSARY

Since:

1.5

public BigDecimal(double num)
            throws NumberFormatException

public BigDecimal(double num,
                  MathContext mc)

Constructs a BigDecimal in the same way as BigDecimal(double) and then rounds according to the MathContext.

Parameters:

num - the double from which the initial BigDecimal is created

mc - the MathContext that specifies the rounding behaviour

Throws:

ArithmeticException - if the result is inexact but the rounding type is RoundingMode.UNNECESSARY

Since:

1.5

public BigDecimal(int val)

Constructs a new BigDecimal whose unscaled value is val and whose scale is zero.

Parameters:

val - the value of the new BigDecimal

Since:

1.5

public BigDecimal(int val,
                  MathContext mc)

Constructs a BigDecimal using the BigDecimal(int) constructor and then rounds according to the MathContext.

Parameters:

val - the value for the initial (unrounded) BigDecimal

mc - the MathContext specifying the rounding

Throws:

ArithmeticException - if the result is inexact but the rounding type is RoundingMode.UNNECESSARY

Since:

1.5

public BigDecimal(String num)
            throws NumberFormatException

public BigDecimal(String val,
                  MathContext mc)

Constructs a BigDecimal from the String val according to the same rules as the BigDecimal(String) constructor and then rounds according to the MathContext mc.

Parameters:

val - the String from which we construct the initial BigDecimal

mc - the MathContext that specifies the rounding

Throws:

ArithmeticException - if the result is inexact but the rounding type is RoundingMode.UNNECESSARY

Since:

1.5

public BigDecimal(BigInteger num)

Constructs a BigDecimal whose unscaled value is num and whose scale is zero.

Parameters:

num - the value of the new BigDecimal

public BigDecimal(BigInteger num,
                  int scale)

Constructs a BigDecimal whose unscaled value is num and whose scale is scale.

Parameters:

num -

scale -

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

Constructs a BigDecimal using the BigDecimal(BigInteger, int) constructor and then rounds according to the MathContext.

Parameters:

num - the unscaled value of the unrounded BigDecimal

scale - the scale of the unrounded BigDecimal

mc - the MathContext specifying the rounding

Throws:

ArithmeticException - if the result is inexact but the rounding type is RoundingMode.UNNECESSARY

Since:

1.5

public BigDecimal(BigInteger num,
                  MathContext mc)

Constructs a BigDecimal whose value is given by num rounded according to mc. Since num is already a BigInteger, the rounding refers only to the precision setting in mc, if mc.getPrecision() returns an int lower than the number of digits in num, then rounding is necessary.

Parameters:

num - the unscaledValue, before rounding

mc - the MathContext that specifies the precision

Throws:

ArithmeticException - if the result is inexact but the rounding type is RoundingMode.UNNECESSARY

Since:

1.5

public BigDecimal(long val)

Constructs a new BigDecimal whose unscaled value is val and whose scale is zero.

Parameters:

val - the value of the new BigDecimal

public BigDecimal(long val,
                  MathContext mc)

Constructs a BigDecimal from the long in the same way as BigDecimal(long) and then rounds according to the MathContext.

Parameters:

val - the long from which we create the initial BigDecimal

mc - the MathContext that specifies the rounding behaviour

Throws:

ArithmeticException - if the result is inexact but the rounding type is RoundingMode.UNNECESSARY

Since:

1.5

public BigDecimal abs()

public BigDecimal abs(MathContext mc)

Returns a BigDecimal whose value is the absolute value of this BigDecimal with rounding according to the given MathContext.

Parameters:

mc - the MathContext

Returns:

the new BigDecimal

public BigDecimal add(BigDecimal val)

public BigDecimal add(BigDecimal val,
                      MathContext mc)

Returns a BigDecimal whose value is found first by calling the method add(val) and then by rounding according to the MathContext mc.

Parameters:

val - the augend

mc - the MathContext for rounding

Returns:

this + val, rounded if need be

Throws:

ArithmeticException - if the value is inexact but the rounding is RoundingMode.UNNECESSARY

Since:

1.5

public byte byteValueExact()

Converts this BigDecimal into a byte by first calling longValueExact and then checking that the long returned from that method fits into a byte.

Returns:

a byte whose value is this

Throws:

ArithmeticException - if this BigDecimal has a fractional part or is too large to fit into a byte.

Since:

1.5

public int compareTo(BigDecimal val)

public BigDecimal divide(BigDecimal divisor)
            throws ArithmeticException,
                   IllegalArgumentException

Performs division, if the resulting quotient requires rounding (has a nonterminating decimal expansion), an ArithmeticException is thrown. #see divide(BigDecimal, int, int)

Since:

1.5

public BigDecimal divide(BigDecimal val,
                         int roundingMode)
            throws ArithmeticException,
                   IllegalArgumentException

public BigDecimal divide(BigDecimal val,
                         int newScale,
                         int roundingMode)
            throws ArithmeticException,
                   IllegalArgumentException

public BigDecimal divide(BigDecimal val,
                         int scale,
                         RoundingMode roundingMode)

Returns a BigDecimal whose value is (this / val), with the specified scale and rounding according to the RoundingMode

Parameters:

val - the divisor

scale - the scale of the BigDecimal returned

roundingMode - the rounding mode to use

Returns:

a BigDecimal whose value is approximately (this / val)

Throws:

ArithmeticException - if divisor is zero or the rounding mode is UNNECESSARY but the specified scale cannot represent the value exactly

Since:

1.5

public BigDecimal divide(BigDecimal val,
                         RoundingMode roundingMode)

Returns a BigDecimal whose value is (this / val) rounded according to the RoundingMode

Parameters:

val - the divisor

roundingMode - the rounding mode to use

Returns:

a BigDecimal whose value is approximately (this / val)

Throws:

ArithmeticException - if divisor is zero or the rounding mode is UNNECESSARY but the specified scale cannot represent the value exactly

public BigDecimal[] divideAndRemainder(BigDecimal val)

Returns a BigDecimal array, the first element of which is the integer part of this / val, and the second element of which is the remainder of that quotient.

Parameters:

val - the divisor

Returns:

the above described BigDecimal array

Throws:

ArithmeticException - if val == 0

Since:

1.5

public BigDecimal divideToIntegralValue(BigDecimal val)

Returns a BigDecimal whose value is the integer part of the quotient this / val. The preferred scale is this.scale - val.scale.

Parameters:

val - the divisor

Returns:

a BigDecimal whose value is the integer part of this / val.

Throws:

ArithmeticException - if val == 0

Since:

1.5

public double doubleValue()

Return the value of this Number as a float.

Overrides:

doubleValue in interface Number

Returns:

the double value

public boolean equals(Object o)

Determine whether this Object is semantically equal to another Object.

There are some fairly strict requirements on this method which subclasses must follow:

• It must be transitive. If a.equals(b) and b.equals(c), then a.equals(c) must be true as well.
• It must be symmetric. a.equals(b) and b.equals(a) must have the same value.
• It must be reflexive. a.equals(a) must always be true.
• It must be consistent. Whichever value a.equals(b) returns on the first invocation must be the value returned on all later invocations.
• a.equals(null) must be false.
• It must be consistent with hashCode(). That is, a.equals(b) must imply a.hashCode() == b.hashCode(). The reverse is not true; two objects that are not equal may have the same hashcode, but that has the potential to harm hashing performance.

This is typically overridden to throw a ClassCastException if the argument is not comparable to the class performing the comparison, but that is not a requirement. It is legal for a.equals(b) to be true even though a.getClass() != b.getClass(). Also, it is typical to never cause a NullPointerException.

In general, the Collections API (java.util) use the equals method rather than the == operator to compare objects. However, IdentityHashMap is an exception to this rule, for its own good reasons.

The default implementation returns this == o.

Overrides:

equals in interface Object

Parameters:

Returns:

whether this Object is semantically equal to another

See Also:

Object.hashCode()

public float floatValue()

Return the value of this Number as a float.

Overrides:

floatValue in interface Number

Returns:

the float value

public int hashCode()

Get a value that represents this Object, as uniquely as possible within the confines of an int.

There are some requirements on this method which subclasses must follow:

• Semantic equality implies identical hashcodes. In other words, if a.equals(b) is true, then a.hashCode() == b.hashCode() must be as well. However, the reverse is not necessarily true, and two objects may have the same hashcode without being equal.
• It must be consistent. Whichever value o.hashCode() returns on the first invocation must be the value returned on all later invocations as long as the object exists. Notice, however, that the result of hashCode may change between separate executions of a Virtual Machine, because it is not invoked on the same object.

Notice that since hashCode is used in Hashtable and other hashing classes, a poor implementation will degrade the performance of hashing (so don't blindly implement it as returning a constant!). Also, if calculating the hash is time-consuming, a class may consider caching the results.

The default implementation returns System.identityHashCode(this)

Overrides:

hashCode in interface Object

Returns:

the hash code for this Object

See Also:

Object.equals(Object), System.identityHashCode(Object)

public int intValue()

Return the value of this Number as an int.

Overrides:

intValue in interface Number

Returns:

the int value

public int intValueExact()

Converts this BigDecimal into an int by first calling longValueExact and then checking that the long returned from that method fits into an int.

Returns:

an int whose value is this

Throws:

ArithmeticException - if this BigDecimal has a fractional part or is too large to fit into an int.

Since:

1.5

public long longValue()

Return the value of this Number as a long.

Overrides:

longValue in interface Number

Returns:

the long value

public long longValueExact()

Converts this BigDecimal to a long value.

Returns:

the long value

Throws:

ArithmeticException - if rounding occurs or if overflow occurs

Since:

1.5

public BigDecimal max(BigDecimal val)

public BigDecimal min(BigDecimal val)

public BigDecimal movePointLeft(int n)

public BigDecimal movePointRight(int n)

public BigDecimal multiply(BigDecimal val)

public BigDecimal multiply(BigDecimal val,
                           MathContext mc)

Returns a BigDecimal whose value is (this x val) before it is rounded according to the MathContext mc.

Parameters:

val - the multiplicand

mc - the MathContext for rounding

Returns:

a new BigDecimal with value approximately (this x val)

Throws:

ArithmeticException - if the value is inexact but the rounding mode is RoundingMode.UNNECESSARY

Since:

1.5

public BigDecimal negate()

public BigDecimal negate(MathContext mc)

Returns a BigDecimal whose value is found first by negating this via the negate() method, then by rounding according to the MathContext mc.

Parameters:

mc - the MathContext for rounding

Returns:

a BigDecimal whose value is approximately (-this)

Throws:

ArithmeticException - if the value is inexact but the rounding mode is RoundingMode.UNNECESSARY

Since:

1.5

public BigDecimal plus()

Returns this BigDecimal. This is included for symmetry with the method negate().

Returns:

this

Since:

1.5

public BigDecimal plus(MathContext mc)

Returns a BigDecimal whose value is found by rounding this according to the MathContext. This is the same as round(MathContext).

Parameters:

mc - the MathContext for rounding

Returns:

a BigDecimal whose value is this before being rounded

Throws:

ArithmeticException - if the value is inexact but the rounding mode is RoundingMode.UNNECESSARY

Since:

1.5

public BigDecimal pow(int n)

Returns a BigDecimal whose value is this to the power of n.

Parameters:

n - the power

Returns:

the new BigDecimal

Since:

1.5

public BigDecimal pow(int n,
                      MathContext mc)

Returns a BigDecimal whose value is determined by first calling pow(n) and then by rounding according to the MathContext mc.

Parameters:

n - the power

mc - the MathContext

Returns:

the new BigDecimal

Throws:

ArithmeticException - if n <320 or n > 999999999 or if the result is inexact but the rounding is RoundingMode.UNNECESSARY

Since:

1.5

public int precision()

Returns the precision of this BigDecimal (the number of digits in the unscaled value). The precision of a zero value is 1.

Returns:

the number of digits in the unscaled value, or 1 if the value is zero.

public BigDecimal remainder(BigDecimal val)

Returns a BigDecimal whose value is the remainder in the quotient this / val. This is obtained by subtract(divideToIntegralValue(val).multiply(val)).

Parameters:

val - the divisor

Returns:

a BigDecimal whose value is the remainder

Throws:

ArithmeticException - if val == 0

Since:

1.5

public BigDecimal round(MathContext mc)

Returns a BigDecimal which is this BigDecimal rounded according to the MathContext rounding settings.

Parameters:

mc - the MathContext that tells us how to round

Returns:

the rounded BigDecimal

public int scale()

public BigDecimal scaleByPowerOfTen(int n)

Returns a BigDecimal whose numerical value is the numerical value of this BigDecimal multiplied by 10 to the power of n.

Parameters:

n - the power of ten

Returns:

the new BigDecimal

Since:

1.5

public BigDecimal setScale(int scale)
            throws ArithmeticException

public BigDecimal setScale(int scale,
                           int roundingMode)
            throws ArithmeticException,
                   IllegalArgumentException

public BigDecimal setScale(int newScale,
                           RoundingMode roundingMode)

Returns a BigDecimal whose value is the same as this BigDecimal but whose representation has a scale of newScale. If the scale is reduced then rounding may occur, according to the RoundingMode.

Parameters:

newScale -

roundingMode -

Returns:

a BigDecimal whose scale is as given, whose value is this with possible rounding

Throws:

ArithmeticException - if the rounding mode is UNNECESSARY but rounding is required

Since:

1.5

public short shortValueExact()

Converts this BigDecimal into a short by first calling longValueExact and then checking that the long returned from that method fits into a short.

Returns:

a short whose value is this

Throws:

ArithmeticException - if this BigDecimal has a fractional part or is too large to fit into a short.

Since:

1.5

public int signum()

public BigDecimal stripTrailingZeros()

Returns a BigDecimal which is numerically equal to this BigDecimal but with no trailing zeros in the representation. For example, if this BigDecimal has [unscaledValue, scale] = [6313000, 4] this method returns a BigDecimal with [unscaledValue, scale] = [6313, 1]. As another example, [12400, -2] would become [124, -4].

Returns:

a numerically equal BigDecimal with no trailing zeros

public BigDecimal subtract(BigDecimal val)

public BigDecimal subtract(BigDecimal val,
                           MathContext mc)

Returns a BigDecimal whose value is found first by calling the method subtract(val) and then by rounding according to the MathContext mc.

Parameters:

val - the subtrahend

mc - the MathContext for rounding

Returns:

this - val, rounded if need be

Throws:

ArithmeticException - if the value is inexact but the rounding is RoundingMode.UNNECESSARY

Since:

1.5

public BigInteger toBigInteger()

Converts this BigDecimal to a BigInteger. Any fractional part will be discarded.

Returns:

a BigDecimal whose value is equal to floor[this]

public BigInteger toBigIntegerExact()

Converts this BigDecimal into a BigInteger, throwing an ArithmeticException if the conversion is not exact.

Returns:

a BigInteger whose value is equal to the value of this BigDecimal

Since:

1.5

public String toEngineeringString()

Returns the String representation of this BigDecimal, using engineering notation if necessary. This is similar to toString() but when exponents are used the exponent is made to be a multiple of 3 such that the integer part is between 1 and 999.

Returns:

a String representation of this BigDecimal in engineering notation

Since:

1.5

public String toPlainString()

Returns a String representation of this BigDecimal without using scientific notation. This is how toString() worked for releases 1.4 and previous. Zeros may be added to the end of the String. For example, an unscaled value of 1234 and a scale of -3 would result in the String 1234000, but the toString() method would return 1.234E+6.

Returns:

a String representation of this BigDecimal

Since:

1.5

public String toString()

Returns the String representation of this BigDecimal, using scientific notation if necessary. The following steps are taken to generate the result: 1. the BigInteger unscaledValue's toString method is called and if scale == 0 is returned. 2. an int adjExp is created which is equal to the negation of scale plus the number of digits in the unscaled value, minus one. 3. if scale >= 0 && adjExp >= -6 then we represent this BigDecimal without scientific notation. A decimal is added if the scale is positive and zeros are prepended as necessary. 4. if scale is negative or adjExp is less than -6 we use scientific notation. If the unscaled value has more than one digit, a decimal as inserted after the first digit, the character 'E' is appended and adjExp is appended.

Overrides:

toString in interface Object

public BigDecimal ulp()

Returns the size of a unit in the last place of this BigDecimal. This returns a BigDecimal with [unscaledValue, scale] = [1, this.scale()].

Returns:

the size of a unit in the last place of this.

Since:

1.5

public BigInteger unscaledValue()

public static BigDecimal valueOf(double val)

Returns a new BigDecimal constructed from the BigDecimal(String) constructor using the Double.toString(double) method to obtain the String.

Parameters:

val - the double value used in Double.toString(double)

Returns:

a BigDecimal representation of val

Throws:

NumberFormatException - if val is NaN or infinite

Since:

1.5

public static BigDecimal valueOf(long val)

public static BigDecimal valueOf(long val,
                                 int scale)
            throws NumberFormatException