# W3cubDocs

/Scala 2.12 Library

# Class scala.math.BigDecimal

## final class BigDecimal extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[BigDecimal]

BigDecimal represents decimal floating-point numbers of arbitrary precision. By default, the precision approximately matches that of IEEE 128-bit floating point numbers (34 decimal digits, HALF_EVEN rounding mode). Within the range of IEEE binary128 numbers, BigDecimal will agree with BigInt for both equality and hash codes (and will agree with primitive types as well). Beyond that range--numbers with more than 4934 digits when written out in full--the hashCode of BigInt and BigDecimal is allowed to diverge due to difficulty in efficiently computing both the decimal representation in BigDecimal and the binary representation in BigInt.

When creating a BigDecimal from a Double or Float, care must be taken as the binary fraction representation of Double and Float does not easily convert into a decimal representation. Three explicit schemes are available for conversion. BigDecimal.decimal will convert the floating-point number to a decimal text representation, and build a BigDecimal based on that. BigDecimal.binary will expand the binary fraction to the requested or default precision. BigDecimal.exact will expand the binary fraction to the full number of digits, thus producing the exact decimal value corresponding to the binary fraction of that floating-point number. BigDecimal equality matches the decimal expansion of Double: BigDecimal.decimal(0.1) == 0.1. Note that since 0.1f != 0.1, the same is not true for Float. Instead, 0.1f == BigDecimal.decimal((0.1f).toDouble).

To test whether a BigDecimal number can be converted to a Double or Float and then back without loss of information by using one of these methods, test with isDecimalDouble, isBinaryDouble, or isExactDouble or the corresponding Float versions. Note that BigInt's isValidDouble will agree with isExactDouble, not the isDecimalDouble used by default.

BigDecimal uses the decimal representation of binary floating-point numbers to determine equality and hash codes. This yields different answers than conversion between Long and Double values, where the exact form is used. As always, since floating-point is a lossy representation, it is advisable to take care when assuming identity will be maintained across multiple conversions.

BigDecimal maintains a MathContext that determines the rounding that is applied to certain calculations. In most cases, the value of the BigDecimal is also rounded to the precision specified by the MathContext. To create a BigDecimal with a different precision than its MathContext, use new BigDecimal(new java.math.BigDecimal(...), mc). Rounding will be applied on those mathematical operations that can dramatically change the number of digits in a full representation, namely multiplication, division, and powers. The left-hand argument's MathContext always determines the degree of rounding, if any, and is the one propagated through arithmetic operations that do not apply rounding themselves.

Source
BigDecimal.scala
Linear Supertypes

## Value Members

### final def !=(arg0: Any): Boolean

Test two objects for inequality.

returns

true if !(this == that), false otherwise.

Definition Classes
AnyRef → Any

### final def ##(): Int

Equivalent to x.hashCode except for boxed numeric types and null. For numerics, it returns a hash value which is consistent with value equality: if two value type instances compare as true, then ## will produce the same hash value for each of them. For null returns a hashcode where null.hashCode throws a NullPointerException.

returns

a hash value consistent with ==

Definition Classes
AnyRef → Any

### def ->[B](y: B): (BigDecimal, B)

Implicit
This member is added by an implicit conversion from BigDecimal to ArrowAssoc[BigDecimal] performed by method ArrowAssoc in scala.Predef.
Definition Classes
ArrowAssoc
Annotations
()

### def /%(that: BigDecimal): (BigDecimal, BigDecimal)

Division and Remainder - returns tuple containing the result of divideToIntegralValue and the remainder. The computation is exact: no rounding is applied.

### def <(that: BigDecimal): Boolean

Returns true if this is less than that

Definition Classes
Ordered

### def <=(that: BigDecimal): Boolean

Returns true if this is less than or equal to that.

Definition Classes
Ordered

### final def ==(arg0: Any): Boolean

The expression x == that is equivalent to if (x eq null) that eq null else x.equals(that).

returns

true if the receiver object is equivalent to the argument; false otherwise.

Definition Classes
AnyRef → Any

### def >(that: BigDecimal): Boolean

Returns true if this is greater than that.

Definition Classes
Ordered

### def >=(that: BigDecimal): Boolean

Returns true if this is greater than or equal to that.

Definition Classes
Ordered

### final def asInstanceOf[T0]: T0

Cast the receiver object to be of type T0.

Note that the success of a cast at runtime is modulo Scala's erasure semantics. Therefore the expression 1.asInstanceOf[String] will throw a ClassCastException at runtime, while the expression List(1).asInstanceOf[List[String]] will not. In the latter example, because the type argument is erased as part of compilation it is not possible to check whether the contents of the list are of the requested type.

returns

Definition Classes
Any
Exceptions thrown

ClassCastException if the receiver object is not an instance of the erasure of type T0.

### def byteValue(): Byte

