decimal.js-light

The light version of decimal.js, an arbitrary-precision Decimal type for JavaScript.

Hosted on GitHub.

The library is incorporated into this page, so it should be available in the console now.

API

See the README on GitHub for a quick-start introduction.

In all examples below, var and semicolons are not shown, and if a commented-out value is in quotes it means toString has been called on the preceding expression.

When the library is loaded, it defines a single function object, Decimal, the constructor of Decimal instances.

If necessary, multiple Decimal constructors can be created, each with their own independent configuration, e.g. precision and range, which applies to all Decimal instances created from it.

A new Decimal constructor is created by calling the clone method of an already existing Decimal constructor.

CONSTRUCTOR

DecimalDecimal(value) ⇒ Decimal

value: number|string|Decimal

Integer or float.

The number of digits is not limited, except by JavaScript's maximum array size and, in practice, the processing time required.

The maximum permissible exponent magnitude is approximately 9007199254740991.

String values may be in exponential (floating-point), as well as normal (fixed-point) notation.

In exponential notation, e or E defines a power-of-ten exponent.

Returns a new Decimal object instance.

Throws on an invalid value.

x = new Decimal(9)                       // '9'
y = new Decimal(x)                       // '9'

new Decimal('5032485723458348569331745.33434346346912144534543')
new Decimal('4.321e+4')                  // '43210'
new Decimal('-735.0918e-430')            // '-7.350918e-428'
new Decimal('5.6700000')                 // '5.67'
new Decimal('.5')                        // '0.5'

new Decimal(0.046875)                    // '0.046875'
new Decimal('0.046875000000')            // '0.046875'

new Decimal(4.6875e-2)                   // '0.046875'
new Decimal('468.75e-4')                 // '0.046875'

Methods

The methods of a Decimal constructor.

clone .clone([object]) ⇒ Decimal constructor

object: object

Returns a new independent Decimal constructor with configuration settings as described by object (see config), or with the same settings as this Decimal constructor if object is omitted.

Decimal.config({ precision: 5 })
D9 = Decimal.clone({ precision: 9 })

a = new Decimal(1)
b = new D9(1)

a.div(3)                           // 0.33333
b.div(3)                           // 0.333333333

// D9 = Decimal.clone({ precision: 9 }) is equivalent to:
D9 = Decimal.clone()
D9.config({ precision: 9 })

It is not inefficient in terms of memory usage to use multiple Decimal constructors as functions are shared between them.

config.set(object) ⇒ Decimal constructor

object: object

Configures the 'global' settings for this particular Decimal constructor, i.e. the settings which apply to operations performed on the Decimal instances created by it.

Returns this Decimal constructor.

The configuration object, object, can contain some or all of the properties described in detail at Properties and shown in the example below.

The values of the configuration object properties are checked for validity and then stored as equivalently-named properties of this Decimal constructor.

Throws on an invalid object or configuration property value.

// Defaults
Decimal.config({
    precision: 20,
    rounding: 4,
    toExpNeg: -7,
    toExpPos: 21,
    LN10: new Decimal('2.30258509299404568401799145468436...')
})

Decimal.set({ rounding: Decimal.ROUND_CEIL })

The properties of a Decimal constructor can also be set by direct assignment, but that will by-pass the validity checking that this method performs - which is not a problem if the user knows that the checks are unnecessary.

Properties

The properties of a Decimal constructor.

Configuration properties

The values of the configuration properties precision, rounding, toExpNeg and toExpPos are set using the config method.

As simple object properties they can be set directly without using config, and it is fine to do so, but the values assigned will not then be checked for validity. For example:

Decimal.config({ precision: 0 })
// '[DecimalError] Invalid argument: precision: 0'

Decimal.precision = 0
// No error is thrown and the results of calculations are unreliable

precision

number: integer, 1 to 1e+9 inclusive
Default value: 20

The maximum number of significant digits of the result of an operation.

