BigDecimal

Kotlin |Java

open class BigDecimal : Number, Comparable<BigDecimal!>, Serializable

kotlin.Any
↳	kotlin.Number
	↳	android.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.

Summary

Constants
static Int	`ROUND_CEILING` Rounding mode to round to a more positive number.
static Int	`ROUND_DOWN` Rounding mode to round towards zero.
static Int	`ROUND_FLOOR` Rounding mode to round to a more negative number.
static Int	`ROUND_HALF_DOWN` Rounding mode to round to nearest neighbor, where an equidistant value is rounded down.
static Int	`ROUND_HALF_EVEN` Rounding mode to round to nearest neighbor, where an equidistant value is rounded to the nearest even neighbor.
static Int	`ROUND_HALF_UP` Rounding mode to round to nearest neighbor, where an equidistant value is rounded up.
static Int	`ROUND_UNNECESSARY` Rounding mode to assert that no rounding is necessary.
static Int	`ROUND_UP` Rounding mode to round away from zero.

Public constructors
`BigDecimal(inchars: CharArray!)` Constructs a `BigDecimal` object from an array of characters.
`BigDecimal(inchars: CharArray!, offset: Int, length: Int)` Constructs a `BigDecimal` object from an array of characters.
`BigDecimal(num: Double)` Constructs a `BigDecimal` object directly from a `double`.
`BigDecimal(num: Int)` Constructs a `BigDecimal` object directly from a `int`.
`BigDecimal(string: String!)` Constructs a `BigDecimal` object from a `String`.
`BigDecimal(bd: BigDecimal!)` Constructs a `BigDecimal` object from a `java.math.BigDecimal`.
`BigDecimal(bi: BigInteger!)` Constructs a `BigDecimal` object from a `BigInteger`, with scale 0.
`BigDecimal(bi: BigInteger!, scale: Int)` Constructs a `BigDecimal` object from a `BigInteger` and a scale.
`BigDecimal(num: Long)` Constructs a `BigDecimal` object directly from a `long`.