Converts this BigDecimal to a Byte. If the BigDecimal is too big to fit in a Byte, only the low-order 8 bits are returned. Note that this conversion can lose information about the overall magnitude of the BigDecimal value as well as return a result with the opposite sign.

Definition Classes
BigDecimalScalaNumericAnyConversions → Number

### def charValue: Char

Converts this BigDecimal to a Char. If the BigDecimal is too big to fit in a Char, only the low-order 16 bits are returned. Note that this conversion can lose information about the overall magnitude of the BigDecimal value and that it always returns a positive result.

### def clone(): AnyRef

Create a copy of the receiver object.

The default implementation of the clone method is platform dependent.

returns

a copy of the receiver object.

Attributes
protected[lang]
Definition Classes
AnyRef
Annotations
( ... ) ()
Note

not specified by SLS as a member of AnyRef

### def compare(that: BigDecimal): Int

Compares this BigDecimal with the specified BigDecimal

Definition Classes
BigDecimalOrdered

### def compareTo(that: BigDecimal): Int

Result of comparing this with operand that.

Definition Classes
Ordered → Comparable

### def doubleValue(): Double

Converts this BigDecimal to a Double. if this BigDecimal has too great a magnitude to represent as a double, it will be converted to Double.NEGATIVE_INFINITY or Double.POSITIVE_INFINITY as appropriate.

Definition Classes
BigDecimalScalaNumericAnyConversions → Number

### def ensuring(cond: (BigDecimal) ⇒ Boolean, msg: ⇒ Any): BigDecimal

Implicit
This member is added by an implicit conversion from BigDecimal to Ensuring[BigDecimal] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring

### def ensuring(cond: (BigDecimal) ⇒ Boolean): BigDecimal

Implicit
This member is added by an implicit conversion from BigDecimal to Ensuring[BigDecimal] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring

### def ensuring(cond: Boolean, msg: ⇒ Any): BigDecimal

Implicit
This member is added by an implicit conversion from BigDecimal to Ensuring[BigDecimal] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring

### def ensuring(cond: Boolean): BigDecimal

Implicit
This member is added by an implicit conversion from BigDecimal to Ensuring[BigDecimal] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring

### final def eq(arg0: AnyRef): Boolean

Tests whether the argument (that) is a reference to the receiver object (this).

The eq method implements an equivalence relation on non-null instances of AnyRef, and has three additional properties:

It is consistent: for any non-null instances x and y of type AnyRef, multiple invocations of x.eq(y) consistently returns true or consistently returns false.For any non-null instance x of type AnyRef, x.eq(null) and null.eq(x) returns false. null.eq(null) returns true.

When overriding the equals or hashCode methods, it is important to ensure that their behavior is consistent with reference equality. Therefore, if two objects are references to each other (o1 eq o2), they should be equal to each other (o1 == o2) and they should hash to the same value (o1.hashCode == o2.hashCode).

returns

true if the argument is a reference to the receiver object; false otherwise.

Definition Classes
AnyRef

### def equals(that: Any): Boolean

Compares this BigDecimal with the specified value for equality. Where Float and Double disagree, BigDecimal will agree with the Double value

that

the object to compare against this object for equality.

returns

true if the receiver object is equivalent to the argument; false otherwise.

Definition Classes
BigDecimal → AnyRef → Any

### def finalize(): Unit

Called by the garbage collector on the receiver object when there are no more references to the object.

The details of when and if the finalize method is invoked, as well as the interaction between finalize and non-local returns and exceptions, are all platform dependent.

Attributes
protected[lang]
Definition Classes
AnyRef
Annotations
( classOf[java.lang.Throwable] )
Note

not specified by SLS as a member of AnyRef

### def floatValue(): Float

Converts this BigDecimal to a Float. if this BigDecimal has too great a magnitude to represent as a float, it will be converted to Float.NEGATIVE_INFINITY or Float.POSITIVE_INFINITY as appropriate.

Definition Classes
BigDecimalScalaNumericAnyConversions → Number

### def formatted(fmtstr: String): String

Returns string formatted according to given format string. Format strings are as for String.format (@see java.lang.String.format).

Implicit
This member is added by an implicit conversion from BigDecimal to StringFormat[BigDecimal] performed by method StringFormat in scala.Predef.
Definition Classes
StringFormat
Annotations
()

### final def getClass(): Class[_]

Returns the runtime class representation of the object.

returns

a class object corresponding to the runtime type of the receiver.

Definition Classes
AnyRef → Any
Annotations
()

### def hashCode(): Int

Returns the hash code for this BigDecimal. Note that this does not merely use the underlying java object's hashCode because we compare BigDecimals with compareTo which deems 2 == 2.00, whereas in java these are unequal with unequal hashCodes. These hash codes agree with BigInt for whole numbers up ~4934 digits (the range of IEEE 128 bit floating point). Beyond this, hash codes will disagree; this prevents the explicit representation of the BigInt form for BigDecimal values with large exponents.

