Decimal arithmetic
Copyright (c) IBM Corporation, 2000. All rights reserved. © | 11 Jan 2000 |
[previous | contents | next] |
Each of the methods here[1] takes a MathContext object as a parameter, which must not be null but which is optional in that a version of each of the methods is provided which does not require the MathContext parameter. This is indicated below by square brackets in the method prototypes.
The MathContext parameter provides the numeric settings for the operation (precision, and so on). If the parameter is omitted, then the settings used are "digits=0 form=PLAIN lostDigits=0 roundingMode=ROUND_HALF_UP".[2] If MathContext.DEFAULT is provided for the parameter then the default values of the settings are used ("digits=9 form=SCIENTIFIC lostDigits=0 roundingMode=ROUND_HALF_UP").
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 Decimal arithmetic section, but in summary:
'2.40'.add('2') => '4.40' '2.40'.subtract('2') => '0.40' '2.40'.multiply('2') => '4.80' '2.40'.divide('2', MathContext.DEFAULT) => '1.2'This preservation of trailing zeros is desirable for most calculations (including financial calculations).
'1e+6'.multiply('1e+6', MathContext.DEFAULT)results in '1E+12' instead of '1000000000000', and
'1'.divide('3E+10', MathContext.DEFAULT)results in '3.33333333E-11' instead of '0.0000000000333333333'.
The descriptions of the operator methods follow.
Returns the absolute value of the BigDecimal number. If the current object is zero or positive, then the same result as invoking the plus method with the same parameter is returned. Otherwise, the same result as invoking the negate method with the same parameter is returned.
Implements the addition (+) operator, and returns the result as a BigDecimal object.
Implements comparison, using numeric comparison, and returns a result of type int. The result will be:
A compareTo(Object) method is also provided.
Implements the division (/) operator, and returns the result as a BigDecimal object.
Implements the division (/) operator using settings "0 plain 0 rounding_mode", where rounding_mode is the second parameter, and returns the result as a BigDecimal object.
The length of the decimal part (the scale) of the result will be the same as the scale of the current object, if the latter were formatted without exponential notation.
An IllegalArgumentException is thrown if rounding_mode is not a valid rounding mode.
Implements the division (/) operator using settings "0 plain 0 rounding_mode", where rounding_mode is the third parameter, and returns the result as a BigDecimal object.
The length of the decimal part (the scale) of the result is specified by the second parameter. An ArithmeticException is thrown if this parameter is negative.
An IllegalArgumentException is thrown if rounding_mode is not a valid rounding mode.
Implements the integer division operator, and returns the result as a BigDecimal object.
Returns the larger of the current object and the first parameter.
If calling the compareTo method with the same parameters would return 1 or 0, then the result of calling the plus method on the current object (using the same MathContext parameter) is returned. Otherwise, the result of calling the plus method on the first parameter object (using the same MathContext parameter) is returned.
Returns the smaller of the current object and the first parameter.
If calling the compareTo method with the same parameters would return -1 or 0, then the result of calling the plus method on the current object (using the same MathContext parameter) is returned. Otherwise, the result of calling the plus method on the first parameter object (using the same MathContext parameter) is returned.
Implements the multiply (*) operator, and returns the result as a BigDecimal object.
Implements the negation (Prefix -) operator, and returns the result as a BigDecimal object.
Implements the plus (Prefix +) operator, and returns the result as a BigDecimal object.
Note: This method is provided for symmetry with negate and also for tracing, etc. It is also useful for rounding or otherwise applying a context to a decimal value.
Implements the power operator, and returns the result as a BigDecimal object.
The first parameter is the power to which the current number will be raised; it must be in the range -999999999 through 999999999, and must have a decimal part of zero. If no MathContext parameter is specified (or its digits property is 0) the power must be zero or positive. If any of these conditions is not met, an ArithmeticException is thrown.[3]
Implements the remainder operator, and returns the result as a BigDecimal object. (This is not the modulo operator -- the result may be negative.)
Implements the subtract (-) operator, and returns the result as a BigDecimal object.
[1] | Except for two forms of the divide method, which are preserved from the original BigDecimal class. |
[2] | This performs fixed point arithmetic with unlimited precision, as defined for the original BigDecimal class in Java. |
[3] | Note that the range and decimal part restrictions may be removed in the future, so should not be relied upon to produce an exception. |