Public methods
open BigDecimal!	`abs()` Returns a plain `BigDecimal` whose value is the absolute value of this `BigDecimal`.
open BigDecimal!	`abs(set: MathContext!)` Returns a `BigDecimal` whose value is the absolute value of this `BigDecimal`.
open BigDecimal!	`add(rhs: BigDecimal!)` Returns a plain `BigDecimal` whose value is `this+rhs`, using fixed point arithmetic.
open BigDecimal!	`add(rhs: BigDecimal!, set: MathContext!)` Returns a `BigDecimal` whose value is `this+rhs`.
open Byte	`byteValueExact()` Converts this `BigDecimal` to a `byte`.
open Int	`compareTo(other: BigDecimal!)` Compares this `BigDecimal` to another, using unlimited precision.
open Int	`compareTo(rhs: BigDecimal!, set: MathContext!)` Compares this `BigDecimal` to another.
open BigDecimal!	`divide(rhs: BigDecimal!)` Returns a plain `BigDecimal` whose value is `this/rhs`, using fixed point arithmetic.
open BigDecimal!	`divide(rhs: BigDecimal!, set: MathContext!)` Returns a `BigDecimal` whose value is `this/rhs`.
open BigDecimal!	`divide(rhs: BigDecimal!, round: Int)` Returns a plain `BigDecimal` whose value is `this/rhs`, using fixed point arithmetic and a rounding mode.
open BigDecimal!	`divide(rhs: BigDecimal!, scale: Int, round: Int)` Returns a plain `BigDecimal` whose value is `this/rhs`, using fixed point arithmetic and a given scale and rounding mode.
open BigDecimal!	`divideInteger(rhs: BigDecimal!)` Returns a plain `BigDecimal` whose value is the integer part of `this/rhs`.
open BigDecimal!	`divideInteger(rhs: BigDecimal!, set: MathContext!)` Returns a `BigDecimal` whose value is the integer part of `this/rhs`.
open Boolean	`equals(other: Any?)` Compares this `BigDecimal` with `rhs` for equality.
open String!	`format(before: Int, after: Int)` Returns the `String` representation of this `BigDecimal`, modified by layout parameters.
open String!	`format(before: Int, after: Int, explaces: Int, exdigits: Int, exformint: Int, exround: Int)` Returns the `String` representation of this `BigDecimal`, modified by layout parameters and allowing exponential notation.
open Int	`hashCode()` Returns the hashcode for this `BigDecimal`.
open Int	`intValueExact()` Converts this `BigDecimal` to an `int`.
open Long	`longValueExact()` Converts this `BigDecimal` to a `long`.
open BigDecimal!	`max(rhs: BigDecimal!)` Returns a plain `BigDecimal` whose value is the maximum of `this` and `rhs`.
open BigDecimal!	`max(rhs: BigDecimal!, set: MathContext!)` Returns a `BigDecimal` whose value is the maximum of `this` and `rhs`.
open BigDecimal!	`min(rhs: BigDecimal!)` Returns a plain `BigDecimal` whose value is the minimum of `this` and `rhs`.
open BigDecimal!	`min(rhs: BigDecimal!, set: MathContext!)` Returns a `BigDecimal` whose value is the minimum of `this` and `rhs`.
open BigDecimal!	`movePointLeft(n: Int)` Returns a plain `BigDecimal` whose decimal point has been moved to the left by a specified number of positions.
open BigDecimal!	`movePointRight(n: Int)` Returns a plain `BigDecimal` whose decimal point has been moved to the right by a specified number of positions.
open BigDecimal!	`multiply(rhs: BigDecimal!)` Returns a plain `BigDecimal` whose value is `this*rhs`, using fixed point arithmetic.
open BigDecimal!	`multiply(rhs: BigDecimal!, set: MathContext!)` Returns a `BigDecimal` whose value is `this*rhs`.
open BigDecimal!	`negate()` Returns a plain `BigDecimal` whose value is `-this`.
open BigDecimal!	`negate(set: MathContext!)` Returns a `BigDecimal` whose value is `-this`.
open BigDecimal!	`plus()` Returns a plain `BigDecimal` whose value is `+this`.
open BigDecimal!	`plus(set: MathContext!)` Returns a `BigDecimal` whose value is `+this`.
open BigDecimal!	`pow(rhs: BigDecimal!)` Returns a plain `BigDecimal` whose value is `this**rhs`, using fixed point arithmetic.
open BigDecimal!	`pow(rhs: BigDecimal!, set: MathContext!)` Returns a `BigDecimal` whose value is `this**rhs`.
open BigDecimal!	`remainder(rhs: BigDecimal!)` Returns a plain `BigDecimal` whose value is the remainder of `this/rhs`, using fixed point arithmetic.
open BigDecimal!	`remainder(rhs: BigDecimal!, set: MathContext!)` Returns a `BigDecimal` whose value is the remainder of `this/rhs`.
open Int	`scale()` Returns the scale of this `BigDecimal`.
open BigDecimal!	`setScale(scale: Int)` Returns a plain `BigDecimal` with a given scale.
open BigDecimal!	`setScale(scale: Int, round: Int)` Returns a plain `BigDecimal` with a given scale.
open Short	`shortValueExact()` Converts this `BigDecimal` to a `short`.
open Int	`signum()` Returns the sign of this `BigDecimal`, as an `int`.
open BigDecimal!	`subtract(rhs: BigDecimal!)` Returns a plain `BigDecimal` whose value is `this-rhs`, using fixed point arithmetic.
open BigDecimal!	`subtract(rhs: BigDecimal!, set: MathContext!)` Returns a `BigDecimal` whose value is `this-rhs`.
open BigDecimal!	`toBigDecimal()` Converts this `BigDecimal` to a `java.math.BigDecimal`.
open BigInteger!	`toBigInteger()` Converts this `BigDecimal` to a `java.math.BigInteger`.
open BigInteger!	`toBigIntegerExact()` Converts this `BigDecimal` to a `java.math.BigInteger`.
open CharArray!	`toCharArray()` Returns the `BigDecimal` as a character array.
open Double	`toDouble()` Converts this `BigDecimal` to a `double`.
open Float	`toFloat()` Converts this `BigDecimal` to a `float`.
open Int	`toInt()` Converts this `BigDecimal` to an `int`.
open Long	`toLong()` Converts this `BigDecimal` to a `long`.
open String	`toString()` Returns the `BigDecimal` as a `String`.
open BigInteger!	`unscaledValue()` Returns the number as a `BigInteger` after removing the scale.
open static BigDecimal!	`valueOf(dub: Double)` Translates a `double` to a `BigDecimal`.
open static BigDecimal!	`valueOf(lint: Long)` Translates a `long` to a `BigDecimal`.
open static BigDecimal!	`valueOf(lint: Long, scale: Int)` Translates a `long` to a `BigDecimal` with a given scale.