returns

the hash code value for this object.

Definition Classes
BigDecimal → AnyRef → Any

### def intValue(): Int

Converts this BigDecimal to an Int. If the BigDecimal is too big to fit in an Int, only the low-order 32 bits are returned. Note that this conversion can lose information about the overall magnitude of the BigDecimal value as well as return a result with the opposite sign.

Definition Classes
BigDecimalScalaNumericAnyConversions → Number

### final def isInstanceOf[T0]: Boolean

Test whether the dynamic type of the receiver object is T0.

Note that the result of the test is modulo Scala's erasure semantics. Therefore the expression 1.isInstanceOf[String] will return false, while the expression List(1).isInstanceOf[List[String]] will return true. In the latter example, because the type argument is erased as part of compilation it is not possible to check whether the contents of the list are of the specified type.

returns

true if the receiver object is an instance of erasure of type T0; false otherwise.

Definition Classes
Any

### def isValidByte: Boolean

Returns true iff this has a zero fractional part, and is within the range of scala.Byte MinValue and MaxValue; otherwise returns false.

Definition Classes
BigDecimalScalaNumericAnyConversions

### def isValidChar: Boolean

Returns true iff this has a zero fractional part, and is within the range of scala.Char MinValue and MaxValue; otherwise returns false.

Definition Classes
BigDecimalScalaNumericAnyConversions

### def isValidInt: Boolean

Returns true iff this has a zero fractional part, and is within the range of scala.Int MinValue and MaxValue; otherwise returns false.

Definition Classes
BigDecimalScalaNumericAnyConversions

### def isValidShort: Boolean

Returns true iff this has a zero fractional part, and is within the range of scala.Short MinValue and MaxValue; otherwise returns false.

Definition Classes
BigDecimalScalaNumericAnyConversions

### def isWhole(): Boolean

returns

true if this number has no decimal component, false otherwise.

Definition Classes
BigDecimalScalaNumericAnyConversions → ScalaNumber

### def longValue(): Long

Converts this BigDecimal to a Long. If the BigDecimal is too big to fit in a Long, only the low-order 64 bits are returned. Note that this conversion can lose information about the overall magnitude of the BigDecimal value as well as return a result with the opposite sign.

Definition Classes
BigDecimalScalaNumericAnyConversions → Number

### final def ne(arg0: AnyRef): Boolean

Equivalent to !(this eq that).

returns

true if the argument is not a reference to the receiver object; false otherwise.

Definition Classes
AnyRef

### final def notify(): Unit

Wakes up a single thread that is waiting on the receiver object's monitor.

Definition Classes
AnyRef
Annotations
()
Note

not specified by SLS as a member of AnyRef

### final def notifyAll(): Unit

Wakes up all threads that are waiting on the receiver object's monitor.

Definition Classes
AnyRef
Annotations
()
Note

not specified by SLS as a member of AnyRef

### def shortValue(): Short

Converts this BigDecimal to a Short. If the BigDecimal is too big to fit in a Short, only the low-order 16 bits are returned. Note that this conversion can lose information about the overall magnitude of the BigDecimal value as well as return a result with the opposite sign.

Definition Classes
BigDecimalScalaNumericAnyConversions → Number

### final def synchronized[T0](arg0: ⇒ T0): T0

Definition Classes
AnyRef

### def toByte: Byte

Returns the value of this as a scala.Byte. This may involve rounding or truncation.

Definition Classes
ScalaNumericAnyConversions

### def toByteExact: Byte

Converts this BigDecimal to a scala.Byte, checking for lost information. If this BigDecimal has a nonzero fractional part, or is out of the possible range for a scala.Byte result, then a java.lang.ArithmeticException is thrown.

### def toChar: Char

Returns the value of this as a scala.Char. This may involve rounding or truncation.

Definition Classes
ScalaNumericAnyConversions

### def toDouble: Double

Returns the value of this as a scala.Double. This may involve rounding or truncation.

Definition Classes
ScalaNumericAnyConversions

### def toFloat: Float

Returns the value of this as a scala.Float. This may involve rounding or truncation.

Definition Classes
ScalaNumericAnyConversions

### def toInt: Int

Returns the value of this as an scala.Int. This may involve rounding or truncation.

Definition Classes
ScalaNumericAnyConversions

### def toIntExact: Int

Converts this BigDecimal to a scala.Int, checking for lost information. If this BigDecimal has a nonzero fractional part, or is out of the possible range for an scala.Int result, then a java.lang.ArithmeticException is thrown.

### def toLong: Long

Returns the value of this as a scala.Long. This may involve rounding or truncation.

Definition Classes
ScalaNumericAnyConversions

### def toLongExact: Long

