Added in API level 1

BigDecimal

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

kotlin.Any
↳	kotlin.Number
	↳	java.math.BigDecimal

An immutable arbitrary-precision signed decimal.

A value is represented by an arbitrary-precision "unscaled value" and a signed 32-bit "scale", combined thus: unscaled * 10-scale. See unscaledValue and scale.

Most operations allow you to supply a MathContext to specify a desired rounding mode.

Summary

Constants
static Int	`ROUND_CEILING` Rounding mode to round towards positive infinity.
static Int	`ROUND_DOWN` Rounding mode where the values are rounded towards zero.
static Int	`ROUND_FLOOR` Rounding mode to round towards negative infinity.
static Int	`ROUND_HALF_DOWN` Rounding mode where values are rounded towards the nearest neighbor.
static Int	`ROUND_HALF_EVEN` Rounding mode where values are rounded towards the nearest neighbor.
static Int	`ROUND_HALF_UP` Rounding mode where values are rounded towards the nearest neighbor.
static Int	`ROUND_UNNECESSARY` Rounding mode where the rounding operations throws an `ArithmeticException` for the case that rounding is necessary, i.
static Int	`ROUND_UP` Rounding mode where positive values are rounded towards positive infinity and negative values towards negative infinity.

Public constructors
`<init>(in: CharArray!, offset: Int, len: Int)` Constructs a new `BigDecimal` instance from a string representation given as a character array.
`<init>(in: CharArray!, offset: Int, len: Int, mc: MathContext!)` Constructs a new `BigDecimal` instance from a string representation given as a character array.
`<init>(in: CharArray!)` Constructs a new `BigDecimal` instance from a string representation given as a character array.
`<init>(in: CharArray!, mc: MathContext!)` Constructs a new `BigDecimal` instance from a string representation given as a character array.
`<init>(val: String!)` Constructs a new `BigDecimal` instance from a string representation.
`<init>(val: String!, mc: MathContext!)` Constructs a new `BigDecimal` instance from a string representation.
`<init>(val: Double)` Constructs a new `BigDecimal` instance from the 64bit double `val`.
`<init>(val: Double, mc: MathContext!)` Constructs a new `BigDecimal` instance from the 64bit double `val`.
`<init>(val: BigInteger!)` Constructs a new `BigDecimal` instance from the given big integer `val`.
`<init>(val: BigInteger!, mc: MathContext!)` Constructs a new `BigDecimal` instance from the given big integer `val`.
`<init>(unscaledVal: BigInteger!, scale: Int)` Constructs a new `BigDecimal` instance from a given unscaled value `unscaledVal` and a given scale.
`<init>(unscaledVal: BigInteger!, scale: Int, mc: MathContext!)` Constructs a new `BigDecimal` instance from a given unscaled value `unscaledVal` and a given scale.
`<init>(val: Int)` Constructs a new `BigDecimal` instance from the given int `val`.
`<init>(val: Int, mc: MathContext!)` Constructs a new `BigDecimal` instance from the given int `val`.
`<init>(val: Long)` Constructs a new `BigDecimal` instance from the given long `val`.
`<init>(val: Long, mc: MathContext!)` Constructs a new `BigDecimal` instance from the given long `val`.