All functions which return a Decimal will return the value to precision significant digits except Decimal, absoluteValue, negated, toInteger, and toDecimalPlaces.

Decimal.config({ precision: 5 })
Decimal.precision                  // 5

rounding

number: integer, 0 to 8 inclusive
Default value: 4 (ROUND_HALF_UP)

The default rounding mode used by toInteger, toDecimalPlaces, toExponential, toFixed, toPrecision and toSignificantDigits.

The rounding modes are available as enumerated properties of the constructor.

Decimal.config({ rounding: Decimal.ROUND_UP })
Decimal.config({ rounding: 0 })    // equivalent
Decimal.rounding                   // 0

toExpNeg

number: integer, -9e15 to 0 inclusive
Default value: -7

The negative exponent value at and below which toString returns exponential notation.

Decimal.config({ toExpNeg: -7 })
Decimal.toExpNeg                   // -7
new Decimal(0.00000123)            // '0.00000123'       e is -6
new Decimal(0.000000123)           // '1.23e-7'

// Always return exponential notation:
Decimal.config({ toExpNeg: 0 })

JavaScript numbers use exponential notation for negative exponents of -7 and below.

Regardless of the value of toExpNeg, the toFixed method will always return a value in normal notation and the toExponential method will always return a value in exponential form.

toExpPos

number: integer, 0 to 9e15 inclusive
Default value: 20

The positive exponent value at and above which toString returns exponential notation.

Decimal.config({ toExpPos: 2 })
Decimal.toExpPos                   // 2
new Decimal(12.3)                  // '12.3'        e is 1
new Decimal(123)                   // '1.23e+2'

// Always return exponential notation:
Decimal.config({ toExpPos: 0 })

JavaScript numbers use exponential notation for positive exponents of 20 and above.

Regardless of the value of toExpPos, the toFixed method will always return a value in normal notation and the toExponential method will always return a value in exponential form.

LN10

string|Decimal: the natural logarithm of 10
The default value has 115 digits

The maximum precision of the naturalExponential, naturalLogarithm, logarithm, and toPower methods is determined by the precision of the value of LN10.

The default value of LN10 enables a maximum precision of about 100 digits. To increase this, assign a new value to LN10 using a string or Decimal value with about 15 digits more than the maximum precision required.

An error will be thrown if the LN10 value does not have sufficient precision to enable an operation to be performed.

Decimal.config({ LN10: '2.3025850929940456840179914546843642076011014886287729760333279009' })

Decimal.LN10.toFixed(5)             // ''2.30259'

Rounding modes

The library's enumerated rounding modes are stored as properties of the Decimal constructor.
They are not referenced internally by the library itself.

Rounding modes 0 to 6 (inclusive) are the same as those of Java's BigDecimal class.

Property	Value	Description
ROUND_UP	0	Rounds away from zero
ROUND_DOWN	1	Rounds towards zero
ROUND_CEIL	2	Rounds towards Infinity
ROUND_FLOOR	3	Rounds towards -Infinity
ROUND_HALF_UP	4	Rounds towards nearest neighbour. If equidistant, rounds away from zero
ROUND_HALF_DOWN	5	Rounds towards nearest neighbour. If equidistant, rounds towards zero
ROUND_HALF_EVEN	6	Rounds towards nearest neighbour. If equidistant, rounds towards even neighbour
ROUND_HALF_CEIL	7	Rounds towards nearest neighbour. If equidistant, rounds towards Infinity
ROUND_HALF_FLOOR	8	Rounds towards nearest neighbour. If equidistant, rounds towards -Infinity

Decimal.config({ rounding: Decimal.ROUND_CEIL })
Decimal.config({ rounding: 2 })    // equivalent
Decimal.rounding                   // 2

INSTANCE

Methods

The methods inherited by a Decimal instance from its constructor's prototype object.

A Decimal instance is immutable in the sense that it is not changed by its methods.