Converts this BigDecimal to a scala.Long, checking for lost information. If this BigDecimal has a nonzero fractional part, or is out of the possible range for a scala.Long result, then a java.lang.ArithmeticException is thrown.

### def toShort: Short

Returns the value of this as a scala.Short. This may involve rounding or truncation.

Definition Classes
ScalaNumericAnyConversions

### def toShortExact: Short

Converts this BigDecimal to a scala.Short, checking for lost information. If this BigDecimal has a nonzero fractional part, or is out of the possible range for a scala.Short result, then a java.lang.ArithmeticException is thrown.

### def toString(): String

Returns the decimal String representation of this BigDecimal.

returns

a String representation of the object.

Definition Classes
BigDecimal → AnyRef → Any

### def underlying(): java.math.BigDecimal

Definition Classes
BigDecimalScalaNumericConversionsScalaNumericAnyConversions → ScalaNumber

### def unifiedPrimitiveEquals(x: Any): Boolean

Should only be called after all known non-primitive types have been excluded. This method won't dispatch anywhere else after checking against the primitives to avoid infinite recursion between equals and this on unknown "Number" variants.

Additionally, this should only be called if the numeric type is happy to be converted to Long, Float, and Double. If for instance a BigInt much larger than the Long range is sent here, it will claim equality with whatever Long is left in its lower 64 bits. Or a BigDecimal with more precision than Double can hold: same thing. There's no way given the interface available here to prevent this error.

Attributes
protected
Definition Classes
ScalaNumericAnyConversions

### def unifiedPrimitiveHashcode(): Int

Attributes
protected
Definition Classes
ScalaNumericAnyConversions

### def until(end: BigDecimal): Partial[BigDecimal, Exclusive[BigDecimal]]

Creates a partially constructed NumericRange[BigDecimal] in range [start;end), where start is the target BigDecimal. The step must be supplied via the "by" method of the returned object in order to receive the fully constructed range. For example:

val partial = BigDecimal(1.0) to 2.0       // not usable yet
val range = partial by 0.01                // now a NumericRange
val range2 = BigDecimal(0) to 1.0 by 0.01  // all at once of course is fine too
end

the end value of the range (exclusive)

returns

the partially constructed NumericRange

### final def wait(): Unit

Definition Classes
AnyRef
Annotations
( ... )

### final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
( ... )

### final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
( ... ) ()

### def →[B](y: B): (BigDecimal, B)

Implicit
This member is added by an implicit conversion from BigDecimal to ArrowAssoc[BigDecimal] performed by method ArrowAssoc in scala.Predef.
Definition Classes
ArrowAssoc

### def +(other: String): String

Implicit
This member is added by an implicit conversion from BigDecimal to any2stringadd[BigDecimal] performed by method any2stringadd in scala.Predef.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
Definition Classes

### def <(that: BigDecimal): Boolean

Returns true if this is less than that

Implicit
This member is added by an implicit conversion from BigDecimal to Ordered[BigDecimal] performed by method orderingToOrdered in scala.math.Ordered.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
(bigDecimal: Ordered[BigDecimal]).<(that)
Definition Classes
Ordered

### def <=(that: BigDecimal): Boolean

Returns true if this is less than or equal to that.

Implicit
This member is added by an implicit conversion from BigDecimal to Ordered[BigDecimal] performed by method orderingToOrdered in scala.math.Ordered.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
(bigDecimal: Ordered[BigDecimal]).<=(that)
Definition Classes
Ordered

### def >(that: BigDecimal): Boolean

Returns true if this is greater than that.

Implicit
This member is added by an implicit conversion from BigDecimal to Ordered[BigDecimal] performed by method orderingToOrdered in scala.math.Ordered.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
(bigDecimal: Ordered[BigDecimal]).>(that)
Definition Classes
Ordered

### def >=(that: BigDecimal): Boolean

Returns true if this is greater than or equal to that.

Implicit
This member is added by an implicit conversion from BigDecimal to Ordered[BigDecimal] performed by method orderingToOrdered in scala.math.Ordered.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
(bigDecimal: Ordered[BigDecimal]).>=(that)
Definition Classes
Ordered

### def compare(that: BigDecimal): Int

Result of comparing this with operand that.

Implement this method to determine how instances of A will be sorted.

Returns x where:

x < 0 when this < that x == 0 when this == that x > 0 when this > that
Implicit
This member is added by an implicit conversion from BigDecimal to Ordered[BigDecimal] performed by method orderingToOrdered in scala.math.Ordered.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
(bigDecimal: Ordered[BigDecimal]).compare(that)
Definition Classes
Ordered

### def compareTo(that: BigDecimal): Int

Result of comparing this with operand that.

Implicit
This member is added by an implicit conversion from BigDecimal to Ordered[BigDecimal] performed by method orderingToOrdered in scala.math.Ordered.