The light version of decimal.js, an arbitrary-precision Decimal type for JavaScript.
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.
Decimal(value) ⇒ Decimal
value: number|string|Decimal9007199254740991.
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'
The methods of a Decimal constructor.
.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.
.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.
The properties of a Decimal constructor.
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
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
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
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.
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.
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'
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
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.)
.abs() ⇒ DecimalReturns 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'
.cmp(x) ⇒ numberx: 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
.dp() ⇒ numberReturns 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'
.div(x) ⇒ Decimalx: 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'
.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'
.eq(x) ⇒ booleanx: 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() ⇒ numberReturns the exponent value of this Decimal.
x = new Decimal(1234.567) x.exponent() // 3
.gt(x) ⇒ booleanx: 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
.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
.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
.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.
.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() ⇒ 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.
.lt(x) ⇒ booleanx: 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
.lte(x) ⇒ booleanx: 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
.log(x) ⇒ Decimalx: 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(x) ⇒ Decimalx: 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'
.mod(x) ⇒ Decimalx: 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'
.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.
.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.
.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(x) ⇒ Decimalx: 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'
.sd([include_zeros]) ⇒ numberReturns 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'
.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(x) ⇒ Decimalx: 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'
.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([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 b = 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([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 b = 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'
.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() ⇒ stringAs toString.
.toNumber() ⇒ numberReturns 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
.pow(x) ⇒ Decimalx: 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([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 b = 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'
.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() ⇒ stringReturns 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'
.val() ⇒ stringAs toString.
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
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) ) {
// ...
}
}
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.