Properties
static BigDecimal!	`ONE` The `BigDecimal` constant "1".
static BigDecimal!	`TEN` The `BigDecimal` constant "10".
static BigDecimal!	`ZERO` The `BigDecimal` constant "0".

Parameters
`inchars`	CharArray!: The `char[]` array containing the number to be converted.
`offset`	Int: The `int` offset into the array of the start of the number to be converted.
`length`	Int: The `int` length of the number.

Parameters
`bi`	BigInteger!: The `BigInteger` to be converted.
`scale`	Int: The `int` specifying the scale.

Parameters
`rhs`	BigDecimal!: The `BigDecimal` for the right hand side of the addition.
`set`	MathContext!: The `MathContext` arithmetic settings.

Parameters
`o`	the object to be compared.
`rhs`	The `BigDecimal` for the right hand side of the comparison.

Exceptions
`java.lang.NullPointerException`	if the specified object is null
`java.lang.ClassCastException`	if the specified object's type prevents it from being compared to this object.

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

Parameters
`rhs`	BigDecimal!: The `BigDecimal` for the right hand side of the division.
`round`	Int: The `int` rounding mode to be used for the division (see the `MathContext` class).

Exceptions
`java.lang.IllegalArgumentException`	if `round` is not a valid rounding mode.
`java.lang.ArithmeticException`	if `round` is `MathContext.ROUND_UNNECESSARY` and `this.scale()` is insufficient to represent the result exactly.

Parameters
`before`	Int: The `int` specifying the number of places before the decimal point. Use -1 for 'as many as are needed'.
`after`	Int: The `int` specifying the number of places after the decimal point. Use -1 for 'as many as are needed'.

Exceptions
`java.lang.ArithmeticException`	if the number cannot be laid out as requested.
`java.lang.IllegalArgumentException`	if a parameter is out of range.

Parameters
`scale`	Int: The `int` specifying the scale of the resulting `BigDecimal`.
`round`	Int: The `int` rounding mode to be used for the division (see the `MathContext` class).

Parameters
`lint`	Long: The `long` to be translated.
`scale`	Int: The `int` scale to be applied.

BigDecimal

Operator methods

Summary

Constants

ROUND_CEILING

ROUND_DOWN

ROUND_FLOOR

ROUND_HALF_DOWN

ROUND_HALF_EVEN

ROUND_HALF_UP

ROUND_UNNECESSARY

ROUND_UP

Public constructors

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

Public methods

abs

abs

add

add

byteValueExact

compareTo

compareTo

divide

divide

divide

divide

divideInteger

divideInteger

equals

format

format

hashCode

intValueExact

longValueExact

max

max

min

min

movePointLeft

movePointRight

multiply

multiply

negate

negate

plus

plus

pow

pow

remainder

remainder

scale

setScale

setScale

shortValueExact

signum

subtract

subtract

toBigDecimal

toBigInteger

toBigIntegerExact

toCharArray

toDouble

toFloat

toInt

toLong

toString

unscaledValue

valueOf

valueOf

valueOf

Properties

ONE