Methods that return a Decimal can be chained:

x = new Decimal(2).times('999.999999999999999').dividedBy(4).toFixed(2)

Methods do not round their arguments before execution.

Many method names have a shorter alias. (Internally, the library always uses the shorter method names.)

absoluteValue.abs() ⇒ Decimal

Returns a new Decimal whose value is the absolute value, i.e. the magnitude, of the value of this Decimal.

The return value is not affected by the value of the precision setting.

x = new Decimal(-0.8)
y = x.absoluteValue()         // '0.8'
z = y.abs()                   // '0.8'

comparedTo.cmp(x) ⇒ number

x: number|string|Decimal

Returns
1	if the value of this Decimal is greater than the value of x
-1	if the value of this Decimal is less than the value of x
0	if this Decimal and x have the same value

x = new Decimal(4)
y = new Decimal(5)
x.comparedTo(y)                // -1
x.comparedTo(x.plus(1))        // 0

decimalPlaces.dp() ⇒ number

Returns the number of decimal places, i.e. the number of digits after the decimal point, of the value of this Decimal.

x = new Decimal(1.234)
x.decimalPlaces()              // '3'
y = new Decimal(987.654321)
y.dp()                         // '6'

dividedBy.div(x) ⇒ Decimal

x: number|string|Decimal

Returns a new Decimal whose value is the value of this Decimal divided by x, truncated to precision significant digits.

x = new Decimal(355)
y = new Decimal(113)
x.dividedBy(y)             // '3.14159292035398230088'
x.div(5)                   // '71'

dividedToIntegerBy.idiv(x) ⇒ Decimal

x: number|string|Decimal

Return a new Decimal whose value is the integer part of dividing this Decimal by x, truncated to precision significant digits.

x = new Decimal(5)
y = new Decimal(3)
x.dividedToIntegerBy(y)     // '1'
x.idiv(0.7)             // '7'

equals.eq(x) ⇒ boolean

x: number|string|Decimal

Returns true if the value of this Decimal equals the value of x, otherwise returns false.

Note: This method uses the cmp method internally.

0 === 1e-324                     // true
x = new Decimal(0)
x.equals('1e-324')               // false

exponent.exponent() ⇒ number

Returns the exponent value of this Decimal.

x = new Decimal(1234.567)
x.exponent()                     // 3

greaterThan.gt(x) ⇒ boolean

x: number|string|Decimal

Returns true if the value of this Decimal is greater than the value of x, otherwise returns false.

Note: This method uses the cmp method internally.

0.1 > (0.3 - 0.2)                            // true
x = new Decimal(0.1)
x.greaterThan(Decimal(0.3).minus(0.2))       // false
new Decimal(0).gt(x)                         // false

greaterThanOrEqualTo.gte(x) ⇒ boolean

x: number|string|Decimal

Returns true if the value of this Decimal is greater than or equal to the value of x, otherwise returns false.

Note: This method uses the cmp method internally.

(0.3 - 0.2) >= 0.1                       // false
x = new Decimal(0.3).minus(0.2)
x.greaterThanOrEqualTo(0.1)              // true
new Decimal(1).gte(x)                    // true

isInteger.isint() ⇒ boolean

Returns true if the value of this Decimal is a whole number, otherwise returns false.

x = new Decimal(1)
x.isInteger()                            // true
y = new Decimal(123.456)
y.isint()                                // false

isNegative.isneg() ⇒ boolean

Returns true if the value of this Decimal is negative, otherwise returns false.

x = new Decimal(0)
x.isNegative()                           // false
y = new Decimal(2)
y.isneg                                  // false

Note: n < 0 can be used if n <= -Number.MIN_VALUE.

isPositive.ispos() ⇒ boolean

Returns true if the value of this Decimal is positive, otherwise returns false.

x = new Decimal(0)
x.isPositive()                           // false
y = new Decimal(-2)
y.ispos                                  // false

