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
| |
| |
| |