International Components for Unicode for Java (icu4j) 74.2 · com.ibm.icu.math.BigDecimal

The BigDecimal class implements immutable arbitrary-precision decimal numbers. The methods of the BigDecimal class provide operations for fixed and floating point arithmetic, comparison, format conversions, and hashing.

As the numbers are decimal, there is an exact correspondence between an instance of a BigDecimal object and its String representation; the BigDecimal class provides direct conversions to and from String and character array (char[]) objects, as well as conversions to and from the Java primitive types (which may not be exact) and BigInteger.

In the descriptions of constructors and methods in this documentation, the value of a BigDecimal number object is shown as the result of invoking the toString() method on the object. The internal representation of a decimal number is neither defined nor exposed, and is not permitted to affect the result of any operation.

The floating point arithmetic provided by this class is defined by the ANSI X3.274-1996 standard, and is also documented at http://www2.hursley.ibm.com/decimal
[This URL will change.]

Operator methods

Operations on BigDecimal numbers are controlled by a MathContext object, which provides the context (precision and other 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 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:

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:
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.
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
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 form setting.

The names of methods in this class follow the conventions established by java.lang.Number, java.math.BigInteger, and java.math.BigDecimal in Java 1.1 and Java 1.2.

Modifier and Type	Field and Description
private static byte[]	bytecar
private static byte[]	bytedig
private int	exp The exponent.
private byte	form The formatting style.
private byte	ind The indicator.
private static final byte	isneg
private static final byte	ispos
private static final byte	iszero
private byte[]	mant The value of the mantissa.
private static final int	MaxArg
private static final int	MaxExp
private static final int	MinArg
private static final int	MinExp
public static final BigDecimal	ONE The `BigDecimal` constant "1".
private static final MathContext	plainMC
public static final int	ROUND_CEILING Rounding mode to round to a more positive number.
public static final int	ROUND_DOWN Rounding mode to round towards zero.
public static final int	ROUND_FLOOR Rounding mode to round to a more negative number.
public static final int	ROUND_HALF_DOWN Rounding mode to round to nearest neighbor, where an equidistant value is rounded down.
public static final int	ROUND_HALF_EVEN Rounding mode to round to nearest neighbor, where an equidistant value is rounded to the nearest even neighbor.
public static final int	ROUND_HALF_UP Rounding mode to round to nearest neighbor, where an equidistant value is rounded up.
public static final int	ROUND_UNNECESSARY Rounding mode to assert that no rounding is necessary.
public static final int	ROUND_UP Rounding mode to round away from zero.
private static final long	serialVersionUID Hides java.lang.Number.serialVersionUID.
public static final BigDecimal	TEN The `BigDecimal` constant "10".
public static final BigDecimal	ZERO The `BigDecimal` constant "0".

Access	Constructor and Description
public	BigDecimal(BigDecimal The `BigDecimal` to be translated. bd) Constructs a `BigDecimal` object from a `java.math.BigDecimal`.
public	BigDecimal(BigInteger The `BigInteger` to be converted. bi) Constructs a `BigDecimal` object from a `BigInteger`, with scale 0.
public	BigDecimal(BigInteger The `BigInteger` to be converted. bi, int The `int` specifying the scale. scale) Constructs a `BigDecimal` object from a `BigInteger` and a scale.
public	BigDecimal(char[] The `char[]` array containing the number to be converted. inchars) Constructs a `BigDecimal` object from an array of characters.
public	BigDecimal(char[] The `char[]` array containing the number to be converted. inchars, int The `int` offset into the array of the start of the number to be converted. offset, int The `int` length of the number. length) Constructs a `BigDecimal` object from an array of characters.
public	BigDecimal(double The `double` to be converted. num) Constructs a `BigDecimal` object directly from a `double`.
public	BigDecimal(int The `int` to be converted. num) Constructs a `BigDecimal` object directly from a `int`.
public	BigDecimal(long The `long` to be converted. num) Constructs a `BigDecimal` object directly from a `long`.
public	BigDecimal(String The `String` to be converted. string) Constructs a `BigDecimal` object from a `String`.
private	BigDecimal()

Method Summary

Modifier and Type	Method and Description
public BigDecimal	Returns: A `BigDecimal` whose value is the absolute value of this `BigDecimal`. abs() Returns a plain `BigDecimal` whose value is the absolute value of this `BigDecimal`.
public BigDecimal	Returns: A `BigDecimal` whose value is the absolute value of this `BigDecimal`. abs(MathContext The `MathContext` arithmetic settings. set) Returns a `BigDecimal` whose value is the absolute value of this `BigDecimal`.
public BigDecimal	Returns: A `BigDecimal` whose value is `this+rhs`, using fixed point arithmetic. add(BigDecimal The `BigDecimal` for the right hand side of the addition. rhs) Returns a plain `BigDecimal` whose value is `this+rhs`, using fixed point arithmetic.
public BigDecimal	Returns: A `BigDecimal` whose value is `this+rhs`. add(BigDecimal The `BigDecimal` for the right hand side of the addition. rhs, MathContext The `MathContext` arithmetic settings. set) Returns a `BigDecimal` whose value is `this+rhs`.
private static final boolean	allzero(byte[] array, int start)
private void	bad(char[] s)
private void	badarg(String name, int pos, String value)
private static final byte[]	byteaddsub(byte[] a, int avlen, byte[] b, int bvlen, int m, boolean reuse)
public byte	Returns: A `byte` equal in value to `this`. byteValueExact() Converts this `BigDecimal` to a `byte`.
private void	checkdigits(BigDecimal rhs, int dig)
private static final BigDecimal	clone(BigDecimal dec)
public int	Returns: An `int` whose value is -1, 0, or 1 as `this` is numerically less than, equal to, or greater than `rhs`. compareTo(BigDecimal The `BigDecimal` for the right hand side of the comparison. rhs) Implements java.lang.Comparable.compareTo. Compares this `BigDecimal` to another, using unlimited precision.
public int	Returns: An `int` whose value is -1, 0, or 1 as `this` is numerically less than, equal to, or greater than `rhs`. compareTo(BigDecimal The `BigDecimal` for the right hand side of the comparison. rhs, MathContext The `MathContext` arithmetic settings. set) Compares this `BigDecimal` to another.
private static final byte[]	diginit()
public BigDecimal	Returns: A plain `BigDecimal` whose value is `this/rhs`, using fixed point arithmetic. divide(BigDecimal The `BigDecimal` for the right hand side of the division. rhs) Returns a plain `BigDecimal` whose value is `this/rhs`, using fixed point arithmetic.
public BigDecimal	Returns: A plain `BigDecimal` whose value is `this/rhs`, using fixed point arithmetic and the specified rounding mode. divide(BigDecimal The `BigDecimal` for the right hand side of the division. rhs, int The `int` rounding mode to be used for the division (see the `MathContext` class). round) Returns a plain `BigDecimal` whose value is `this/rhs`, using fixed point arithmetic and a rounding mode.
public BigDecimal	Returns: A plain `BigDecimal` whose value is `this/rhs`, using fixed point arithmetic and the specified rounding mode. divide(BigDecimal The `BigDecimal` for the right hand side of the division. rhs, int The `int` scale to be used for the result. scale, int The `int` rounding mode to be used for the division (see the `MathContext` class). round) Returns a plain `BigDecimal` whose value is `this/rhs`, using fixed point arithmetic and a given scale and rounding mode.
public BigDecimal	Returns: A `BigDecimal` whose value is `this/rhs`. divide(BigDecimal The `BigDecimal` for the right hand side of the division. rhs, MathContext The `MathContext` arithmetic settings. set) Returns a `BigDecimal` whose value is `this/rhs`.
public BigDecimal	Returns: A `BigDecimal` whose value is the integer part of `this/rhs`. divideInteger(BigDecimal The `BigDecimal` for the right hand side of the integer division. rhs) Returns a plain `BigDecimal` whose value is the integer part of `this/rhs`.
public BigDecimal	Returns: A `BigDecimal` whose value is the integer part of `this/rhs`. divideInteger(BigDecimal The `BigDecimal` for the right hand side of the integer division. rhs, MathContext The `MathContext` arithmetic settings. set) Returns a `BigDecimal` whose value is the integer part of `this/rhs`.
private BigDecimal	dodivide(char code, BigDecimal rhs, MathContext set, int scale)
public double	Returns: A `double` corresponding to `this`. doubleValue() Implements abstract java.lang.Number.doubleValue. Converts this `BigDecimal` to a `double`.
public boolean	Returns: A `boolean` whose value true if and only if the operands have identical string representations. equals(Object The `Object` for the right hand side of the comparison. obj) Overrides java.lang.Object.equals. Compares this `BigDecimal` with `rhs` for equality.
private static final byte[]	extend(byte[] inarr, int newlen)
private BigDecimal	finish(MathContext set, boolean strip)
public float	Returns: A `float` corresponding to `this`. floatValue() Implements abstract java.lang.Number.floatValue. Converts this `BigDecimal` to a `float`.
public String	Returns: A `String` representing this `BigDecimal`, laid out according to the specified parameters format(int The `int` specifying the number of places before the decimal point. Use -1 for 'as many as are needed'. before, int The `int` specifying the number of places after the decimal point. Use -1 for 'as many as are needed'. after) Returns the `String` representation of this `BigDecimal`, modified by layout parameters.
public String	Returns: A `String` representing this `BigDecimal`, laid out according to the specified parameters format(int The `int` specifying the number of places before the decimal point. Use -1 for 'as many as are needed'. before, int The `int` specifying the number of places after the decimal point. Use -1 for 'as many as are needed'. after, int The `int` specifying the number of places to be used for any exponent. Use -1 for 'as many as are needed'. explaces, int The `int` specifying the trigger (digits before the decimal point) which if exceeded causes exponential notation to be used. Use 0 to force exponential notation. Use -1 to force plain notation (no exponential notation). exdigits, int The `int` specifying the form of exponential notation to be used ( `MathContext#SCIENTIFIC` or `MathContext#ENGINEERING`). exformint, int The `int` specifying the rounding mode to use. Use -1 for the default, `MathContext#ROUND_HALF_UP`. exround) Returns the `String` representation of this `BigDecimal`, modified by layout parameters and allowing exponential notation.
public int	Returns: An `int` that is the hashcode for `this`. hashCode() Overrides java.lang.Object.hashCode. Returns the hashcode for this `BigDecimal`.
private int	intcheck(int min, int max)
public int	Returns: An `int` converted from `this`, truncated and decapitated if necessary. intValue() Implements abstract java.lang.Number.intValue. Converts this `BigDecimal` to an `int`.
public int	Returns: An `int` equal in value to `this`. intValueExact() Converts this `BigDecimal` to an `int`.
private char[]	layout()
public long	Returns: A `long` converted from `this`, truncated and decapitated if necessary. longValue() Implements abstract java.lang.Number.longValue. Converts this `BigDecimal` to a `long`.
public long	Returns: A `long` equal in value to `this`. longValueExact() Converts this `BigDecimal` to a `long`.
public BigDecimal	Returns: A `BigDecimal` whose value is the maximum of `this` and `rhs`. max(BigDecimal The `BigDecimal` for the right hand side of the comparison. rhs) Returns a plain `BigDecimal` whose value is the maximum of `this` and `rhs`.
public BigDecimal	Returns: A `BigDecimal` whose value is the maximum of `this` and `rhs`. max(BigDecimal The `BigDecimal` for the right hand side of the comparison. rhs, MathContext The `MathContext` arithmetic settings. set) Returns a `BigDecimal` whose value is the maximum of `this` and `rhs`.
public BigDecimal	Returns: A `BigDecimal` whose value is the minimum of `this` and `rhs`. min(BigDecimal The `BigDecimal` for the right hand side of the comparison. rhs) Returns a plain `BigDecimal` whose value is the minimum of `this` and `rhs`.
public BigDecimal	Returns: A `BigDecimal` whose value is the minimum of `this` and `rhs`. min(BigDecimal The `BigDecimal` for the right hand side of the comparison. rhs, MathContext The `MathContext` arithmetic settings. set) Returns a `BigDecimal` whose value is the minimum of `this` and `rhs`.
public BigDecimal	Returns: A `BigDecimal` derived from `this`, with the decimal point moved `n` places to the left. movePointLeft(int The `int` specifying the number of places to move the decimal point leftwards. n) Returns a plain `BigDecimal` whose decimal point has been moved to the left by a specified number of positions.
public BigDecimal	Returns: A `BigDecimal` derived from `this`, with the decimal point moved `n` places to the right. movePointRight(int The `int` specifying the number of places to move the decimal point rightwards. n) Returns a plain `BigDecimal` whose decimal point has been moved to the right by a specified number of positions.
public BigDecimal	Returns: A `BigDecimal` whose value is `thisrhs`, using fixed point arithmetic. multiply(BigDecimal The `BigDecimal` for the right hand side of the multiplication. rhs) Returns a plain `BigDecimal` whose value is `thisrhs`, using fixed point arithmetic.
public BigDecimal	Returns: A `BigDecimal` whose value is `thisrhs`. multiply(BigDecimal The `BigDecimal` for the right hand side of the multiplication. rhs, MathContext The `MathContext` arithmetic settings. set) Returns a `BigDecimal` whose value is `thisrhs`.
public BigDecimal	Returns: A `BigDecimal` whose value is `-this`. negate() Returns a plain `BigDecimal` whose value is `-this`.
public BigDecimal	Returns: A `BigDecimal` whose value is `-this`. negate(MathContext The `MathContext` arithmetic settings. set) Returns a `BigDecimal` whose value is `-this`.
public BigDecimal	Returns: A `BigDecimal` whose value is `+this`. plus() Returns a plain `BigDecimal` whose value is `+this`.
public BigDecimal	Returns: A `BigDecimal` whose value is `+this`. plus(MathContext The `MathContext` arithmetic settings. set) Returns a `BigDecimal` whose value is `+this`.
public BigDecimal	Returns: A `BigDecimal` whose value is `thisrhs`, using fixed point arithmetic. pow(BigDecimal The `BigDecimal` for the right hand side of the operation (the power). rhs) Returns a plain `BigDecimal` whose value is `thisrhs`, using fixed point arithmetic.
public BigDecimal	Returns: A `BigDecimal` whose value is `thisrhs`. pow(BigDecimal The `BigDecimal` for the right hand side of the operation (the power). rhs, MathContext The `MathContext` arithmetic settings. set) Returns a `BigDecimal` whose value is `thisrhs`.
public BigDecimal	Returns: A `BigDecimal` whose value is the remainder of `this/rhs`, using fixed point arithmetic. remainder(BigDecimal The `BigDecimal` for the right hand side of the remainder operation. rhs) Returns a plain `BigDecimal` whose value is the remainder of `this/rhs`, using fixed point arithmetic.
public BigDecimal	Returns: A `BigDecimal` whose value is the remainder of `this+rhs`. remainder(BigDecimal The `BigDecimal` for the right hand side of the remainder operation. rhs, MathContext The `MathContext` arithmetic settings. set) Returns a `BigDecimal` whose value is the remainder of `this/rhs`.
private BigDecimal	round(MathContext set)
private BigDecimal	round(int len, int mode)
public int	Returns: An `int` whose value is the scale of this `BigDecimal`. scale() Returns the scale of this `BigDecimal`.
public BigDecimal	Returns: A plain `BigDecimal` with the given scale. setScale(int The `int` specifying the scale of the resulting `BigDecimal`. scale) Returns a plain `BigDecimal` with a given scale.
public BigDecimal	Returns: A plain `BigDecimal` with the given scale. setScale(int The `int` specifying the scale of the resulting `BigDecimal`. scale, int The `int` rounding mode to be used for the division (see the `MathContext` class). round) Returns a plain `BigDecimal` with a given scale.
public short	Returns: A `short` equal in value to `this`. shortValueExact() Converts this `BigDecimal` to a `short`.
public int	Returns: An `int` which is -1 if the `BigDecimal` is negative, 0 if it is numerically equal to zero, or 1 if it is positive. signum() Returns the sign of this `BigDecimal`, as an `int`.
public BigDecimal	Returns: A `BigDecimal` whose value is `this-rhs`, using fixed point arithmetic. subtract(BigDecimal The `BigDecimal` for the right hand side of the subtraction. rhs) Returns a plain `BigDecimal` whose value is `this-rhs`, using fixed point arithmetic.
public BigDecimal	Returns: A `BigDecimal` whose value is `this-rhs`. subtract(BigDecimal The `BigDecimal` for the right hand side of the subtraction. rhs, MathContext The `MathContext` arithmetic settings. set) Returns a `BigDecimal` whose value is `this-rhs`.
public BigDecimal	Returns: The `java.math.BigDecimal` equal in value to this `BigDecimal`. toBigDecimal() Converts this `BigDecimal` to a `java.math.BigDecimal`.
public BigInteger	Returns: The `java.math.BigInteger` equal in value to the integer part of this `BigDecimal`. toBigInteger() Converts this `BigDecimal` to a `java.math.BigInteger`.
public BigInteger	Returns: The `java.math.BigInteger` equal in value to the integer part of this `BigDecimal`. toBigIntegerExact() Converts this `BigDecimal` to a `java.math.BigInteger`.
public char[]	Returns: The `char[]` array corresponding to this `BigDecimal`. toCharArray() Returns the `BigDecimal` as a character array.
public String	Returns: The `String` exactly corresponding to this `BigDecimal`. toString() Overrides java.lang.Object.toString. Returns the `BigDecimal` as a `String`.
public BigInteger	Returns: The `java.math.BigInteger` equal in value to this `BigDecimal` multiplied by ten to the power of `this.scale()`. unscaledValue() Returns the number as a `BigInteger` after removing the scale.
public static BigDecimal	Returns: The `BigDecimal` equal in value to `dub`. valueOf(double The `double` to be translated. dub) Translates a `double` to a `BigDecimal`.
public static BigDecimal	Returns: The `BigDecimal` equal in value to `lint`. valueOf(long The `long` to be translated. lint) Translates a `long` to a `BigDecimal`.
public static BigDecimal	Returns: The `BigDecimal` equal in value to `lint`. valueOf(long The `long` to be translated. lint, int The `int` scale to be applied. scale) Translates a `long` to a `BigDecimal` with a given scale.

Inherited from java.lang.Number:: byteValue shortValue

public Class BigDecimal

Operator methods

Field Summary

Constructor Summary

Method Summary