Note: n < 0 can be used if n <= -Number.MIN_VALUE.

isZero.isZero() ⇒ boolean

Returns true if the value of this Decimal is zero or minus zero, otherwise returns false.

x = new Decimal(0)
x.isZero()                               // true

Note: n == 0 can be used if n >= Number.MIN_VALUE.

lessThan.lt(x) ⇒ boolean

x: number|string|Decimal

Returns true if the value of this Decimal is less than the value of x, otherwise returns false.

Note: This method uses the cmp method internally.

(0.3 - 0.2) < 0.1                        // true
x = new Decimal(0.3).minus(0.2)
x.lessThan(0.1)                          // false
new Decimal(0).lt(x)                     // true

lessThanOrEqualTo.lte(x) ⇒ boolean

x: number|string|Decimal

Returns true if the value of this Decimal is less than or equal to the value of x, otherwise returns false.

Note: This method uses the cmp method internally.

0.1 <= (0.3 - 0.2)                              // false
x = new Decimal(0.1)
x.lessThanOrEqualTo(Decimal(0.3).minus(0.2))    // true
new Decimal(-1).lte(x)                          // true

logarithm.log(x) ⇒ Decimal

x: number|string|Decimal

Returns a new Decimal whose value is the base x logarithm of the value of this Decimal, truncated to precision significant digits.

If x is omitted, the base 10 logarithm of the value of this Decimal will be returned.

x = new Decimal(1000)
x.logarithm()                            // '3'
y = new Decimal(256)
y.log(2)                                 // '8'

The maximum error will be 1 ulp (unit in the last place).

Logarithms to base 2 or 10 will always be correct.

The performance of this method degrades exponentially with increasing digits.

minus.minus(x) ⇒ Decimal

x: number|string|Decimal

Returns a new Decimal whose value is the value of this Decimal minus x, truncated to precision significant digits.

0.3 - 0.1                                // 0.19999999999999998
x = new Decimal(0.3)
x.minus(0.1)                             // '0.2'

modulo.mod(x) ⇒ Decimal

x: number|string|Decimal

Returns a new Decimal whose value is the value of this Decimal modulo x, truncated to precision significant digits.

1 % 0.9                                  // 0.09999999999999998
x = new Decimal(1)
y = x.modulo(0.9)                            // '0.1'

naturalExponential.exp() ⇒ Decimal

