Operator methods

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)

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:

• Results are normally calculated with up to some maximum number of significant digits. For example, if the 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.
  You can change the default of 9 significant digits by providing the method with a suitable 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).
  Similarly, you can change the algorithm used for rounding from the default 'classic' algorithm.
• In standard arithmetic (that is, when the 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).
• Except for the division and power operators in standard arithmetic, trailing zeros are preserved (this is in contrast to binary floating point operations and most electronic calculators, which lose the information about trailing zeros in the fractional part of results).
  So, for example:

    '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).
  If necessary, trailing zeros may be easily removed using division by 1.
• In standard arithmetic, exponential form is used for a result depending on its value and the current setting of 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

    '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 form of the exponential notation (scientific or engineering) is determined by the form setting.

The descriptions of the operator methods follow.

abs([MathContext])

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.

add(BigDecimal[, MathContext])

Implements the addition (+) operator, and returns the result as a BigDecimal object.

compareTo(BigDecimal[, MathContext])

Implements comparison, using numeric comparison, and returns a result of type int. The result will be:

-1

if the current object is less than the first parameter

 0

if the current object is equal to the first parameter

 1

if the current object is greater than the first parameter.

A compareTo(Object) method is also provided.

divide(BigDecimal[, MathContext])

Implements the division (/) operator, and returns the result as a BigDecimal object.

divide(BigDecimal, int)

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.

divide(BigDecimal, int, int)

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.

divideInteger(BigDecimal[, MathContext])

Implements the integer division operator, and returns the result as a BigDecimal object.

max(BigDecimal[, MathContext])

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.

min(BigDecimal[, MathContext])

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.

multiply(BigDecimal[, MathContext])

Implements the multiply (*) operator, and returns the result as a BigDecimal object.

negate([MathContext])

Implements the negation (Prefix -) operator, and returns the result as a BigDecimal object.

plus([MathContext])

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.

pow(BigDecimal[, MathContext])

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] 

remainder(BigDecimal[, MathContext])

Implements the remainder operator, and returns the result as a BigDecimal object. (This is not the modulo operator -- the result may be negative.)

subtract(BigDecimal[, MathContext])

Implements the subtract (-) operator, and returns the result as a BigDecimal object.