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
BigDecimal is allowed to diverge due to difficulty
in efficiently computing both the decimal representation in
BigDecimal and the
binary representation in
When creating a
BigDecimal from a
Float, care must be taken as
the binary fraction representation of
Float does not easily
convert into a decimal representation. Three explicit schemes are available
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
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.
matches the decimal expansion of
BigDecimal.decimal(0.1) == 0.1.
Note that since
0.1f != 0.1, the same is not true for
0.1f == BigDecimal.decimal((0.1f).toDouble).
To test whether a
BigDecimal number can be converted to a
Float and then back without loss of information by using one of these
methods, test with
or the corresponding
Float versions. Note that
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
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
To create a
BigDecimal with a different precision than its
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.
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.
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.
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.POSITIVE_INFINITY as appropriate.
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.POSITIVE_INFINITY as appropriate.
Returns the hash code for this BigDecimal.
Note that this does not merely use the underlying java object's
hashCode because we compare
which deems 2 == 2.00, whereas in java these are unequal
hashCodes. These hash codes agree with
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
with large exponents.
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.
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.
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.
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
- Value Params
the end value of the range (exclusive)
the partially constructed NumericRange
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.