Returns a new Decimal whose value is the base e (Euler's number, the base of the natural logarithm) exponential of the value of this Decimal, truncated to precision significant digits.

The naturalLogarithm function is the inverse of this function.

x = new Decimal(1)
x.naturalExponential()                   // '2.7182818284590452354'
y = new Decimal(2)
y.exp()                                  // '7.3890560989306502272'

The maximum error will be 1 ulp (unit in the last place).

The performance of this method degrades exponentially with increasing digits.

naturalLogarithm.ln() ⇒ Decimal

Returns a new Decimal whose value is the natural logarithm of the value of this Decimal, truncated to precision significant digits.

The natural logarithm is the inverse of the naturalExponential function.

x = new Decimal(10)
x.naturalLogarithm()                     // '2.3026'
y = new Decimal('1.23e+30')
y.ln()                                   // '69.28'

The mathematical result of the natural logarithm function is non-terminating, unless its argument is 1.

The time-taken by this method increases exponentially with increasing digits.

See LN10 to configure the maximum precision available.

negated.neg() ⇒ Decimal

Returns a new Decimal whose value is the value of this Decimal negated, i.e. multiplied by -1.

The return value is not affected by the value of the precision setting.

x = new Decimal(1.8)
x.negated()                              // '-1.8'
y = new Decimal(-1.3)
y.neg()                                  // '1.3'

plus.plus(x) ⇒ Decimal

x: number|string|Decimal

Returns a new Decimal whose value is the value of this Decimal plus x, truncated to precision significant digits.

0.1 + 0.2                                // 0.30000000000000004
x = new Decimal(0.1)
y = x.plus(0.2)                          // '0.3'
new Decimal(0.7).plus(x).plus(y)         // '1.1'

precision.sd([include_zeros]) ⇒ number

Returns the number of significant digits of the value of this Decimal.

If include_zeros is true or 1 then any trailing zeros of the integer part of a number are counted as significant digits, otherwise they are not.

x = new Decimal(1.234)
x.precision()                            // '4'
y = new Decimal(987000)
y.sd()                                   // '3'
y.sd(true)                               // '6'

squareRoot.sqrt() ⇒ Decimal

Returns a new Decimal whose value is the square root of this Decimal, truncated to precision significant digits.

This method is much faster than using the toPower method with an exponent of 0.5.

x = new Decimal(16)
x.squareRoot()                           // '4'
y = new Decimal(3)
y.sqrt()                                 // '1.73205080756887729353'
y.sqrt().eq( y.pow(0.5) )                // true

times.times(x) ⇒ Decimal

x: number|string|Decimal

Returns a new Decimal whose value is the value of this Decimal times x, truncated to precision significant digits.

0.6 * 3                                  // 1.7999999999999998
x = new Decimal(0.6)
y = x.times(3)                           // '1.8'
new Decimal('7e+500').times(y)           // '1.26e+501'

toDecimalPlaces.todp([dp [, rm]]) ⇒ Decimal

dp: number: integer, 0 to 1e+9 inclusive
rm: number: integer, 0 to 8 inclusive.

Returns a new Decimal whose value is the value of this Decimal rounded to a maximum of dp decimal places using rounding mode rm.

If dp is omitted, the return value will have the same value as this Decimal.

If rm is omitted, rounding mode rounding is used.

Throws on an invalid dp or rm value.

x = new Decimal(12.24567)
x.toDecimalPlaces(0)                // '12'
x.toDecimalPlaces(1, 0)             // '12.3'

y = new Decimal(9876.54321)
y.todp(3)                           // '9876.543'
y.todp(1, 0)                        // '9876.6'
y.todp(1, Decimal.ROUND_DOWN)       // '9876.5'

toExponential.toExponential([dp [, rm]]) ⇒ string

dp: number: integer, 0 to 1e+9 inclusive
rm: number: integer, 0 to 8 inclusive

Returns a string representing the value of this Decimal in exponential notation rounded using rounding mode rm to dp decimal places, i.e with one digit before the decimal point and dp digits after it.

If the value of this Decimal in exponential notation has fewer than dp fraction digits, the return value will be appended with zeros accordingly.

If dp is omitted, the number of digits after the decimal point defaults to the minimum number of digits necessary to represent the value exactly.

If rm is omitted, rounding mode rounding is used.

Throws on an invalid dp or rm value.

x = 45.6
y = new Decimal(x)
x.toExponential()              // '4.56e+1'
y.toExponential()              // '4.56e+1'
x.toExponential(0)             // '5e+1'
y.toExponential(0)             // '5e+1'
x.toExponential(1)             // '4.6e+1'
y.toExponential(1)             // '4.6e+1'
y.toExponential(1, 1)          // '4.5e+1'  (ROUND_DOWN)
x.toExponential(3)             // '4.560e+1'
y.toExponential(3)             // '4.560e+1'

toFixed.toFixed([dp [, rm]]) ⇒ string

dp: number: integer, 0 to 1e+9 inclusive
rm: number: integer, 0 to 8 inclusive

Returns a string representing the value of this Decimal in normal (fixed-point) notation rounded to dp decimal places using rounding mode rm.

If the value of this Decimal in normal notation has fewer than dp fraction digits, the return value will be appended with zeros accordingly.

Unlike Number.prototype.toFixed, which returns exponential notation if a number is greater or equal to 1021, this method will always return normal notation.

If dp is omitted, the return value will be unrounded and in normal notation. This is unlike Number.prototype.toFixed, which returns the value to zero decimal places, but is useful when because of the current toExpNeg or toExpNeg values, toString returns exponential notation.

If rm is omitted, rounding mode rounding is used.

Throws on an invalid dp or rm value.

x = 3.456
y = new Decimal(x)
x.toFixed()              // '3'
y.toFixed()              // '3.456'
y.toFixed(0)             // '3'
x.toFixed(2)             // '3.46'
y.toFixed(2)             // '3.46'
y.toFixed(2, 1)          // '3.45'  (ROUND_DOWN)
x.toFixed(5)             // '3.45600'
y.toFixed(5)             // '3.45600'

toInteger.toint() ⇒ Decimal

Returns a new Decimal whose value is the value of this Decimal rounded to a whole number using rounding mode rounding.

To emulate Math.round, set rounding to 7, i.e. ROUND_HALF_CEIL.

Decimal.config({ rounding: 4 })
x = 1234.5
x.toInteger()                            // '1235'

Decimal.rounding = Decimal.ROUND_DOWN
x.toint()                                // '1234'
x                                        // '1234.5'

toJSON.toJSON() ⇒ string

As toString.

toNumber.toNumber() ⇒ number

Returns the value of this Decimal converted to a primitive number.

Type coercion with, for example, JavaScript's unary plus operator will also work, except that a Decimal with the value minus zero will convert to positive zero.

x = new Decimal(456.789)
x.toNumber()                   // 456.789
+x                             // 456.789

y = new Decimal('45987349857634085409857349856430985')
y.toNumber()                   // 4.598734985763409e+34

toPower.pow(x) ⇒ Decimal

x: number|string|Decimal: integer or non-integer

Returns a new Decimal whose value is the value of this Decimal raised to the power x, truncated to precision significant digits.

The performance of this method degrades exponentially with increasing digits.
For non-integer exponents in particular, the performance of this method may not be adequate.

The maximum error will be 1 ulp (unit in the last place).

Math.pow(0.7, 2)               // 0.48999999999999994
x = new Decimal(0.7)
x.toPower(2)                   // '0.49'
new Decimal(3).pow(-2)         // '0.11111111111111111111'

new Decimal(1217652.23).pow('98765.489305603941')
// '4.8227010515242461181e+601039'

toPrecision.toPrecision([sd [, rm]]) ⇒ string

sd: number: integer, 1 to 1e+9 inclusive
rm: number: integer, 0 to 8 inclusive

Returns a string representing the value of this Decimal rounded to sd significant digits using rounding mode rm.

If sd is less than the number of digits necessary to represent the integer part of the value in normal (fixed-point) notation, then exponential notation is used.

If sd is omitted, the return value is the same as toString.

If rm is omitted, rounding mode rounding is used.

Throws on an invalid sd or rm value.

x = 45.6
y = new Decimal(x)
x.toPrecision()                          // '45.6'
y.toPrecision()                          // '45.6'
x.toPrecision(1)                         // '5e+1'
y.toPrecision(1)                         // '5e+1'
y.toPrecision(2, 0)                      // '4.6e+1'  (ROUND_UP)
y.toPrecision(2, 1)                      // '4.5e+1'  (ROUND_DOWN)
x.toPrecision(5)                         // '45.600'
y.toPrecision(5)                         // '45.600'

toSignificantDigits.tosd([sd [, rm]]) ⇒ Decimal

sd: number: integer, 1 to 1e+9 inclusive.
rm: number: integer, 0 to 8 inclusive.

Returns a new Decimal whose value is the value of this Decimal rounded to a maximum of sd significant digits using rounding mode rm.

If sd is omitted, the return value will be rounded to precision significant digits.

If rm is omitted, rounding mode rounding will be used.

Throws on an invalid sd or rm value.

Decimal.config({ precision: 5, rounding: 4 })
x = new Decimal(9876.54321)

x.toSignificantDigits()                          // '9876.5'
x.toSignificantDigits(6)                         // '9876.54'
x.toSignificantDigits(6, Decimal.ROUND_UP)       // '9876.55'
x.tosd(2)                                        // '9900'
x.tosd(2, 1)                                     // '9800'
x                                                // '9876.54321'

toString.toString() ⇒ string

Returns a string representing the value of this Decimal.

If this Decimal has a positive exponent that is equal to or greater than toExpPos, or a negative exponent equal to or less than toExpNeg, then exponential notation will be returned.

x = new Decimal(750000)
x.toString()                             // '750000'
Decimal.config({ toExpPos: 5 })
x.toString()                             // '7.5e+5'

Decimal.config({ precision: 4 });
y = new Decimal('1.23456789')
y.toString()                             // '1.23456789'

valueOf.val() ⇒ string

As toString.

Properties

The value of a Decimal is stored in a normalised base 10000000 floating point format.

A Decimal instance is an object with three properties:

Property	Description	Type	Value
d	digits	number[]	Array of integers, each 0 - 1e7
e	exponent*	number	Integer, -1286742750677284 to 1286742750677284 inclusive
s	sign	number	-1, 0, or 1

*This is the exponent in base 10000000. To get the base 10 exponent, use the exponent method.

The properties are best considered to be read-only.

As with JavaScript numbers, the original exponent and fractional trailing zeros of a number are not preserved.

x = new Decimal(0.123)                   // '0.123'
x.toExponential()                        // '1.23e-1'
x.d                                      // [ 1230000 ]
x.e                                      // -1
x.s                                      // 1

y = new Number(-123.4567000e+2)          // '-12345.67'
y.toExponential()                        // '-1.234567e+4'
z = new Decimal('-123.4567000e+2')       // '-12345.67'
z.toExponential()                        // '-1.234567e+4'
z.d                                      // [ 12345, 6700000 ]
z.e                                      // 4
z.s                                      // -1

Errors

The errors that are thrown are generic Error objects whose message property begins with "[DecimalError]".

To determine if an exception is a Decimal Error:

try {
    // ...
} catch (e) {
    if ( e instanceof Error && /DecimalError/.test(e.message) ) {
        // ...
    }
}

FAQ

Why are trailing fractional zeros removed from Decimals?

Some arbitrary-precision libraries retain trailing fractional zeros as they can indicate the precision of a value. This can be useful but the results of arithmetic operations can be misleading.

x = new BigDecimal("1.0")
y = new BigDecimal("1.1000")
z = x.add(y)                      // 2.1000

x = new BigDecimal("1.20")
y = new BigDecimal("3.45000")
z = x.multiply(y)                 // 4.1400000

To specify the precision of a value is to specify that the value lies within a certain range.

In the first example, x has a value of 1.0. The trailing zero shows the precision of the value, implying that it is in the range 0.95 to 1.05. Similarly, the precision indicated by the trailing zeros of y indicates that the value is in the range 1.09995 to 1.10005.

If we add the two lowest values in the ranges we have, 0.95 + 1.09995 = 2.04995, and if we add the two highest values we have, 1.05 + 1.10005 = 2.15005, so the range of the result of the addition implied by the precision of its operands is 2.04995 to 2.15005.

The result given by BigDecimal of 2.1000 however, indicates that the value is in the range 2.09995 to 2.10005 and therefore the precision implied by its trailing zeros may be misleading.

In the second example, the true range is 4.122744 to 4.157256 yet the BigDecimal answer of 4.1400000 indicates a range of 4.13999995 to 4.14000005. Again, the precision implied by the trailing zeros may be misleading.

This library, like binary floating point and most calculators, does not retain trailing fractional zeros. Instead, the toExponential, toFixed and toPrecision methods enable trailing zeros to be added if and when required.