BigDecimal

<p>In general the rounding modes and precision setting determine how operations return results with a limited number of digits when the exact result has more digits (perhaps infinitely many in the case of division and square root) than the number of digits returned.

First, the total number of digits to return is specified by the {@code MathContext}'s {@code precision} setting; this determines the result's <i>precision</i>. The digit count starts from the leftmost nonzero digit of the exact result. The rounding mode determines how any discarded trailing digits affect the returned result.

<p>For all arithmetic operators , the operation is carried out as though an exact intermediate result were first calculated and then rounded to the number of digits specified by the precision setting (if necessary), using the selected rounding mode. If the exact result is not returned, some digit positions of the exact result are discarded. When rounding increases the magnitude of the returned result, it is possible for a new digit position to be created by a carry propagating to a leading {@literal "9"} digit. For example, rounding the value 999.9 to three digits rounding up would be numerically equal to one thousand, represented as 100&times;10!(sup)1</sup>. In such cases, the new {@literal "1"} is the leading digit position of the returned result.

<p>Besides a logical exact result, each arithmetic operation has a preferred scale for representing a result. The preferred scale for each operation is listed in the table below.

<table class="striped" style="text-align:left"> <caption>Preferred Scales for Results of Arithmetic Operations </caption> <thead> <tr><th scope="col">Operation</th><th scope="col">Preferred Scale of Result</th></tr> </thead> <tbody> <tr><th scope="row">Add</th><td>max(addend.scale(), augend.scale())</td> <tr><th scope="row">Subtract</th><td>max(minuend.scale(), subtrahend.scale())</td> <tr><th scope="row">Multiply</th><td>multiplier.scale() + multiplicand.scale()</td> <tr><th scope="row">Divide</th><td>dividend.scale() - divisor.scale()</td> <tr><th scope="row">Square root</th><td>radicand.scale()/2</td> </tbody> </table>

These scales are the ones used by the methods which return exact arithmetic results; except that an exact divide may have to use a larger scale since the exact result may have more digits. For example, {@code 1/32} is {@code 0.03125}.

<p>Before rounding, the scale of the logical exact intermediate result is the preferred scale for that operation. If the exact numerical result cannot be represented in {@code precision} digits, rounding selects the set of digits to return and the scale of the result is reduced from the scale of the intermediate result to the least scale which can represent the {@code precision} digits actually returned. If the exact result can be represented with at most {@code precision} digits, the representation of the result with the scale closest to the preferred scale is returned. In particular, an exactly representable quotient may be represented in fewer than {@code precision} digits by removing trailing zeros and decreasing the scale. For example, rounding to three digits using the {@linkplain RoundingMode#FLOOR floor} rounding mode, <br>

{@code 19/100 = 0.19 // integer=19, scale=2} <br>

but!(br)

{@code 21/110 = 0.190 // integer=190, scale=3} <br>

<p>Note that for add, subtract, and multiply, the reduction in scale will equal the number of digit positions of the exact result which are discarded. If the rounding causes a carry propagation to create a new high-order digit position, an additional digit of the result is discarded than when no new digit position is created.

<p>Other methods may have slightly different rounding semantics. For example, the result of the {@code pow} method using the {@linkplain #pow(int, MathContext) specified algorithm} can occasionally differ from the rounded mathematical result by more than one unit in the last place, one <i>{@linkplain #ulp() ulp}</i>.

<p>Two types of operations are provided for manipulating the scale of a {@code BigDecimal}: scaling/rounding operations and decimal point motion operations. Scaling/rounding operations ({@link #setScale setScale} and {@link #round round}) return a {@code BigDecimal} whose value is approximately (or exactly) equal to that of the operand, but whose scale or precision is the specified value; that is, they increase or decrease the precision of the stored number with minimal effect on its value. Decimal point motion operations ({@link #movePointLeft movePointLeft} and {@link #movePointRight movePointRight}) return a {@code BigDecimal} created from the operand by moving the decimal point a specified distance in the specified direction.

<p>For the sake of brevity and clarity, pseudo-code is used throughout the descriptions of {@code BigDecimal} methods. The pseudo-code expression {@code (i + j)} is shorthand for "a {@code BigDecimal} whose value is that of the {@code BigDecimal} {@code i} added to that of the {@code BigDecimal} {@code j}." The pseudo-code expression {@code (i == j)} is shorthand for "{@code true} if and only if the {@code BigDecimal} {@code i} represents the same value as the {@code BigDecimal} {@code j}." Other pseudo-code expressions are interpreted similarly. Square brackets are used to represent the particular {@code BigInteger} and scale pair defining a {@code BigDecimal} value; for example [19, 2] is the {@code BigDecimal} numerically equal to 0.19 having a scale of 2.

<p>All methods and constructors for this class throw {@code NullPointerException} when passed a {@code null} object reference for any input parameter.

@apiNote Care should be exercised if {@code BigDecimal} objects are used as keys in a {@link java.util.SortedMap SortedMap} or elements in a {@link java.util.SortedSet SortedSet} since {@code BigDecimal}'s <i>natural ordering</i> is <em>inconsistent with equals</em>. See {@link Comparable}, {@link java.util.SortedMap} or {@link java.util.SortedSet} for more information.

@see BigInteger @see MathContext @see RoundingMode @see java.util.SortedMap @see java.util.SortedSet @author Josh Bloch @author Mike Cowlishaw @author Joseph D. Darcy @author Sergey V. Kuksenko