Public methods
open BigDecimal!	`abs()` Returns a `BigDecimal` whose value is the absolute value of `this`.
open BigDecimal!	`abs(mc: MathContext!)` Returns a `BigDecimal` whose value is the absolute value of `this`.
open BigDecimal!	`add(augend: BigDecimal!)` Returns a new `BigDecimal` whose value is `this + augend`.
open BigDecimal!	`add(augend: BigDecimal!, mc: MathContext!)` Returns a new `BigDecimal` whose value is `this + augend`.
open Byte	`byteValueExact()` Returns this `BigDecimal` as a byte value if it has no fractional part and if its value fits to the byte range ([-128..127]).
open Int	`compareTo(other: BigDecimal!)` Compares this `BigDecimal` with `val`.
open BigDecimal!	`divide(divisor: BigDecimal!, scale: Int, roundingMode: Int)` Returns a new `BigDecimal` whose value is `this / divisor`.
open BigDecimal!	`divide(divisor: BigDecimal!, scale: Int, roundingMode: RoundingMode!)` Returns a new `BigDecimal` whose value is `this / divisor`.
open BigDecimal!	`divide(divisor: BigDecimal!, roundingMode: Int)` Returns a new `BigDecimal` whose value is `this / divisor`.
open BigDecimal!	`divide(divisor: BigDecimal!, roundingMode: RoundingMode!)` Returns a new `BigDecimal` whose value is `this / divisor`.
open BigDecimal!	`divide(divisor: BigDecimal!)` Returns a new `BigDecimal` whose value is `this / divisor`.
open BigDecimal!	`divide(divisor: BigDecimal!, mc: MathContext!)` Returns a new `BigDecimal` whose value is `this / divisor`.
open Array<BigDecimal!>!	`divideAndRemainder(divisor: BigDecimal!)` Returns a `BigDecimal` array which contains the integral part of `this / divisor` at index 0 and the remainder `this % divisor` at index 1.
open Array<BigDecimal!>!	`divideAndRemainder(divisor: BigDecimal!, mc: MathContext!)` Returns a `BigDecimal` array which contains the integral part of `this / divisor` at index 0 and the remainder `this % divisor` at index 1.
open BigDecimal!	`divideToIntegralValue(divisor: BigDecimal!)` Returns a new `BigDecimal` whose value is the integral part of `this / divisor`.
open BigDecimal!	`divideToIntegralValue(divisor: BigDecimal!, mc: MathContext!)` Returns a new `BigDecimal` whose value is the integral part of `this / divisor`.
open Boolean	`equals(other: Any?)` Returns `true` if `x` is a `BigDecimal` instance and if this instance is equal to this big decimal.
open Int	`hashCode()` Returns a hash code for this `BigDecimal`.
open Int	`intValueExact()` Returns this `BigDecimal` as a int value if it has no fractional part and if its value fits to the int range ([-231.
open Long	`longValueExact()` Returns this `BigDecimal` as a long value if it has no fractional part and if its value fits to the int range ([-263.
open BigDecimal!	`max(val: BigDecimal!)` Returns the maximum of this `BigDecimal` and `val`.
open BigDecimal!	`min(val: BigDecimal!)` Returns the minimum of this `BigDecimal` and `val`.
open BigDecimal!	`movePointLeft(n: Int)` Returns a new `BigDecimal` instance where the decimal point has been moved `n` places to the left.
open BigDecimal!	`movePointRight(n: Int)` Returns a new `BigDecimal` instance where the decimal point has been moved `n` places to the right.
open BigDecimal!	`multiply(multiplicand: BigDecimal!)` Returns a new `BigDecimal` whose value is `this * multiplicand`.
open BigDecimal!	`multiply(multiplicand: BigDecimal!, mc: MathContext!)` Returns a new `BigDecimal` whose value is `this * multiplicand`.
open BigDecimal!	`negate()` Returns a new `BigDecimal` whose value is the `-this`.
open BigDecimal!	`negate(mc: MathContext!)` Returns a new `BigDecimal` whose value is the `-this`.
open BigDecimal!	`plus()` Returns a new `BigDecimal` whose value is `+this`.
open BigDecimal!	`plus(mc: MathContext!)` Returns a new `BigDecimal` whose value is `+this`.
open BigDecimal!	`pow(n: Int)` Returns a new `BigDecimal` whose value is `this<sup>n</sup>`.
open BigDecimal!	`pow(n: Int, mc: MathContext!)` Returns a new `BigDecimal` whose value is `this<sup>n</sup>`.
open Int	`precision()` Returns the precision of this `BigDecimal`.
open BigDecimal!	`remainder(divisor: BigDecimal!)` Returns a new `BigDecimal` whose value is `this % divisor`.
open BigDecimal!	`remainder(divisor: BigDecimal!, mc: MathContext!)` Returns a new `BigDecimal` whose value is `this % divisor`.
open BigDecimal!	`round(mc: MathContext!)` Returns a new `BigDecimal` whose value is `this`, rounded according to the passed context `mc`.
open Int	`scale()` Returns the scale of this `BigDecimal`.
open BigDecimal!	`scaleByPowerOfTen(n: Int)` Returns a new `BigDecimal` whose value is `this * 10<sup>n</sup>`.
open BigDecimal!	`setScale(newScale: Int, roundingMode: RoundingMode!)` Returns a new `BigDecimal` instance with the specified scale.
open BigDecimal!	`setScale(newScale: Int, roundingMode: Int)` Returns a new `BigDecimal` instance with the specified scale.
open BigDecimal!	`setScale(newScale: Int)` Returns a new `BigDecimal` instance with the specified scale.
open Short	`shortValueExact()` Returns this `BigDecimal` as a short value if it has no fractional part and if its value fits to the short range ([-215.
open Int	`signum()` Returns the sign of this `BigDecimal`.
open BigDecimal!	`stripTrailingZeros()` Returns a new `BigDecimal` instance with the same value as `this` but with a unscaled value where the trailing zeros have been removed.
open BigDecimal!	`subtract(subtrahend: BigDecimal!)` Returns a new `BigDecimal` whose value is `this - subtrahend`.
open BigDecimal!	`subtract(subtrahend: BigDecimal!, mc: MathContext!)` Returns a new `BigDecimal` whose value is `this - subtrahend`.
open BigInteger!	`toBigInteger()` Returns this `BigDecimal` as a big integer instance.
open BigInteger!	`toBigIntegerExact()` Returns this `BigDecimal` as a big integer instance if it has no fractional part.
open Double	`toDouble()` Returns this `BigDecimal` as a double value.
open String!	`toEngineeringString()` Returns a string representation of this `BigDecimal`.
open Float	`toFloat()` Returns this `BigDecimal` as a float value.
open Int	`toInt()` Returns this `BigDecimal` as an int value.
open Long	`toLong()` Returns this `BigDecimal` as an long value.
open String!	`toPlainString()` Returns a string representation of this `BigDecimal`.
open String	`toString()` Returns a canonical string representation of this `BigDecimal`.
open BigDecimal!	`ulp()` Returns the unit in the last place (ULP) of this `BigDecimal` instance.
open BigInteger!	`unscaledValue()` Returns the unscaled value (mantissa) of this `BigDecimal` instance as a `BigInteger`.
open static BigDecimal!	`valueOf(unscaledVal: Long, scale: Int)` Returns a new `BigDecimal` instance whose value is equal to `unscaledVal * 10<sup>-scale</sup>`).
open static BigDecimal!	`valueOf(unscaledVal: Long)` Returns a new `BigDecimal` instance whose value is equal to `unscaledVal`.
open static BigDecimal!	`valueOf(val: Double)` Returns a new `BigDecimal` instance whose value is equal to `val`.

Properties
static BigDecimal!	`ONE` The constant one as a `BigDecimal`.
static BigDecimal!	`TEN` The constant ten as a `BigDecimal`.
static BigDecimal!	`ZERO` The constant zero as a `BigDecimal`.

Constants

ROUND_CEILING

Added in API level 1

static val ROUND_CEILING: Int

Rounding mode to round towards positive infinity. For positive values this rounding mode behaves as ROUND_UP, for negative values as ROUND_DOWN.

Value: 2

See Also

java.math.RoundingMode#CEILING

ROUND_DOWN

Added in API level 1

static val ROUND_DOWN: Int

Rounding mode where the values are rounded towards zero.

Value: 1

See Also

java.math.RoundingMode#DOWN

ROUND_FLOOR

Added in API level 1

static val ROUND_FLOOR: Int

Rounding mode to round towards negative infinity. For positive values this rounding mode behaves as ROUND_DOWN, for negative values as ROUND_UP.

Value: 3

See Also

java.math.RoundingMode#FLOOR

ROUND_HALF_DOWN

Added in API level 1

static val ROUND_HALF_DOWN: Int

Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding down.

Value: 5

See Also

java.math.RoundingMode#HALF_DOWN

ROUND_HALF_EVEN

Added in API level 1

static val ROUND_HALF_EVEN: Int

Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding to the even neighbor.

Value: 6

See Also

java.math.RoundingMode#HALF_EVEN

ROUND_HALF_UP

Added in API level 1

static val ROUND_HALF_UP: Int

Rounding mode where values are rounded towards the nearest neighbor. Ties are broken by rounding up.

Value: 4

See Also

java.math.RoundingMode#HALF_UP

ROUND_UNNECESSARY

Added in API level 1

static val ROUND_UNNECESSARY: Int

Rounding mode where the rounding operations throws an ArithmeticException for the case that rounding is necessary, i.e. for the case that the value cannot be represented exactly.

Value: 7

See Also

java.math.RoundingMode#UNNECESSARY

ROUND_UP

Added in API level 1

static val ROUND_UP: Int

Rounding mode where positive values are rounded towards positive infinity and negative values towards negative infinity.

Value: 0

See Also

java.math.RoundingMode#UP

Public constructors

<init>

Added in API level 1

BigDecimal(
    in: CharArray!, 
    offset: Int, 
    len: Int)

Constructs a new BigDecimal instance from a string representation given as a character array.

Parameters
`in`	CharArray!: array of characters containing the string representation of this `BigDecimal`.
`offset`	Int: first index to be copied.
`len`	Int: number of characters to be used.

Exceptions
`java.lang.NumberFormatException`	if `offset < 0 \|\| len <= 0 \|\| offset+len-1 < 0 \|\| offset+len-1 >= in.length`, or if `in` does not contain a valid string representation of a big decimal.

<init>

Added in API level 1

BigDecimal(
    in: CharArray!, 
    offset: Int, 
    len: Int, 
    mc: MathContext!)

Constructs a new BigDecimal instance from a string representation given as a character array.

Parameters
`in`	CharArray!: array of characters containing the string representation of this `BigDecimal`.
`offset`	Int: first index to be copied.
`len`	Int: number of characters to be used.
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Exceptions
`java.lang.NumberFormatException`	if `offset < 0 \|\| len <= 0 \|\| offset+len-1 < 0 \|\| offset+len-1 >= in.length`, or if `in` does not contain a valid string representation of a big decimal.
`java.lang.ArithmeticException`	if `mc.precision > 0` and `mc.roundingMode == UNNECESSARY` and the new big decimal cannot be represented within the given precision without rounding.

<init>

Added in API level 1

BigDecimal(in: CharArray!)

Constructs a new BigDecimal instance from a string representation given as a character array.

Parameters
`in`	CharArray!: array of characters containing the string representation of this `BigDecimal`.

Exceptions
`java.lang.NumberFormatException`	if `in` does not contain a valid string representation of a big decimal.

<init>

Added in API level 1

BigDecimal(
    in: CharArray!, 
    mc: MathContext!)

Constructs a new BigDecimal instance from a string representation given as a character array. The result is rounded according to the specified math context.

Parameters
`in`	CharArray!: array of characters containing the string representation of this `BigDecimal`.
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Exceptions
`java.lang.NumberFormatException`	if `in` does not contain a valid string representation of a big decimal.
`java.lang.ArithmeticException`	if `mc.precision > 0` and `mc.roundingMode == UNNECESSARY` and the new big decimal cannot be represented within the given precision without rounding.

<init>

Added in API level 1

BigDecimal(val: String!)

Constructs a new BigDecimal instance from a string representation.

Exceptions
`java.lang.NumberFormatException`	if `val` does not contain a valid string representation of a big decimal.

<init>

Added in API level 1

BigDecimal(
    val: String!, 
    mc: MathContext!)

Constructs a new BigDecimal instance from a string representation. The result is rounded according to the specified math context.

Parameters
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Exceptions
`java.lang.NumberFormatException`	if `val` does not contain a valid string representation of a big decimal.
`java.lang.ArithmeticException`	if `mc.precision > 0` and `mc.roundingMode == UNNECESSARY` and the new big decimal cannot be represented within the given precision without rounding.

<init>

Added in API level 1

BigDecimal(val: Double)

Constructs a new BigDecimal instance from the 64bit double val. The constructed big decimal is equivalent to the given double. For example, new BigDecimal(0.1) is equal to 0.1000000000000000055511151231257827021181583404541015625. This happens as 0.1 cannot be represented exactly in binary.

To generate a big decimal instance which is equivalent to 0.1 use the BigDecimal(String) constructor.

Parameters
`val`	Double: double value to be converted to a `BigDecimal` instance.

Exceptions
`java.lang.NumberFormatException`	if `val` is infinity or not a number.

<init>

Added in API level 1

BigDecimal(
    val: Double, 
    mc: MathContext!)

To generate a big decimal instance which is equivalent to 0.1 use the BigDecimal(String) constructor.

Parameters
`val`	Double: double value to be converted to a `BigDecimal` instance.
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Exceptions
`java.lang.NumberFormatException`	if `val` is infinity or not a number.
`java.lang.ArithmeticException`	if `mc.precision > 0` and `mc.roundingMode == UNNECESSARY` and the new big decimal cannot be represented within the given precision without rounding.

<init>

Added in API level 1

BigDecimal(val: BigInteger!)

Constructs a new BigDecimal instance from the given big integer val. The scale of the result is 0.

<init>

Added in API level 1

BigDecimal(
    val: BigInteger!, 
    mc: MathContext!)

Constructs a new BigDecimal instance from the given big integer val. The scale of the result is 0.

Parameters
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Exceptions
`java.lang.ArithmeticException`	if `mc.precision > 0` and `mc.roundingMode == UNNECESSARY` and the new big decimal cannot be represented within the given precision without rounding.

<init>

Added in API level 1

BigDecimal(
    unscaledVal: BigInteger!, 
    scale: Int)

Constructs a new BigDecimal instance from a given unscaled value unscaledVal and a given scale. The value of this instance is unscaledVal * 10-scale).

Exceptions
`java.lang.NullPointerException`	if `unscaledVal == null`.

<init>

BigDecimal(
    unscaledVal: BigInteger!, 
    scale: Int, 
    mc: MathContext!)

Constructs a new BigDecimal instance from a given unscaled value unscaledVal and a given scale. The value of this instance is unscaledVal * 10-scale). The result is rounded according to the specified math context. mc rounding mode and precision for the result of this operation. ArithmeticException if { mc.precision > 0} and { mc.roundingMode == UNNECESSARY} and the new big decimal cannot be represented within the given precision without rounding. NullPointerException if { unscaledVal == null}. 1

<init>

Added in API level 1

BigDecimal(val: Int)

Constructs a new BigDecimal instance from the given int val. The scale of the result is 0.

Parameters
`val`	Int: int value to be converted to a `BigDecimal` instance.

<init>

Added in API level 1

BigDecimal(
    val: Int, 
    mc: MathContext!)

Constructs a new BigDecimal instance from the given int val. The scale of the result is 0. The result is rounded according to the specified math context.

Parameters
`val`	Int: int value to be converted to a `BigDecimal` instance.
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Exceptions
`java.lang.ArithmeticException`	if `mc.precision > 0` and `c.roundingMode == UNNECESSARY` and the new big decimal cannot be represented within the given precision without rounding.

<init>

Added in API level 1

BigDecimal(val: Long)

Constructs a new BigDecimal instance from the given long val. The scale of the result is 0.

Parameters
`val`	Long: long value to be converted to a `BigDecimal` instance.

<init>

Added in API level 1

BigDecimal(
    val: Long, 
    mc: MathContext!)

Constructs a new BigDecimal instance from the given long val. The scale of the result is 0. The result is rounded according to the specified math context.

Parameters
`val`	Long: long value to be converted to a `BigDecimal` instance.
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Exceptions
`java.lang.ArithmeticException`	if `mc.precision > 0` and `mc.roundingMode == UNNECESSARY` and the new big decimal cannot be represented within the given precision without rounding.

Public methods

abs

Added in API level 1

open fun abs(): BigDecimal!

Returns a BigDecimal whose value is the absolute value of this. The scale of the result is the same as the scale of this.

abs

Added in API level 1

open fun abs(mc: MathContext!): BigDecimal!

Returns a BigDecimal whose value is the absolute value of this. The result is rounded according to the passed context mc.

add

Added in API level 1

open fun add(augend: BigDecimal!): BigDecimal!

Returns a new BigDecimal whose value is this + augend. The scale of the result is the maximum of the scales of the two arguments.

Parameters
`augend`	BigDecimal!: value to be added to `this`.

Return
`BigDecimal!`	`this + augend`.

Exceptions
`java.lang.NullPointerException`	if `augend == null`.

add

Added in API level 1

open fun add(
    augend: BigDecimal!, 
    mc: MathContext!
): BigDecimal!

Returns a new BigDecimal whose value is this + augend. The result is rounded according to the passed context mc.

Parameters
`augend`	BigDecimal!: value to be added to `this`.
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Return
`BigDecimal!`	`this + augend`.

Exceptions
`java.lang.NullPointerException`	if `augend == null` or `mc == null`.

byteValueExact

Added in API level 1

open fun byteValueExact(): Byte

Returns this BigDecimal as a byte value if it has no fractional part and if its value fits to the byte range ([-128..127]). If these conditions are not met, an ArithmeticException is thrown.

Exceptions
`java.lang.ArithmeticException`	if rounding is necessary or the number doesn't fit in a byte.

compareTo

Added in API level 1

open fun compareTo(other: BigDecimal!): Int

Compares this BigDecimal with val. Returns one of the three values 1, 0, or -1. The method behaves as if this.subtract(val) is computed. If this difference is > 0 then 1 is returned, if the difference is < 0 then -1 is returned, and if the difference is 0 then 0 is returned. This means, that if two decimal instances are compared which are equal in value but differ in scale, then these two instances are considered as equal.

Parameters
`o`	the object to be compared.
`val`	value to be compared with `this`.

Return
`Int`	`1` if `this > val`, `-1` if `this < val`, `0` if `this == val`.

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

divide

Added in API level 1

open fun divide(
    divisor: BigDecimal!, 
    scale: Int, 
    roundingMode: Int
): BigDecimal!

Returns a new BigDecimal whose value is this / divisor. As scale of the result the parameter scale is used. If rounding is required to meet the specified scale, then the specified rounding mode roundingMode is applied.

Parameters
`divisor`	BigDecimal!: value by which `this` is divided.
`scale`	Int: the scale of the result returned.
`roundingMode`	Int: rounding mode to be used to round the result.

Return
`BigDecimal!`	`this / divisor` rounded according to the given rounding mode.

Exceptions
`java.lang.NullPointerException`	if `divisor == null`.
`java.lang.IllegalArgumentException`	if `roundingMode` is not a valid rounding mode.
`java.lang.ArithmeticException`	if `roundingMode == ROUND_UNNECESSARY` and rounding is necessary according to the given scale.

divide

Added in API level 1

open fun divide(
    divisor: BigDecimal!, 
    scale: Int, 
    roundingMode: RoundingMode!
): BigDecimal!

Parameters
`divisor`	BigDecimal!: value by which `this` is divided.
`scale`	Int: the scale of the result returned.
`roundingMode`	RoundingMode!: rounding mode to be used to round the result.

Return
`BigDecimal!`	`this / divisor` rounded according to the given rounding mode.

Exceptions
`java.lang.NullPointerException`	if `divisor == null` or `roundingMode == null`.
`java.lang.ArithmeticException`	if `roundingMode == RoundingMode.UNNECESSAR`Y and rounding is necessary according to the given scale and given precision.

divide

Added in API level 1

open fun divide(
    divisor: BigDecimal!, 
    roundingMode: Int
): BigDecimal!

Returns a new BigDecimal whose value is this / divisor. The scale of the result is the scale of this. If rounding is required to meet the specified scale, then the specified rounding mode roundingMode is applied.

Parameters
`divisor`	BigDecimal!: value by which `this` is divided.
`roundingMode`	Int: rounding mode to be used to round the result.

Return
`BigDecimal!`	`this / divisor` rounded according to the given rounding mode.

Exceptions
`java.lang.NullPointerException`	if `divisor == null`.
`java.lang.IllegalArgumentException`	if `roundingMode` is not a valid rounding mode.
`java.lang.ArithmeticException`	if `roundingMode == ROUND_UNNECESSARY` and rounding is necessary according to the scale of this.

divide

Added in API level 1

open fun divide(
    divisor: BigDecimal!, 
    roundingMode: RoundingMode!
): BigDecimal!

Parameters
`divisor`	BigDecimal!: value by which `this` is divided.
`roundingMode`	RoundingMode!: rounding mode to be used to round the result.

Return
`BigDecimal!`	`this / divisor` rounded according to the given rounding mode.

Exceptions
`java.lang.NullPointerException`	if `divisor == null` or `roundingMode == null`.
`java.lang.ArithmeticException`	if `roundingMode == RoundingMode.UNNECESSARY` and rounding is necessary according to the scale of this.

divide

Added in API level 1

open fun divide(divisor: BigDecimal!): BigDecimal!

Returns a new BigDecimal whose value is this / divisor. The scale of the result is the difference of the scales of this and divisor. If the exact result requires more digits, then the scale is adjusted accordingly. For example, 1/128 = 0.0078125 which has a scale of 7 and precision 5.

Parameters
`divisor`	BigDecimal!: value by which `this` is divided.

Return
`BigDecimal!`	`this / divisor`.

Exceptions
`java.lang.NullPointerException`	if `divisor == null`.
`java.lang.ArithmeticException`	if the result cannot be represented exactly.

divide

Added in API level 1

open fun divide(
    divisor: BigDecimal!, 
    mc: MathContext!
): BigDecimal!

Returns a new BigDecimal whose value is this / divisor. The result is rounded according to the passed context mc. If the passed math context specifies precision 0, then this call is equivalent to this.divide(divisor).

Parameters
`divisor`	BigDecimal!: value by which `this` is divided.
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Return
`BigDecimal!`	`this / divisor`.

Exceptions
`java.lang.NullPointerException`	if `divisor == null` or `mc == null`.
`java.lang.ArithmeticException`	if `mc.getRoundingMode() == UNNECESSARY` and rounding is necessary according `mc.getPrecision()`.

divideAndRemainder

Added in API level 1

open fun divideAndRemainder(divisor: BigDecimal!): Array<BigDecimal!>!

Parameters
`divisor`	BigDecimal!: value by which `this` is divided.

Return
`Array<BigDecimal!>!`	`[this.divideToIntegralValue(divisor), this.remainder(divisor)]`.

Exceptions
`java.lang.NullPointerException`	if `divisor == null`.
`java.lang.ArithmeticException`	if `divisor == 0`.

See Also

#divideToIntegralValue#remainder

divideAndRemainder

Added in API level 1

open fun divideAndRemainder(
    divisor: BigDecimal!, 
    mc: MathContext!
): Array<BigDecimal!>!

Returns a BigDecimal array which contains the integral part of this / divisor at index 0 and the remainder this % divisor at index 1. The quotient is rounded down towards zero to the next integer. The rounding mode passed with the parameter mc is not considered. But if the precision of mc > 0 and the integral part requires more digits, then an ArithmeticException is thrown.

Parameters
`divisor`	BigDecimal!: value by which `this` is divided.
`mc`	MathContext!: math context which determines the maximal precision of the result.

Return
`Array<BigDecimal!>!`	`[this.divideToIntegralValue(divisor), this.remainder(divisor)]`.

Exceptions
`java.lang.NullPointerException`	if `divisor == null`.
`java.lang.ArithmeticException`	if `divisor == 0`.

See Also

#divideToIntegralValue#remainder

divideToIntegralValue

Added in API level 1

open fun divideToIntegralValue(divisor: BigDecimal!): BigDecimal!

Returns a new BigDecimal whose value is the integral part of this / divisor. The quotient is rounded down towards zero to the next integer. For example, 0.5/0.2 = 2.

Parameters
`divisor`	BigDecimal!: value by which `this` is divided.

Return
`BigDecimal!`	integral part of `this / divisor`.

Exceptions
`java.lang.NullPointerException`	if `divisor == null`.
`java.lang.ArithmeticException`	if `divisor == 0`.

divideToIntegralValue

Added in API level 1

open fun divideToIntegralValue(
    divisor: BigDecimal!, 
    mc: MathContext!
): BigDecimal!

Returns a new BigDecimal whose value is the integral part of this / divisor. The quotient is rounded down towards zero to the next integer. The rounding mode passed with the parameter mc is not considered. But if the precision of mc > 0 and the integral part requires more digits, then an ArithmeticException is thrown.

Parameters
`divisor`	BigDecimal!: value by which `this` is divided.
`mc`	MathContext!: math context which determines the maximal precision of the result.

Return
`BigDecimal!`	integral part of `this / divisor`.

Exceptions
`java.lang.NullPointerException`	if `divisor == null` or `mc == null`.
`java.lang.ArithmeticException`	if `mc.getPrecision() > 0` and the result requires more digits to be represented.

equals

Added in API level 1

open fun equals(other: Any?): Boolean

Returns true if x is a BigDecimal instance and if this instance is equal to this big decimal. Two big decimals are equal if their unscaled value and their scale is equal. For example, 1.0 (10*10-1) is not equal to 1.00 (100*10-2). Similarly, zero instances are not equal if their scale differs.

Parameters
`obj`	the reference object with which to compare.

Return
`Boolean`	`true` if this object is the same as the obj argument; `false` otherwise.

hashCode

Added in API level 1

open fun hashCode(): Int

Returns a hash code for this BigDecimal.

Return
`Int`	hash code for `this`.

intValueExact

Added in API level 1

open fun intValueExact(): Int

Returns this BigDecimal as a int value if it has no fractional part and if its value fits to the int range ([-231..231-1]). If these conditions are not met, an ArithmeticException is thrown.

Exceptions
`java.lang.ArithmeticException`	if rounding is necessary or the number doesn't fit in an int.

longValueExact

Added in API level 1

open fun longValueExact(): Long

Returns this BigDecimal as a long value if it has no fractional part and if its value fits to the int range ([-263..263-1]). If these conditions are not met, an ArithmeticException is thrown.

Exceptions
`java.lang.ArithmeticException`	if rounding is necessary or the number doesn't fit in a long.

max

Added in API level 1

open fun max(val: BigDecimal!): BigDecimal!

Returns the maximum of this BigDecimal and val.

Parameters
`val`	BigDecimal!: value to be used to compute the maximum with this.

Return
`BigDecimal!`	`max(this, val`.

Exceptions
`java.lang.NullPointerException`	if `val == null`.

min

Added in API level 1

open fun min(val: BigDecimal!): BigDecimal!

Returns the minimum of this BigDecimal and val.

Parameters
`val`	BigDecimal!: value to be used to compute the minimum with this.

Return
`BigDecimal!`	`min(this, val`.

Exceptions
`java.lang.NullPointerException`	if `val == null`.

movePointLeft

Added in API level 1

open fun movePointLeft(n: Int): BigDecimal!

Returns a new BigDecimal instance where the decimal point has been moved n places to the left. If n < 0 then the decimal point is moved -n places to the right.

The result is obtained by changing its scale. If the scale of the result becomes negative, then its precision is increased such that the scale is zero.

Note, that movePointLeft(0) returns a result which is mathematically equivalent, but which has scale >= 0.

movePointRight

Added in API level 1

open fun movePointRight(n: Int): BigDecimal!

Returns a new BigDecimal instance where the decimal point has been moved n places to the right. If n < 0 then the decimal point is moved -n places to the left.

The result is obtained by changing its scale. If the scale of the result becomes negative, then its precision is increased such that the scale is zero.

Note, that movePointRight(0) returns a result which is mathematically equivalent, but which has scale >= 0.

multiply

Added in API level 1

open fun multiply(multiplicand: BigDecimal!): BigDecimal!

Returns a new BigDecimal whose value is this * multiplicand. The scale of the result is the sum of the scales of the two arguments.

Parameters
`multiplicand`	BigDecimal!: value to be multiplied with `this`.

Return
`BigDecimal!`	`this * multiplicand`.

Exceptions
`java.lang.NullPointerException`	if `multiplicand == null`.

multiply

Added in API level 1

open fun multiply(
    multiplicand: BigDecimal!, 
    mc: MathContext!
): BigDecimal!

Returns a new BigDecimal whose value is this * multiplicand. The result is rounded according to the passed context mc.

Parameters
`multiplicand`	BigDecimal!: value to be multiplied with `this`.
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Return
`BigDecimal!`	`this * multiplicand`.

Exceptions
`java.lang.NullPointerException`	if `multiplicand == null` or `mc == null`.

negate

Added in API level 1

open fun negate(): BigDecimal!

Returns a new BigDecimal whose value is the -this. The scale of the result is the same as the scale of this.

Return
`BigDecimal!`	`-this`

negate

Added in API level 1

open fun negate(mc: MathContext!): BigDecimal!

Returns a new BigDecimal whose value is the -this. The result is rounded according to the passed context mc.

Parameters
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Return
`BigDecimal!`	`-this`

plus

Added in API level 1

open fun plus(): BigDecimal!

Returns a new BigDecimal whose value is +this. The scale of the result is the same as the scale of this.

Return
`BigDecimal!`	`this`

plus

Added in API level 1

open fun plus(mc: MathContext!): BigDecimal!

Returns a new BigDecimal whose value is +this. The result is rounded according to the passed context mc.

Parameters
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Return
`BigDecimal!`	`this`, rounded

pow

Added in API level 1

open fun pow(n: Int): BigDecimal!

Returns a new BigDecimal whose value is thisn. The scale of the result is n * this.scale().

x.pow(0) returns 1, even if x == 0.

Implementation Note: The implementation is based on the ANSI standard X3.274-1996 algorithm.

Exceptions
`java.lang.ArithmeticException`	if `n < 0` or `n > 999999999`.

pow

Added in API level 1

open fun pow(
    n: Int, 
    mc: MathContext!
): BigDecimal!

Returns a new BigDecimal whose value is thisn. The result is rounded according to the passed context mc.

Implementation Note: The implementation is based on the ANSI standard X3.274-1996 algorithm.

Parameters
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Exceptions
`java.lang.ArithmeticException`	if `n < 0` or `n > 999999999`.

precision

Added in API level 1

open fun precision(): Int

Returns the precision of this BigDecimal. The precision is the number of decimal digits used to represent this decimal. It is equivalent to the number of digits of the unscaled value. The precision of 0 is 1 (independent of the scale).

Return
`Int`	the precision of this `BigDecimal`.

remainder

Added in API level 1

open fun remainder(divisor: BigDecimal!): BigDecimal!

Returns a new BigDecimal whose value is this % divisor.

The remainder is defined as this - this.divideToIntegralValue(divisor) * divisor.

Parameters
`divisor`	BigDecimal!: value by which `this` is divided.

Return
`BigDecimal!`	`this % divisor`.

Exceptions
`java.lang.NullPointerException`	if `divisor == null`.
`java.lang.ArithmeticException`	if `divisor == 0`.

remainder

Added in API level 1

open fun remainder(
    divisor: BigDecimal!, 
    mc: MathContext!
): BigDecimal!

Returns a new BigDecimal whose value is this % divisor.

The remainder is defined as this - this.divideToIntegralValue(divisor) * divisor.

The specified rounding mode mc is used for the division only.

Parameters
`divisor`	BigDecimal!: value by which `this` is divided.
`mc`	MathContext!: rounding mode and precision to be used.

Return
`BigDecimal!`	`this % divisor`.

Exceptions
`java.lang.NullPointerException`	if `divisor == null`.
`java.lang.ArithmeticException`	if `mc.getPrecision() > 0` and the result of `this.divideToIntegralValue(divisor, mc)` requires more digits to be represented.

round

Added in API level 1

open fun round(mc: MathContext!): BigDecimal!

Returns a new BigDecimal whose value is this, rounded according to the passed context mc.

If mc.precision = 0, then no rounding is performed.

If mc.precision > 0 and mc.roundingMode == UNNECESSARY, then an ArithmeticException is thrown if the result cannot be represented exactly within the given precision.

Parameters
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Return
`BigDecimal!`	`this` rounded according to the passed context.

Exceptions
`java.lang.ArithmeticException`	if `mc.precision > 0` and `mc.roundingMode == UNNECESSARY` and this cannot be represented within the given precision.

scale

Added in API level 1

open fun scale(): Int

Returns the scale of this BigDecimal. The scale is the number of digits behind the decimal point. The value of this BigDecimal is the unsignedValue * 10-scale. If the scale is negative, then this BigDecimal represents a big integer.

Return
`Int`	the scale of this `BigDecimal`.

scaleByPowerOfTen

Added in API level 1

open fun scaleByPowerOfTen(n: Int): BigDecimal!

Returns a new BigDecimal whose value is this * 10n. The scale of the result is this.scale() - n. The precision of the result is the precision of this.

This method has the same effect as movePointRight, except that the precision is not changed.

setScale

Added in API level 1

open fun setScale(
    newScale: Int, 
    roundingMode: RoundingMode!
): BigDecimal!

Returns a new BigDecimal instance with the specified scale.

If the new scale is greater than the old scale, then additional zeros are added to the unscaled value. In this case no rounding is necessary.

If the new scale is smaller than the old scale, then trailing digits are removed. If these trailing digits are not zero, then the remaining unscaled value has to be rounded. For this rounding operation the specified rounding mode is used.

Parameters
`newScale`	Int: scale of the result returned.
`roundingMode`	RoundingMode!: rounding mode to be used to round the result.

Return
`BigDecimal!`	a new `BigDecimal` instance with the specified scale.

Exceptions
`java.lang.NullPointerException`	if `roundingMode == null`.
`java.lang.ArithmeticException`	if `roundingMode == ROUND_UNNECESSARY` and rounding is necessary according to the given scale.

setScale

Added in API level 1

open fun setScale(
    newScale: Int, 
    roundingMode: Int
): BigDecimal!

Returns a new BigDecimal instance with the specified scale.

If the new scale is greater than the old scale, then additional zeros are added to the unscaled value. In this case no rounding is necessary.

Parameters
`newScale`	Int: scale of the result returned.
`roundingMode`	Int: rounding mode to be used to round the result.

Return
`BigDecimal!`	a new `BigDecimal` instance with the specified scale.

Exceptions
`java.lang.IllegalArgumentException`	if `roundingMode` is not a valid rounding mode.
`java.lang.ArithmeticException`	if `roundingMode == ROUND_UNNECESSARY` and rounding is necessary according to the given scale.

setScale

Added in API level 1

open fun setScale(newScale: Int): BigDecimal!

Returns a new BigDecimal instance with the specified scale. If the new scale is greater than the old scale, then additional zeros are added to the unscaled value. If the new scale is smaller than the old scale, then trailing zeros are removed. If the trailing digits are not zeros then an ArithmeticException is thrown.

If no exception is thrown, then the following equation holds: x.setScale(s).compareTo(x) == 0.

Parameters
`newScale`	Int: scale of the result returned.

Return
`BigDecimal!`	a new `BigDecimal` instance with the specified scale.

Exceptions
`java.lang.ArithmeticException`	if rounding would be necessary.

shortValueExact

Added in API level 1

open fun shortValueExact(): Short

Returns this BigDecimal as a short value if it has no fractional part and if its value fits to the short range ([-215..215-1]). If these conditions are not met, an ArithmeticException is thrown.

Exceptions
`java.lang.ArithmeticException`	if rounding is necessary of the number doesn't fit in a short.

signum

Added in API level 1

open fun signum(): Int

Returns the sign of this BigDecimal.

Return
`Int`	`-1` if `this < 0`, `0` if `this == 0`, `1` if `this > 0`.

stripTrailingZeros

Added in API level 1

open fun stripTrailingZeros(): BigDecimal!

Returns a new BigDecimal instance with the same value as this but with a unscaled value where the trailing zeros have been removed. If the unscaled value of this has n trailing zeros, then the scale and the precision of the result has been reduced by n.

Return
`BigDecimal!`	a new `BigDecimal` instance equivalent to this where the trailing zeros of the unscaled value have been removed.

subtract

Added in API level 1

open fun subtract(subtrahend: BigDecimal!): BigDecimal!

Returns a new BigDecimal whose value is this - subtrahend. The scale of the result is the maximum of the scales of the two arguments.

Parameters
`subtrahend`	BigDecimal!: value to be subtracted from `this`.

Return
`BigDecimal!`	`this - subtrahend`.

Exceptions
`java.lang.NullPointerException`	if `subtrahend == null`.

subtract

Added in API level 1

open fun subtract(
    subtrahend: BigDecimal!, 
    mc: MathContext!
): BigDecimal!

Returns a new BigDecimal whose value is this - subtrahend. The result is rounded according to the passed context mc.

Parameters
`subtrahend`	BigDecimal!: value to be subtracted from `this`.
`mc`	MathContext!: rounding mode and precision for the result of this operation.

Return
`BigDecimal!`	`this - subtrahend`.

Exceptions
`java.lang.NullPointerException`	if `subtrahend == null` or `mc == null`.

toBigInteger

Added in API level 1

open fun toBigInteger(): BigInteger!

Returns this BigDecimal as a big integer instance. A fractional part is discarded.

Return
`BigInteger!`	this `BigDecimal` as a big integer instance.

toBigIntegerExact

Added in API level 1

open fun toBigIntegerExact(): BigInteger!

Returns this BigDecimal as a big integer instance if it has no fractional part. If this BigDecimal has a fractional part, i.e. if rounding would be necessary, an ArithmeticException is thrown.

Return
`BigInteger!`	this `BigDecimal` as a big integer value.

Exceptions
`java.lang.ArithmeticException`	if rounding is necessary.

toDouble

Added in API level 1

open fun toDouble(): Double

Returns this BigDecimal as a double value. If this is too big to be represented as an float, then Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY is returned.

Note, that if the unscaled value has more than 53 significant digits, then this decimal cannot be represented exactly in a double variable. In this case the result is rounded.

For example, if the instance x1 = new BigDecimal("0.1") cannot be represented exactly as a double, and thus x1.equals(new BigDecimal(x1.doubleValue()) returns false for this case.

Similarly, if the instance new BigDecimal(9007199254740993L) is converted to a double, the result is 9.007199254740992E15.

Return
`Double`	this `BigDecimal` as a double value.

toEngineeringString

Added in API level 1

open fun toEngineeringString(): String!

Returns a string representation of this BigDecimal. This representation always prints all significant digits of this value.

If the scale is negative or if scale - precision >= 6 then engineering notation is used. Engineering notation is similar to the scientific notation except that the exponent is made to be a multiple of 3 such that the integer part is >= 1 and < 1000.

Return
`String!`	a string representation of `this` in engineering notation if necessary.

toFloat

Added in API level 1

open fun toFloat(): Float

Returns this BigDecimal as a float value. If this is too big to be represented as an float, then Float.POSITIVE_INFINITY or Float.NEGATIVE_INFINITY is returned.

Note, that if the unscaled value has more than 24 significant digits, then this decimal cannot be represented exactly in a float variable. In this case the result is rounded.

For example, if the instance x1 = new BigDecimal("0.1") cannot be represented exactly as a float, and thus x1.equals(new BigDecimal(x1.floatValue()) returns false for this case.

Similarly, if the instance new BigDecimal(16777217) is converted to a float, the result is 1.6777216E7.

Return
`Float`	this `BigDecimal` as a float value.

toInt

Added in API level 1

open fun toInt(): Int

Returns this BigDecimal as an int value. Any fractional part is discarded. If the integral part of this is too big to be represented as an int, then this % 232 is returned.

Return
`Int`	the numeric value represented by this object after conversion to type `int`.

toLong

Added in API level 1

open fun toLong(): Long

Returns this BigDecimal as an long value. Any fractional part is discarded. If the integral part of this is too big to be represented as an long, then this % 264 is returned.

Return
`Long`	the numeric value represented by this object after conversion to type `long`.

toPlainString

Added in API level 1

open fun toPlainString(): String!

Returns a string representation of this BigDecimal. No scientific notation is used. This methods adds zeros where necessary.

If this string representation is used to create a new instance, this instance is generally not identical to this as the precision changes.

x.equals(new BigDecimal(x.toPlainString()) usually returns false.

x.compareTo(new BigDecimal(x.toPlainString()) returns 0.

Return
`String!`	a string representation of `this` without exponent part.

toString

Added in API level 1

open fun toString(): String

Returns a canonical string representation of this BigDecimal. If necessary, scientific notation is used. This representation always prints all significant digits of this value.

If the scale is negative or if scale - precision >= 6 then scientific notation is used.

Return
`String`	a string representation of `this` in scientific notation if necessary.

ulp

Added in API level 1

open fun ulp(): BigDecimal!

Returns the unit in the last place (ULP) of this BigDecimal instance. An ULP is the distance to the nearest big decimal with the same precision.

The amount of a rounding error in the evaluation of a floating-point operation is often expressed in ULPs. An error of 1 ULP is often seen as a tolerable error.

For class BigDecimal, the ULP of a number is simply 10-scale. For example, new BigDecimal(0.1).ulp() returns 1E-55.

Return
`BigDecimal!`	unit in the last place (ULP) of this `BigDecimal` instance.

unscaledValue

Added in API level 1

open fun unscaledValue(): BigInteger!

Returns the unscaled value (mantissa) of this BigDecimal instance as a BigInteger. The unscaled value can be computed as this * 10scale.

valueOf

Added in API level 1

open static fun valueOf(
    unscaledVal: Long, 
    scale: Int
): BigDecimal!

Returns a new BigDecimal instance whose value is equal to unscaledVal * 10-scale). The scale of the result is scale, and its unscaled value is unscaledVal.

valueOf

Added in API level 1

open static fun valueOf(unscaledVal: Long): BigDecimal!

Returns a new BigDecimal instance whose value is equal to unscaledVal. The scale of the result is 0, and its unscaled value is unscaledVal.

Parameters
`unscaledVal`	Long: value to be converted to a `BigDecimal`.

Return
`BigDecimal!`	`BigDecimal` instance with the value `unscaledVal`.

valueOf

Added in API level 1

open static fun valueOf(val: Double): BigDecimal!

Returns a new BigDecimal instance whose value is equal to val. The new decimal is constructed as if the BigDecimal(String) constructor is called with an argument which is equal to Double.toString(val). For example, valueOf("0.1") is converted to (unscaled=1, scale=1), although the double 0.1 cannot be represented exactly as a double value. In contrast to that, a new BigDecimal(0.1) instance has the value 0.1000000000000000055511151231257827021181583404541015625 with an unscaled value 1000000000000000055511151231257827021181583404541015625 and the scale 55.

Parameters
`val`	Double: double value to be converted to a `BigDecimal`.

Return
`BigDecimal!`	`BigDecimal` instance with the value `val`.

Exceptions
`java.lang.NumberFormatException`	if `val` is infinite or `val` is not a number

Properties

ONE

Added in API level 1

static val ONE: BigDecimal!

The constant one as a BigDecimal.

TEN

Added in API level 1

static val TEN: BigDecimal!

The constant ten as a BigDecimal.

ZERO

Added in API level 1

static val ZERO: BigDecimal!

The constant zero as a BigDecimal.