Operations on BigDecimal numbers are controlled by a {@link MathContext} object, which provides the context (precision andother information) for the operation. Methods that can take a MathContext parameter implement the standard arithmetic operators for BigDecimal objects and are known as operator methods. The default settings provided by the constant {@link MathContext#DEFAULT} (digits=9,form=SCIENTIFIC, lostDigits=false, roundingMode=ROUND_HALF_UP) perform general-purpose floating point arithmetic to nine digits of precision. The MathContext parameter must not be null.
Each operator method also has a version provided which does not take a MathContext parameter. For this version of each method, the context settings used are digits=0, form=PLAIN, lostDigits=false, roundingMode=ROUND_HALF_UP; these settings perform fixed point arithmetic with unlimited precision, as defined for the original BigDecimal class in Java 1.1 and Java 1.2.
For monadic operators, only the optional MathContext parameter is present; the operation acts upon the current object.
For dyadic operators, a BigDecimal parameter is always present; it must not be null. The operation acts with the current object being the left-hand operand and the BigDecimal parameter being the right-hand operand.
For example, adding two BigDecimal objects referred to by the names award and extra could be written as any of:
award.add(extra)
award.add(extra, MathContext.DEFAULT)
award.add(extra, acontext)
(where acontext is a MathContext object), which would return a BigDecimal object whose value is the result of adding award and extra under the appropriate context settings.
When a BigDecimal operator method is used, a set of rules define what the result will be (and, by implication, how the result would be represented as a character string). These rules are defined in the BigDecimal arithmetic documentation (see the URL above), but in summary:
MathContext parameter for an operation were MathContext.DEFAULT then the result would be rounded to 9 digits; the division of 2 by 3 would then result in 0.666666667. MathContext object. This lets you calculate using as many digits as you need -- thousands, if necessary. Fixed point (scaled) arithmetic is indicated by using a digits setting of 0 (or omitting the MathContext parameter). form setting is not PLAIN), a zero result is always expressed as the single digit '0' (that is, with no sign, decimal point, or exponent part). new BigDecimal("2.40").add( new BigDecimal("2")) => "4.40"
new BigDecimal("2.40").subtract(new BigDecimal("2")) => "0.40"
new BigDecimal("2.40").multiply(new BigDecimal("2")) => "4.80"
new BigDecimal("2.40").divide( new BigDecimal("2"), def) => "1.2"
where the value on the right of the => would be the result of the operation, expressed as a String, and def (in this and following examples) refers to MathContext.DEFAULT). This preservation of trailing zeros is desirable for most calculations (including financial calculations). If necessary, trailing zeros may be easily removed using division by 1.
digits (the default is 9 digits). If the number of places needed before the decimal point exceeds the digits setting, or the absolute value of the number is less than 0.000001, then the number will be expressed in exponential notation; thus new BigDecimal("1e+6").multiply(new BigDecimal("1e+6"), def)
results in 1E+12 instead of 1000000000000, and
new BigDecimal("1").divide(new BigDecimal("3E+10"), def)
results in 3.33333333E-11 instead of 0.0000000000333333333.
The form of the exponential notation (scientific or engineering) is determined by the The names of methods in this class follow the conventions established by form setting. java.lang.Number, java.math.BigInteger, and java.math.BigDecimal in Java 1.1 and Java 1.2.
@see MathContext
@author Mike Cowlishaw
@stable ICU 2.0
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.
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} canoccasionally differ from the rounded mathematical result by more than one unit in the last place, one {@linkplain #ulp() ulp}.
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) equalto 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 decimalpoint a specified distance in the specified direction.
For the sake of brevity and clarity, pseudo-code is used throughout the descriptions of {@code BigDecimal} methods. Thepseudo-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)} isshorthand 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.
Note: care should be exercised if {@code BigDecimal} objectsare used as keys in a {@link java.util.SortedMap SortedMap} orelements in a {@link java.util.SortedSet SortedSet} since{@code BigDecimal}'s natural ordering is inconsistent with equals. See {@link Comparable}, {@link java.util.SortedMap} or {@link java.util.SortedSet} for moreinformation.
All methods and constructors for this class throw {@code NullPointerException} when passed a {@code null} objectreference for any input parameter. @see BigInteger @see MathContext @see RoundingMode @see java.util.SortedMap @see java.util.SortedSet @author Josh Bloch @author Mike Cowlishaw @author Joseph D. Darcy
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |