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 numbers.

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

A new Decimal constructor is created by calling the constructor method of an already existing Decimal constructor - when the library is loaded this will be Decimal.

CONSTRUCTOR

DecimalDecimal(value [, base]) ⇒ Decimal

value

number|string|Decimal

A numeric value.

Legitimate values include ±0, ±Infinity and NaN.

Values of type number with more than 15 significant digits are considered invalid (if errors is true) as calling toString or valueOf on such numbers may not result in the intended value.

console.log( 823456789123456.3 );    // 823456789123456.2

There is no limit to the number of digits of a value of type string (other than that of JavaScript's maximum array size).

See minE and maxE for the allowable range of a Decimal in terms of exponent limits.

Decimal string values may be in exponential, as well as normal (fixed-point) notation. Non-decimal values must be in normal notation.

String values in hexadecimal literal form, e.g. '0xff', are invalid, and string values in octal literal form will be interpreted as decimals, e.g. '011' is interpreted as 11, not 9.

Values in any base may have fraction digits.

For bases from 10 to 36, lower and/or upper case letters can be used to represent values from 10 to 35.

For bases above 36, a-z represents values from 10 to 35, A-Z from 36 to 61, and $ and _ represent 62 and 63 respectively.

base

number: integer, 2 to 64 inclusive

The base of value.

If base is omitted or is null or undefined, base 10 is assumed.

Returns a new instance of a Decimal object.

If a base is specified, value is rounded according to the current precision and rounding settings.

See Errors for the treatment of an invalid value or base.

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

 // 'new' is optional if errors is false
Decimal(435.345)

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(Infinity)                    // 'Infinity'
new Decimal(NaN)                         // 'NaN'
new Decimal('.5')                        // '0.5'
new Decimal('+2')                        // '2'
new Decimal(-10110100.1, 2)              // '-180.5'
new Decimal('123412421.234324', 5)       // '607236.557696'
new Decimal('ff.8', 16)                  // '255.5'

The following throws 'not a base 2 number' if errors is true, otherwise it returns a Decimal with value NaN.

new Decimal(9, 2)

The following throws 'number type has more than 15 significant digits' if errors is true, otherwise it returns a Decimal with value 96517860459076820.

new Decimal(96517860459076817.4395)

The following throws 'not a number' if errors is true, otherwise it returns a Decimal with value NaN.

new Decimal('blurgh')

A value is rounded only if a base is specified.

Decimal.config({ precision: 5 })
new Decimal(1.23456789)                  // '1.23456789'
new Decimal(1.23456789, 10)              // '1.2346'

Methods

The static methods of a Decimal constructor.

config.config(object) ⇒ Decimal constructor

object: object

Configures the 'global' settings for this particular Decimal constructor.

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.

If the value to be assigned to any of the properties is null or undefined it is ignored.
See Errors for the treatment of invalid values.

// Defaults
Decimal.config({
    precision: 20,
    rounding: 4,
    toExpNeg: -7,
    toExpPos: 21,
    minE: -9e15,
    maxE: 9e15,
    errors: true,
    crypto: false,
    modulo: 1
})

The properties of a Decimal constructor can also be set by direct assignment, but that will obviously by-pass the validity checking that this method performs.

constructor .constructor([object]) ⇒ Decimal constructor

object: object

Returns a new independent Decimal constructor with configuration settings as described by object (see config).

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

x = new Decimal(1)
y = new D9(1)

x.div(3)                           // 0.33333
y.div(3)                           // 0.333333333

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

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

constructor is a factory method so it is not necessary or desirable to use new but it will do no harm.

D = new Decimal.constructor()

exp.exp() ⇒ Decimal

See exponential.

x = Decimal.exp(3)
y = new Decimal(3).exp()
x.equals(y)                    // true

ln.ln() ⇒ Decimal

See naturalLogarithm.

x = Decimal.ln(4.321)
y = new Decimal(4.321).ln()
x.equals(y)                    // true

log.log(arg [, base]) ⇒ Decimal

arg: number|string|Decimal
base: number|string|Decimal
See Decimal for further parameter details.

See logarithm.

x = Decimal.log(100, 2.5)
y = new Decimal(100).log(2.5)
x.equals(y)                    // true

max.max([arg1 [, arg2, ...]]) ⇒ Decimal

arg1, arg2, ... : number|string|Decimal
See Decimal for further parameter details.

Returns a new Decimal whose value is the maximum of arg1, arg2,... .

Alternatively, the argument to this method can be an array of values.

x = new Decimal('3257869345.0378653')
Decimal.max(4e9, x, '123456789.9')          // '4000000000'

arr = [12, '13', new Decimal(14)]
Decimal.max(arr)                            // '14'

min.min([arg1 [, arg2, ...]]) ⇒ Decimal

arg1, arg2, ... : number|string|Decimal
See Decimal for further parameter details.

Returns a new Decimal whose value is the minimum of arg1, arg2,... .

Alternatively, the argument to this method can be an array of values.

x = new Decimal('3257869345.0378653')
Decimal.min(4e9, x, '123456789.9')          // '123456789.9'

arr = [2, new Decimal(-14), '-15.9999', -12]
Decimal.min(arr)                            // '-15.9999'

noConflict.noConflict() ⇒ Decimal constructor

Browsers only.

Reverts the Decimal variable to the value it had before this library was loaded and returns a reference to the original Decimal constructor so it can be assigned to a variable with a different name.

<script> Decimal = 1 </script>
<script src='/path/to/decimal.js'></script>
<script>
  x = new Decimal(2)      // '2'
  D = Decimal.noConflict()
  Decimal                 // 1
  y = new D(3)            // '3'
</script>

pow.pow(base, exponent) ⇒ Decimal

base: number|string|Decimal
exponent: number|string|Decimal
See Decimal for further parameter details.

See toPower.

x = Decimal.pow(3257.4, 17.01)
y = new Decimal(3257.4).pow(17.01)
x.equals(y)                    // true

random.random([limit [, sd]]) ⇒ Decimal

limit: number|string|Decimal
Default value: 1
sd: number: integer, 1 to 1e+9 inclusive
See Decimal for further parameter details.

Returns a new Decimal with a pseudo-random value equal to or greater in magnitude than 0 and lower in magnitude than limit, and with the same sign as limit.

If limit is omitted then it will be 1 and the return value will have precision significant digits (or less if there are trailing zeros produced).

If limit is included and sd is omitted then the return value will be an integer. If sd is included, the return value will have sd significant digits (or less if there are trailing zeros produced).

If limit is a high value be sure to include a precision, otherwise this method may be slow to return because all integer digits will be generated.

Depending on the value of a Decimal constructor's crypto property and the support for the crypto object in the host environment, the random digits of the return value are generated by either Math.random (fastest), crypto.getRandomValues (Web Cryptography API in recent browsers) or crypto.randomBytes (Node.js).

If crypto is true, i.e. one of the crypto methods is to be used, the value of a returned Decimal should be cryptographically-secure and statistically indistinguishable from a random value.

// A value in the range [0, 1) with precision significant digits
Decimal.config({ precision: 10 })
Decimal.random()                        // '0.4117936847'

// A value in the range [0, 1) with 20 significant digits
Decimal.random(1, 20)                   // '0.48193327636914089007'

// An integer in the range [0, 1)
Decimal.random(1)                       // '0' (always zero)

// An integer in the range [0, 10)
Decimal.random(10)                      // '6'

// An integer in the range (-100, 0]
Decimal.random(-100)                    // '-82'

// An integer in the range [0, 9e9999999999)
Decimal.random('9e99999999999')         // A browser will hang

// A value in the range [0, 9e9999999999) with 10 significant digits
Decimal.random('9e99999999999', 25)     // '1.508652055e+99999999999'

// A value in the range (-0.0125, 0] with 16 significant digits
Decimal.random(-0.0125, 16)             // '-0.0001963482803540358'

// A value in the range [0, 0.9) with 1 significant digit
Decimal.random(0.9, 1)                  // '0.2'

sqrt.sqrt() ⇒ Decimal

See squareRoot.

x = Decimal.sqrt('987654321.123456789')
y = new Decimal('987654321.123456789').sqrt()
x.equals(y)                    // true

Properties

The static properties of a Decimal constructor.

ONE

A Decimal instance with value one.

new Decimal(3).times(Decimal.ONE)    // '3'

Configuration properties

The values of the configuration properties precision, rounding, minE, maxE, toExpNeg, toExpPos, errors, modulo and crypto 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 })
// 'Decimal Error: config() precision out of range: 0'

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

precision

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

The maximum number of significant digits of the result of a calculation or base conversion.

All methods which return a Decimal will round the return value to precision significant digits except absoluteValue, ceil, floor, negated, round, toDecimalPlaces, toNearest and truncated.

A Decimal constructor will also not round to precision unless a base is specified.

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 when rounding the result of a calculation or base conversion to precision significant digits, and when rounding the return value of the round, toDecimalPlaces, toExponential, toFixed, toFormat, toNearest, toPrecision and toSignificantDigits methods.

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

minE

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

The negative exponent limit, i.e. the exponent value below which underflow to zero occurs.

If the Decimal to be returned by a calculation would have an exponent lower than minE then its value becomes zero.

JavaScript numbers underflow to zero for exponents below -324.

Decimal.config({ minE: -500 })
Decimal.minE                       // -500
new Decimal('1e-500')              // '1e-500'
new Decimal('9.9e-501')            // '0'

Decimal.config({ minE: -3 })
new Decimal(0.001)                 // '0.01'       e is -3
new Decimal(0.0001)                // '0'          e is -4

The smallest possible magnitude of a non-zero Decimal is 1e-9000000000000000

maxE

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

The positive exponent limit, i.e. the exponent value above which overflow to Infinity occurs.

If the Decimal to be returned by a calculation would have an exponent higher than maxE then its value becomes Infinity.

JavaScript numbers overflow to Infinity for exponents above 308.

Decimal.config({ maxE: 500 })
Decimal.maxE                       // 500
new Decimal('9.999e500')           // '9.999e+500'
new Decimal('1e501')               // 'Infinity'

Decimal.config({ maxE: 4 })
new Decimal(99999)                 // '99999'      e is 4
new Decimal(100000)                // 'Infinity'

The largest possible magnitude of a finite Decimal is 9.999...e+9000000000000000

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.

Calling toString with a base argument, e.g. toString(10), will also always return normal notation.

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.

Calling toString with a base argument, e.g. toString(10), will also always return normal notation.

errors

boolean/number: true, false, 1 or 0
Default value: true

The value that determines whether Decimal Errors are thrown.
If errors is false, this library will not throw errors.

See Errors.

Decimal.config({ errors: false })
Decimal.errors                     // false

modulo

number: integer, 0 to 9 inclusive
Default value: 1 (ROUND_DOWN)

The modulo mode used when calculating the modulus: a mod n.

The quotient, q = a / n, is calculated according to the rounding mode that corresponds to the chosen modulo mode.

The remainder, r, is calculated as: r = a - n * q.

The modes that are most commonly used for the modulus/remainder operation are shown in the following table. Although the other rounding modes can be used, they may not give useful results.

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

Decimal.config({ modulo: Decimal.EUCLID })
Decimal.config({ modulo: 9 })      // equivalent
Decimal.modulo                     // 9

crypto

boolean/number: true, false, 1 or 0
Default value: false

The value that determines whether cryptographically-secure pseudo-random number generation is used.

If crypto is truthy then the random method will generate random digits using crypto.getRandomValues in browsers that support it, or crypto.randomBytes if using a version of Node.js that supports it.

If neither function is supported by the host environment or if crypto is falsey then the source of randomness will be Math.random.

Decimal.crypto                     // false
Decimal.config({ crypto: true })

If crypto.getRandomValues and crypto.randomBytes are undefined, the crypto property will remain false.

Decimal.crypto                     // false

Rounding modes

The library's enumerated rounding modes are stored as properties of a 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.

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 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).ceil()

Methods do not round their arguments before execution.

The treatment of ±0, ±Infinity and NaN is consistent with how JavaScript treats these values.

Some 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 rounded.

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

ceil.ceil() ⇒ Decimal

Returns a new Decimal whose value is the value of this Decimal rounded to a whole number in the direction of positive Infinity.

The return value is not rounded to precision.

x = new Decimal(1.3)
x.ceil()                      // '2'
y = new Decimal(-1.8)
y.ceil()                      // '-1'

comparedTo.cmp(n [, base]) ⇒ number

n: number|string|Decimal
base: number
See Decimal for further parameter details.

x = new Decimal(Infinity)
y = new Decimal(5)
x.comparedTo(y)                // 1
x.comparedTo(x.minus(1))       // 0
y.cmp(NaN)                     // null
y.cmp('110', 2)                // -1

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(n [, base]) ⇒ Decimal

n: number|string|Decimal
base: number
See Decimal for further parameter details.

Returns a new Decimal whose value is the value of this Decimal divided by n, rounded to precision significant digits using rounding mode rounding.

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

dividedToIntegerBy.divToInt(n [, base]) ⇒ Decimal

n: number|string|Decimal
base: number
See Decimal for further parameter details.

Return a new Decimal whose value is the integer part of dividing this Decimal by n, rounded to precision significant digits using rounding mode rounding.

x = new Decimal(5)
y = new Decimal(3)
x.dividedToIntegerBy(y)     // '1'
x.divToInt(0.7)             // '7'
x.divToInt('0.f', 16)       // '5'

equals.eq(n [, base]) ⇒ boolean

n: number|string|Decimal
base: number
See Decimal for further parameter details.

Returns true if the value of this Decimal equals the value of n, otherwise returns false.
As with JavaScript, NaN does not equal NaN.

Note: This method uses the cmp method internally.

0 === 1e-324                     // true
x = new Decimal(0)
x.equals('1e-324')               // false
new Decimal(-0).eq(x)            // true  ( -0 === 0 )
new Decimal(255).eq('ff', 16)    // true

y = new Decimal(NaN)
y.equals(NaN)                    // false

exponential.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, rounded to precision significant digits using rounding mode rounding.

The naturalLogarithm function is the inverse of this function.

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

The return value will be correctly rounded, i.e. rounded as if the result was first calculated to an infinite number of correct digits before rounding. (The mathematical result of the exponential function is non-terminating, unless its argument is 0).

The performance of this method degrades exponentially with increasing digits.

floor.floor() ⇒ Decimal

Returns a new Decimal whose value is the value of this Decimal rounded to a whole number in the direction of negative Infinity.

The return value is not rounded to precision.

x = new Decimal(1.8)
x.floor()                   // '1'
y = new Decimal(-1.3)
y.floor()                   // '-2'

greaterThan.gt(n [, base]) ⇒ boolean

n: number|string|Decimal
base: number
See Decimal for further parameter details.

Returns true if the value of this Decimal is greater than the value of n, 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
new Decimal(11, 3).gt(11.1, 2)               // true

greaterThanOrEqualTo.gte(n [, base]) ⇒ boolean

n: number|string|Decimal
base: number
See Decimal for further parameter details.

Returns true if the value of this Decimal is greater than or equal to the value of n, 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
new Decimal(10, 18).gte('i', 36)         // true

isFinite.isFinite() ⇒ boolean

Returns true if the value of this Decimal is a finite number, otherwise returns false.
The only possible non-finite values of a Decimal are NaN, Infinity and -Infinity.

x = new Decimal(1)
x.isFinite()                  // true
y = new Decimal(Infinity)
y.isFinite()                  // false

Note: The native method isFinite() can be used if n <= Number.MAX_VALUE.

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

isNaN.isNaN() ⇒ boolean

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

x = new Decimal(NaN)
x.isNaN()                     // true
y = new Decimal('Infinity')
y.isNaN()                     // false

Note: The native method isNaN() can also be used.

isNegative.isNeg() ⇒ boolean

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

x = new Decimal(-0)
x.isNegative()                // true
y = new Decimal(2)
y.isNeg                       // 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() && x.isNeg()          // true
y = new Decimal(Infinity)
y.isZero()                       // false

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

lessThan.lt(n [, base]) ⇒ boolean

n: number|string|Decimal
base: number
See Decimal for further parameter details.

Returns true if the value of this Decimal is less than the value of n, 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
new Decimal(11.1, 2).lt(11, 3)       // true

lessThanOrEqualTo.lte(n [, base]) ⇒ boolean

n: number|string|Decimal
base: number
See Decimal for further parameter details.

Returns true if the value of this Decimal is less than or equal to the value of n, 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
new Decimal(10, 18).lte('i', 36)                // true

logarithm.log([n [, base]]) ⇒ Decimal

n: number|string|Decimal
base: number (This is not the base of the logarithm but the base of n)
See Decimal for further parameter details.

Returns a new Decimal whose value is the base n logarithm of the value of this Decimal, rounded to precision significant digits using rounding mode rounding.

If n is null or undefined, then 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 return value will almost always be correctly rounded, i.e. rounded as if the result was first calculated to an infinite number of correct digits before rounding. If a result is incorrectly rounded the maximum error will be 1 ulp (unit in the last place).

Logarithms to base 2 or 10 will always be correctly rounded.

See toPower for the circumstances in which this method may return an incorrectly rounded result.

The performance of this method degrades exponentially with increasing digits.

minus.minus(n [, base]) ⇒ Decimal

n: number|string|Decimal
base: number
See Decimal for further parameter details.

Returns a new Decimal whose value is the value of this Decimal minus n, rounded to precision significant digits using rounding mode rounding.

0.3 - 0.1                  // 0.19999999999999998
x = new Decimal(0.3)
x.minus(0.1)               // '0.2'
x.minus(0.6, 20)           // '0'

modulo.mod(n [, base]) ⇒ Decimal

n: number|string|Decimal
base: number
See Decimal for further parameter details.

Returns a new Decimal whose value is the value of this Decimal modulo n, rounded to precision significant digits using rounding mode rounding.

The value returned, and in particular its sign, is dependent on the value of the modulo property of this Decimal's constructor. If it is 1 (default value), the result will have the same sign as this Decimal, and it will match that of Javascript's % operator (within the limits of double precision) and BigDecimal's remainder method.

See modulo for a description of the other modulo modes.

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

y = new Decimal(33)
y.mod('a', 33)             // '3'

x = new Decimal(8)
y = new Decimal(-3)
Decimal.modulo = 1
x.mod(y)                   // '2'
Decimal.modulo = 3
x.mod(y)                   // '-1'

naturalLogarithm.ln() ⇒ Decimal

Returns a new Decimal whose value is the natural logarithm of the value of this Decimal, rounded to precision significant digits using rounding mode rounding.

The natual logarithm is the inverse of the exponential function.

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

The return value will be correctly rounded, i.e. rounded as if the result was first calculated to an infinite number of correct digits before rounding. (The mathematical result of the natural logarithm function is non-terminating, unless its argument is 1).

Internally, this method is dependent on a constant whose value is the natural logarithm of 10. This LN10 variable in the source code currently has a precision of 1025 digits, meaning that this method can accurately calculate up to 1000 digits.

If more than 1000 digits is required then the precision of LN10 will need to be increased to 25 digits more than is required - though, as the time-taken by this method increases exponentially with increasing digits, it is unlikely to be viable to calculate over 1000 digits anyway.

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 rounded.

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

plus.plus(n [, base]) ⇒ Decimal

n: number|string|Decimal
base: number
See Decimal for further parameter details.

Returns a new Decimal whose value is the value of this Decimal plus n, rounded to precision significant digits using rounding mode rounding.

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'
x.plus('0.1', 8)                   // '0.225'

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'

round.round() ⇒ 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.round()                                  // '1235'

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

squareRoot.sqrt() ⇒ Decimal

Returns a new Decimal whose value is the square root of this Decimal, rounded to precision significant digits using rounding mode rounding.

The return value will be correctly rounded, i.e. rounded as if the result was first calculated to an infinite number of correct digits before rounding.

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(n [, base]) ⇒ Decimal

n: number|string|Decimal
base: number
See Decimal for further parameter details.

Returns a new Decimal whose value is the value of this Decimal times n, rounded to precision significant digits using rounding mode rounding.

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'
x.times('-a', 16)                   // '-6'

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 dp decimal places using rounding mode rm.

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

if rm is omitted or is null or undefined, rounding mode rounding is used.

See Errors for the treatment of other non-integer or out of range dp values.

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, or is null or undefined, 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 or is null or undefined, rounding mode rounding is used.

See Errors for the treatment of other non-integer or out of range decimal_places values.

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 or is null or undefined, then 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 or is null or undefined, rounding mode rounding is used.

See Errors for the treatment of other non-integer or out of range dp values.

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'

toFormat.toFormat([sep1 [, dp [, sep2]]]) ⇒ string

sep1: string: the grouping separator of the integer part of the number
sep2: string: the grouping separator of the fraction part of the number
dp: number: integer, 0 to 8 inclusive

This method is a placeholder and is likely to be subject to change / further development.

Returns a string representing the value of this Decimal to dp decimal places, (see toFixed), but with the integer part of the number separated by sep1 into groups of three digits, and the fraction part of the number separated into groups of five digits by sep2.

If sep1 is null or undefined, the integer part groupings will be separated by a comma.

If sep2 is null or undefined, the fraction part groupings will not be separated.

If dp is omitted or is null or undefined, then the return value is not rounded to a fixed number of decimal places.

A useful separator character is the non-breaking thin-space: \u202f.

x = new Decimal('1.23456000000000000000789e+9')
x.toFormat()                     // '1,234,560,000.00000000000789'
x.toFormat(' ')                  // '1 234 560 000.00000000000789'
x.toFormat(',', 2)               // '1,234,560,000.00'
x.toFormat(' ', 2)               // '1 234 560 000.00'
x.toFormat(',', 12, ' ')         // '1 ,234,560,000.00000 00000 08'
x.toFormat('-', 14, '-')         // '1-234-560-000.00000-00000-0789'

toFraction .toFraction([max_denominator]) ⇒ [string, string]

max_denominator: number|string|Decimal: 1 >= integer < Infinity

Returns a string array representing the value of this Decimal as a simple fraction with an integer numerator and an integer denominator. The denominator will be a positive non-zero value less than or equal to max_denominator.

If a maximum denominator is not specified, or is null or undefined, the denominator will be the lowest value necessary to represent the number exactly.

See Errors for the treatment of other non-integer or out of range max_denominator values.

x = new Decimal(1.75)
x.toFraction()                       // '7, 4'

pi = new Decimal('3.14159265358')
pi.toFraction()                      // '157079632679,50000000000'
pi.toFraction(100000)                // '312689, 99532'
pi.toFraction(10000)                 // '355, 113'
pi.toFraction(100)                   // '311, 99'
pi.toFraction(10)                    // '22, 7'
pi.toFraction(1)                     // '3, 1'

toJSON.toJSON() ⇒ string

As valueOf.

x = new Decimal('177.7e+457')
y = new Decimal(235.4325)
z = new Decimal('0.0098074')

// Serialize an array of three Decimals
str = JSON.stringify( [x, y, z] )
// "["1.777e+459","235.4325","0.0098074"]"

// Return an array of three Decimals
JSON.parse(str, function (key, val) {
    return key === '' ? val : new Decimal(val)
})

If the toJSON method was not present, the objects (Decimal instances) themselves would be serialized, rather then the string returned by valueOf:

JSON.stringify( [x, y, z] )
/*
"[{"s":1,"e":459,"c":[1,7,7,7]},
  {"s":1,"e":2,"c":[2,3,5,4,3,2,5]},
  {"s":1,"e":-3,"c":[9,8,0,7,4]}]"
 */

toNearest.toNearest(n [, rm]) ⇒ Decimal

n: number|string|Decimal
rm: number: integer, 0 to 8 inclusive
See Decimal for further parameter details.

Returns a new Decimal whose value is the nearest multiple of n to the value of this Decimal.

If the value of this Decimal is equidistant from two multiples of n, the rounding mode rm, or rounding if rm is omitted or is null or undefined, determines the direction of the nearest.

In this context, rounding mode ROUND_HALF_UP is interpreted the same as rounding mode ROUND_UP, and so on. I.e. the rounding is either up, down, to ceil, to floor or to even.

The return value will always have the same sign as this Decimal, unless either this Decimal or n is NaN, in which case the return value will be also be NaN.

The return value is not rounded to precision.

x = new Decimal(1.39)
x.toNearest(0.25)              // '1.5'

y = new Decimal(0.75)          // equidistant from 0.5 and 1
y.toNearest(0.5, 0)            // '1'    (ROUND_UP)
y.toNearest(0.5, 1)            // '0.5'  (ROUND_DOWN)

toNumber.toNumber() ⇒ number

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

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

z = new Decimal(-0)
1 / +z                         // Infinity
1 / z.toNumber()               // -Infinity

toPower.pow(n [, base]) ⇒ Decimal

n: number|string|Decimal: integer or non-integer
base: number
See Decimal for further parameter details.

Returns a new Decimal whose value is the value of this Decimal raised to the power n, rounded to precision significant digits using rounding mode rounding.

The performance of this method degrades exponentially with increasing digits. For non-integer exponents in particular, even when only quite a small number of significant digits is required, the performance of this method may not be adequate.

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'

Is the pow function guaranteed to be correctly rounded?

The return value will almost always be correctly rounded, i.e. rounded as if the result was first calculated to an infinite number of correct digits before rounding. If a result is incorrectly rounded the maximum error will be 1 ulp (unit in the last place).

For non-integer and larger exponents this method uses the formula

xy = exp(y*ln(x))

As the mathematical return values of the exp and ln functions are both non-terminating (excluding arguments of 0 or 1), the Decimal return values of the functions as implemented by this library will be rounded approximations, which means that there can be no guarantee of correct rounding when they are combined in the above formula.

The return value may, depending on the rounding mode, be incorrectly rounded only if the first 15 rounding digits are 15 zeros (and there are non-zero digits following at some point) or 15 nines (the first rounding digit may also be 5 or 4 respectively).

Therefore, assuming the first 15 rounding digits are each equally likely to be any digit, 0-9, the probability of an incorrectly rounded result is less than 1 in 250,000,000,000,000.

An example of incorrect rounding:

Decimal.config({ precision: 20, rounding: 1 })
new Decimal(28).pow('6.166675020000903537297764507632802193308677149')
// 839756321.64088511

As the exact mathematical result begins

839756321.6408851099999999999999999999999999998969466049426031167...

and the rounding mode is set to ROUND_DOWN, the correct return value should be

839756321.64088510999

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 or is null or undefined, then the return value is the same as toString.

if rm is omitted or is null or undefined, rounding mode rounding is used.

See Errors for the treatment of other non-integer or out of range sd values.

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 sd significant digits using rounding mode rm.

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

if rm is omitted or is null or undefined, rounding mode rounding will be used.

See Errors for the treatment of other non-integer or out of range sd or rm values.

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([base]) ⇒ string

base: number: integer, 2 to 64 inclusive

Returns a string representing the value of this Decimal in the specified base, or base 10 if base is omitted or is null or undefined.

For bases above 10, values from 10 to 35 are represented by a-z (as with Number.prototype.toString), 36 to 61 by A-Z, and 62 and 63 by $ and _ respectively.

If a base is specified the value is rounded to precision significant digits using rounding mode rounding.

If a base is not specified and 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 is returned.

If base is null or undefined it is ignored.

See Errors for the treatment of other non-integer or out of range base values.

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

y = new Decimal(362.875)
y.toString(2)                   // '101101010.111'
y.toString(9)                   // '442.77777777777777777778'
y.toString(32)                  // 'ba.s'

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

truncated.trunc() ⇒ Decimal

Returns a new Decimal whose value is the value of this Decimal truncated to a whole number.

The return value is not rounded to precision.

x = new Decimal(123.456)
x.truncated()                   // '123'
y = new Decimal(-12.3)
y.trunc()                       // '-12'

valueOf.valueOf() ⇒ string

As toString, but does not accept a base argument.

x = new Decimal('1.777e+457')
x.valueOf()                     // '1.777e+457'

Properties

A Decimal is an object with three properties:

^*significand

The value of any of the three properties may also be null.

The value of a Decimal is stored in a normalised decimal floating point format which corresponds to the value's toExponential form, with the decimal point to be positioned after the most significant (left-most) digit of the coefficient.

Note that, as with JavaScript numbers, the original exponent and fractional trailing zeros are not preserved.

x = new Decimal(0.123)                // '0.123'
x.toExponential()                     // '1.23e-1'
x.c                                   // '1,2,3'
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.c                                   // '1,2,3,4,5,6,7'
z.e                                   // 4
z.s                                   // -1

A Decimal is mutable in the sense that the value of its properties can be changed.
For example, to rapidly shift a value by a power of 10:

x = new Decimal('1234.000')           // '1234'
x.toExponential()                     // '1.234e+3'
x.c                                   // '1,2,3,4'
x.e                                   // 3

x.e = -5
x                                     // '0.00001234'

If changing the coefficient array directly, which is not recommended, be careful to avoid leading or trailing zeros (unless zero itself is being represented).

Zero, NaN and Infinity

The table below shows how ±0, NaN and ±Infinity are stored.

x = new Number(-0)             // 0
1 / x == -Infinity             // true

y = new Decimal(-0)            // '0'
y.c                            // '0' ( [0].toString() )
y.e                            //  0
y.s                            // -1

Errors

The errors that are thrown are generic Error objects with name Decimal Error.

The table below shows the errors that may be thrown if errors is true, and the action taken if errors is false.

^*No error is thrown if the value is NaN or 'NaN'.

The message of a Decimal Error will also contain the name of the method from which the error originated.

To determine if an exception is a Decimal Error:

try {
    // ...
} catch (e) {
    if ( e instanceof Error && e.name == 'Decimal Error' ) {
        // ...
    }
}

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.