Fixed Point Decimal (BigDecimal) Methods

Some numeric objects in BPM are expressed in BigDecimal format.

BigDecimal format can cope with arbitrarily large numbers. However, it is necessary to specify what precision to use in certain circumstances. For example, calculating one-third would produce an exception if precision is not specified. BigDecimal supports three standard levels of precision:

  • static MathContext DECIMAL32: A MathContext object with a precision setting matching the IEEE 754R Decimal32 format, seven digits, a rounding mode of HALF_EVEN, and the IEEE 754R default (which is equivalent to "float" arithmetic).
  • static MathContext DECIMAL64: A MathContext object with a precision setting matching the IEEE 754R Decimal64 format, 16 digits, a rounding mode of HALF_EVEN, and the IEEE 754R default (which is equivalent to "double" arithmetic).
  • static MathContext DECIMAL128: A MathContext object with a precision setting matching the IEEE 754R Decimal128 format, 34 digits, a rounding mode of HALF_EVEN, and the IEEE 754R default.

In addition, when using the BigDecimal type, the rounding rules can be specified when a particular method of rounding is required for a particular type of calculation (for example, tax calculations). The type of rounding to be used by a BigDecimal operation can be specified when creating a MathContext, or passed directly to the relevant methods of BigDecimal. Possible values are:

  • CEILING
  • FLOOR
  • UP
  • DOWN
  • HALF_UP
  • HALF_DOWN
  • HALF_EVEN
  • UNNECESSARY

The following table lists the methods available for BigDecimal objects.

Type Method Notes
BigDecimal abs() Returns a BigDecimal whose value is the absolute value of this BigDecimal, and whose scale is this.scale().
BigDecimal add(BigDecimal augend) Returns a BigDecimal whose value is (this + augend), and whose scale is max(this.scale(), augend.scale()).
BigDecimal add(BigDecimal augend, MathContext mc) Returns a BigDecimal whose value is (this + augend), with rounding according to the context settings.
int compareTo(BigDecimal val) Compares this BigDecimal with the specified BigDecimal.
BigDecimal divide(BigDecimal divisor) Returns a BigDecimal whose value is (this / divisor), and whose preferred scale is (this.scale() - divisor.scale()). If the exact quotient cannot be represented (because it has a non-terminating decimal expansion), an ArithmeticException is thrown.
BigDecimal divide(BigDecimal divisor, int scale, RoundingMode roundingMode) Returns a BigDecimal whose value is (this / divisor), and whose scale is as specified.
BigDecimal divide(BigDecimal divisor, MathContext mc) Returns a BigDecimal whose value is (this / divisor), with rounding according to the context settings.
BigDecimal divide(BigDecimal divisor, RoundingMode roundingMode) Returns a BigDecimal whose value is (this / divisor), and whose scale is this.scale().
BigDecimal divideToIntegralValue(BigDecimal divisor) Returns a BigDecimal whose value is the integer part of the quotient (this / divisor) rounded down.
BigDecimal divideToIntegralValue(BigDecimal divisor, MathContext mc) Returns a BigDecimal whose value is the integer part of (this / divisor).
BigDecimal max(BigDecimal val) Returns the maximum of this BigDecimal and val.
BigDecimal min(BigDecimal val) Returns the minimum of this BigDecimal and val.
BigDecimal multiply(BigDecimal multiplicand) Returns a BigDecimal whose value is (this × multiplicand), and whose scale is (this.scale() + multiplicand.scale()).
BigDecimal multiply(BigDecimal multiplicand, MathContext mc) Returns a BigDecimal whose value is (this × multiplicand), with rounding according to the context settings.
BigDecimal negate() Returns a BigDecimal whose value is (-this), and whose scale is this.scale().
BigDecimal pow(int n) Returns a BigDecimal whose value is (thisn). The power is computed exactly, to unlimited precision.
BigDecimal pow(int n, MathContext mc) Returns a BigDecimal whose value is (thisn).
int precision() Returns the precision of this BigDecimal.
BigDecimal remainder(BigDecimal divisor) Returns a BigDecimal whose value is (this % divisor).
BigDecimal remainder(BigDecimal divisor, MathContext mc) Returns a BigDecimal whose value is (this % divisor), with rounding according to the context settings.
BigDecimal round(MathContext mc) Returns a BigDecimal rounded according to the MathContext settings.
int scale() Returns the scale of this BigDecimal.
BigDecimal scaleByPowerOfTen(int n) Returns a BigDecimal whose numerical value is equal to (this * 10n).
BigDecimal setScale(int newScale) Returns a BigDecimal whose scale is the specified value, and whose value is numerically equal to this BigDecimal's.
BigDecimal setScale(int newScale, RoundingMode roundingMode) Returns a BigDecimal whose scale is the specified value, and whose unscaled value is determined by multiplying or dividing this BigDecimal's unscaled value by the appropriate power of ten to maintain its overall value.
int signum() Returns the signum function of this BigDecimal.
BigDecimal stripTrailingZeros() Returns a BigDecimal that is numerically equal to this one, but with any trailing zeros removed from the representation.
BigDecimal subtract(BigDecimal subtrahend) Returns a BigDecimal whose value is (this - subtrahend), and whose scale is max(this.scale(), subtrahend.scale()).
BigDecimal subtract(BigDecimal subtrahend, MathContext mc) Returns a BigDecimal whose value is (this - subtrahend), with rounding according to the context settings.
String toEngineeringString() Returns a string representation of this BigDecimal, using engineering notation if an exponent is needed.
String toPlainString() Returns a string representation of this BigDecimal without an exponent field.
String toString() Returns the string representation of this BigDecimal, using scientific notation if an exponent is needed.
BigDecimal ulp() Returns the size of an ulp (a unit in the last place) of this BigDecimal.
BigInteger unscaledValue() Returns a BigInteger whose value is the unscaled value of this BigDecimal.