BigDecimal(int val)

Initialize the BigDecimal instance to val's digits. Set the scale to 0.

BigDecimal(String val)

BigDecimal abs()

Initialize the BigDecimal instance to the decimal equivalent of val. Set the scale to the number of digits after the decimal point, or 0 if no decimal point is specified. This constructor throws java.lang.NullPointerException when val is null, and java.lang.NumberFormatException when val's string representation is invalid (contains letters, for example).

Return a new BigDecimal instance that contains the absolute value of the current instance's value. The resulting scale is the same as the current instance's scale.

BigDecimal add(BigDecimal augend)

BigDecimal divide(BigDecimal divisor)

BigDecimal max(BigDecimal val)

Return a new BigDecimal instance that contains the sum of the current value and the argument value. The resulting scale is the maximum of the current and argument scales. This method throws NullPointerException when augend is null.

Return a new BigDecimal instance that contains the quotient of the current value divided by the argument value. The resulting scale is the difference of the current and argument scales. It might be adjusted when the result requires more digits. This method throws NullPointerException when divisor is null, or java.lang.ArithmeticException when divisor represents 0 or the result cannot be represented exactly.

Return either this or val, whichever BigDecimal instance contains the larger value. This method throws NullPointerException when val is null.

Method

Description

BigDecimal min(BigDecimal val)

Method

Description

BigDecimal min(BigDecimal val)

BigDecimal multiply(BigDecimal multiplicand)

BigDecimal negate()

Return either this or val, whichever BigDecimal instance contains the smaller value. This method throws NullPointerException when val is null.

Return a new BigDecimal instance that contains the product of the current value and the argument value. The resulting scale is the sum of the current and argument scales. This method throws NullPointerException when multiplicand is null.

Return a new BigDecimal instance that contains the negative of the current value. The resulting scale is the same as the current scale.

int precision()

BigDecimal remainder(BigDecimal divisor)

int scale()

BigDecimal setScale(int newScale, RoundingMode roundingMode)

BigDecimal subtract(BigDecimal subtrahend)

String toString()

Return the precision of the current BigDecimal instance.

Return a new BigDecimal instance that contains the remainder of the current value divided by the argument value. The resulting scale is the difference of the current scale and the argument scale. It might be adjusted when the result requires more digits. This method throws NullPointerException when divisor is null, or ArithmeticException when divisor represents 0.

Return the scale of the current BigDecimal instance.

Return a new BigDecimal instance with the specified scale and rounding mode. If the new scale is greater than the old scale, 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, trailing digits are removed. If these trailing digits are not zero, the remaining unscaled value has to be rounded. For this rounding operation, the specified rounding mode is used. This method throws NullPointerException when roundingMode is null, and ArithmeticException when roundingMode is set to RoundingMode.ROUND_UNNECESSARY but rounding is necessary based on the current scale.

Return a new BigDecimal instance that contains the current value minus the argument value. The resulting scale is the maximum of the current and argument scales. This method throws NullPointerException when subtrahend is null.

Return a string representation of this BigDecimal. Scientific notation is used when necessary.

Table 6-2 refers to RoundingMode, which is an enum containing various rounding mode constants. These constants are described in Table 6-3.

Constant |
Description |

CEILING |
Round toward positive infinity. |

DOWN |
Round toward zero. |

FLOOR |
Round toward negative infinity. |

HALF_DOWN |
Round toward the "nearest neighbor" unless both neighbors are equidistant, in which case round down. |

HALF_EVEN |
Round toward the "nearest neighbor" unless both neighbors are equidistant, in which case round toward the even neighbor. |

HALF_UP |
Round toward "nearest neighbor" unless both neighbors are equidistant, in which case round up. (This is the rounding mode commonly taught at school.) |

UNNECESSARY |
Rounding is not necessary because the requested operation produces the exact result. |

UP |
Positive values are rounded toward positive infinity and negative values are rounded toward negative infinity. |

The best way to get comfortable with BigDecimal is to try it out. Listing 6-4 uses this class to correctly perform the invoice calculations that were presented in Listing 6-3.

Listing 6-4. BigDecimal -based invoice calculations not leading to confusing results class InvoiceCalc {

public static void main(String[] args) {

BigDecimal invoiceSubtotal = new BigDecimal("285.36");

BigDecimal discountPercent = new BigDecimal("0.10");

BigDecimal discount = invoiceSubtotal.multiply(discountPercent);

discount = discount.setScale(2, RoundingMode.HALFJJP);

BigDecimal subtotalBeforeTax = invoiceSubtotal.subtract(discount);

subtotalBeforeTax = subtotalBeforeTax.setScale(2, RoundingMode.HALF_UP);

BigDecimal salesTaxPercent = new BigDecimal("0.05");

BigDecimal salesTax = subtotalBeforeTax.multiply(salesTaxPercent);

salesTax = salesTax.setScale(2, RoundingMode.HALF_UP);

BigDecimal invoiceTotal = subtotalBeforeTax.add(salesTax);

invoiceTotal = invoiceTotal.setScale(2, RoundingMode.HALFJJP);

System.out.println("Subtotal: " + invoiceSubtotal);

System.out.println("Discount: " + discount);

System.out.println("SubTotal after discount: " + subtotalBeforeTax); System.out.println("Sales Tax: " + salesTax); System.out.println("Total: " + invoiceTotal);

Listing 6-4's main() method first creates BigDecimal objects invoiceSubtotal and discountPercent that are initialized to 285.36 and 0.10, respectively. It multiplies invoiceSubtotal by discountPercent and assigns the BigDecimal result to discount.

At this point, discount contains 28.5360. Apart from the trailing zero, this value is the same as that generated by invoiceSubtotal*DISCOUNT_PERCENT in Listing 6-3. The value that should be stored in discount is 28.54. To correct this problem before performing another calculation, main() calls discount's setScale() method with these arguments:

■ 2: Two digits after the decimal point

■ RoundingMode.HALF_UP: The conventional approach to rounding

After setting the scale and proper rounding mode, main() subtracts discount from invoiceSubtotal, and assigns the resulting BigDecimal instance to subtotalBeforeTax. main() calls setScale() on subtotalBeforeTax to properly round its value before moving on to the next calculation.

main() next creates a BigDecimal object named salesTaxPercent that is initialized to 0.05. It then multiplies subtotalBeforeTax by salesTaxPercent, assigning the result to salesTax, and calls setScale() on this BigDecimal object to properly round its value.

Moving on, main() adds salesTax to subtotalBeforeTax, saving the result in invoiceTotal, and rounds the result via setScale(). The values in these objects are sent to the standard output device via System.out.println(), which calls their toString() methods to return string representations of the BigDecimal values.

When you run this new version of InvoiceCalc, you will discover the following output:

Subtotal: 285.36 Discount: 28.54

SubTotal after discount: 256.82 Sales Tax: 12.84 Total: 269.66

CAUTION: BigDecimal declares a public BigDecimal(double val) constructor that you should avoid using if at all possible. This constructor initializes the BigDecimal instance to the value stored in val, making it possible for this instance to reflect an invalid representation when the double cannot be stored exactly. For example, BigDecimal(0.1) results in 0.1000000000000000055511151231257827021181583404541015625 being stored in the instance. In contrast, BigDecimal("0.1") stores 0.1 exactly.

Was this article helpful?

## Post a comment