decimal.js

An arbitrary-precision Decimal type for JavaScript.

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

API

+See the README on GitHub for a quickstart +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

+Decimal`Decimal(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'
+new Decimal(1.23456789).round()          // '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 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
+})

+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 })

+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()

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

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
+Default value: precision
+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, 99.99)
+Decimal.random('99.99')                 // '47'
+
+// An integer in the range [0, 9e9999999999)
+Decimal.random('9e99999999999')         // The 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 value to be returned to +precision significant digits except +absoluteValue, ceil, +floor, negated, +round, toDecimalPlaces +and toNearest. +

+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 to +precision and when rounding +round, toDecimalPlaces, +toExponential, toFixed, +toFormat, and toPrecision. +

The 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 only -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 only 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 only -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 only 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. +

+ + + + + + + + + + + + + + + + + + + + + + +

Property	Value	Description
ROUND_UP	0	The remainder is positive if the dividend is negative, else is negative
ROUND_DOWN	1	+The remainder has the same sign as the dividend. +This uses truncating division and matches the behaviour of JavaScript's remainder +operator `%`. +
ROUND_FLOOR	3	+The remainder has the same sign as the divisor. +(This matches Python's `%` operator) +
ROUND_HALF_EVEN	6	The IEEE 754 remainder function
EUCLID	9	+The remainder is always positive. +Euclidian division: `q = sign(n) * floor(a / abs(n))`. +

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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
EUCLID	9	Not a rounding mode, see modulo

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([sd]) ⇒ Decimal`

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

+Returns a new Decimal whose value is the value of this Decimal rounded to sd +significant digits in the direction of positive Infinity. +

+If sd is omitted or is null or undefined, the return value is +the value of this Decimal rounded to a whole number. +

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

+ + + + + + + + + + + + + + + + + + +

Returns
1	If the value of this Decimal is greater than the value of `n`
-1	If the value of this Decimal is less than the value of `n`
0	If this Decimal and `n` have the same value
null	If the value of either this Decimal or `n` is `NaN`

+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([sd]) ⇒ Decimal`

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

+Returns a new Decimal whose value is the value of this Decimal rounded to sd +significant digits in the direction of negative Infinity. +

+If sd is omitted or is null or undefined, the return value is +the value of this Decimal rounded to a whole number. +

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

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 with value 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([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. +

+This method differs completely from Math.round, which rounds to +an integer. See toInteger. +

+Decimal.config({ precision: 5, rounding: 4 })
+x = new Decimal(9876.54321)
+
+x.round()                                 // '9876.5'
+x.round(6)                                // '9876.54'
+x.round(6, Decimal.ROUND_UP)              // '9876.55'
+x.round(2)                                // '9900'
+x.round(2, 1)                             // '9800'
+x                                         // '9876.54321'

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

+The square root is 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, 1)                   // '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 10²¹, this method will always return normal notation. +

+If dp is omitted or is null or undefined, then the return value is +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'

toInteger`.toInt([rm]) ⇒ Decimal`

rm: number: integer, 0 to 8 inclusive.

+Returns a new Decimal whose value is the value of this Decimal rounded to a whole number using +rounding mode rm, or rounding +if rm is omitted or is null or undefined. +

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

+Decimal.config({ rounding: 4 })
+x = 1234.5
+x.toInteger()                              // '1235'
+
+Decimal.config({ rounding: 1 })
+x.toInt()                                  // '1234'
+
+x.toInteger(Decimal.ROUND_HALF_CEIL)       // '1235'
+x.toInt(6)                                 // '1234'
+x                                          // '1234.56'

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 the magnitude 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 4 (ROUND_HALF_UP) is the +same as rounding mode 0 (ROUND_UP), and so on. +

+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?

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

x^y = 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'

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

+For bases above 10, values from 10 to 35 are represented by a-z (as with +Number.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([sd]) ⇒ Decimal`

+Returns a new Decimal whose value is the value of this Decimal truncated to to sd +significant digits. +

+If sd is omitted or is null or undefined, the return 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: +

+ + + + + + + + + + + + + + + + + + + + + + + + + +

Property	Description	Type	Value
c	coefficient^*	number`[]`	Array of single digits
e	exponent	number	Integer, -9e15 to 9e15 inclusive
s	sign	number	-1 or 1

^*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. +

+ + + + + + + + + + + + + + + + + + + + + + + + + +

	c	e	s
±0	`[0]`	`0`	`±1`
NaN	`null`	`null`	`null`
±Infinity	`null`	`null`	`±1`

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Method(s)	errors: true Throw Decimal Error	errors: false Action on invalid argument
+`+ceil +floor +truncated +` +	argument not an integer	Truncate to integer. Ignore if not a number
+`+ceil +floor +truncated +` +	argument out of range	Ignore
+`+comparedTo +Decimal +dividedBy +dividedToIntegerBy +equals +greaterThan +greaterThanOrEqualTo +lessThan +lessThanOrEqualTo +logarithm +minus +modulo +naturalLogarithm +plus +times +toPower +` +	number type has more than 15 significant digits	Accept.
	not a base... number	Substitute `NaN`
	base not an integer	Truncate to integer. Ignore if not a number
	base out of range	Ignore
	not a number^*	Substitute `NaN`
`config`	object expected	Ignore
	`precision` not an integer	Truncate to integer. Ignore if not a number
	`precision` out of range	Ignore
	`rounding` not an integer	Truncate to integer. Ignore if not a number
	`rounding` out of range	Ignore
	`toExpNeg` not an integer	Truncate to integer. Ignore if not a number
	`toExpNeg` out of range	Ignore
	`toExpPos` not an integer	Truncate to integer. Ignore if not a number
	`toExpPos` out of range	Ignore
	`minE` not an integer	Truncate to integer. Ignore if not a number
	`minE` out of range	Ignore
	`maxE` not an integer	Truncate to integer. Ignore if not a number
	`maxE` out of range	Ignore
	`errors` not a boolean or binary digit	Ignore
	`crypto` not a boolean or binary digit	Ignore
	`modulo` not an integer	Truncate to integer. Ignore if not a number
	`modulo` out of range	Ignore
`logarithm naturalLogarithm`	LN10 out of digits	Ignore
`precision`	argument not a boolean or binary digit	Ignore
+`+round +toDecimalPlaces +toExponential +toFixed +toPrecision +` +	argument not an integer	Truncate to integer. Ignore if not a number
	argument out of range	Ignore
	rounding mode not an integer	Truncate to integer. Ignore if not a number
	rounding mode out of range	Ignore
`toFraction`	number type has more than 15 significant digits	Accept.
	max denominator not an integer	Truncate to integer. Ignore if not a number
	max denominator out of range	Ignore
`toInteger`	rounding mode out of range	Ignore
`toNearest`	number type has more than 15 significant digits	Accept.
`toNearest`	rounding mode out of range	Ignore
`toString`	base not an integer	Truncate to integer. Ignore if not a number
`toString`	base out of range	Ignore

^*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.
+

decimal.js

API

CONSTRUCTOR

+DecimalDecimal(value [, base]) ⇒ Decimal +

Methods

+config.config(object) ⇒ Decimal constructor +

+constructor +.constructor([object]) ⇒ Decimal constructor +

exp.exp() ⇒ Decimal

ln.ln() ⇒ Decimal

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

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

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

+noConflict.noConflict() ⇒ Decimal constructor +

pow.pow(base, exponent) ⇒ Decimal

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

sqrt.sqrt() ⇒ Decimal

Properties

ONE

Configuration properties

precision

rounding

minE

maxE

toExpNeg

toExpPos

errors

modulo

crypto

Rounding modes

INSTANCE

Methods

absoluteValue.abs() ⇒ Decimal

ceil.ceil([sd]) ⇒ Decimal

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

decimalPlaces.dp() ⇒ number

dividedBy.div(n [, base]) ⇒ Decimal

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

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

exponential.exp() ⇒ Decimal

floor.floor([sd]) ⇒ Decimal

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

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

isFinite.isFinite() ⇒ boolean

isInteger.isInt() ⇒ boolean

isNaN.isNaN() ⇒ boolean

isNegative.isNeg() ⇒ boolean

isZero.isZero() ⇒ boolean

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

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

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

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

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

naturalLogarithm.ln() ⇒ Decimal

negated.neg() ⇒ Decimal

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

precision.sd([include_zeros]) ⇒ number

round.round([sd [, rm]]) ⇒ Decimal

squareRoot.sqrt() ⇒ Decimal

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

+toDecimalPlaces.toDP([dp [, rm]]) ⇒ Decimal +

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

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

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

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

toInteger.toInt([rm]) ⇒ Decimal

toJSON.toJSON() ⇒ string

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

toNumber.toNumber() ⇒ number

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

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

toString.toString([base]) ⇒ string

truncated.trunc([sd]) ⇒ Decimal

valueOf.valueOf() ⇒ string

Properties

Zero, NaN and Infinity

Errors

FAQ

Why are trailing fractional zeros removed from Decimals?

+Decimal`Decimal(value [, base]) ⇒ Decimal` +

+config`.config(object) ⇒ Decimal constructor` +

+constructor +`.constructor([object]) ⇒ Decimal constructor` +

exp`.exp() ⇒ Decimal`

ln`.ln() ⇒ Decimal`

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

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

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

+noConflict`.noConflict() ⇒ Decimal constructor` +

pow`.pow(base, exponent) ⇒ Decimal`

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

sqrt`.sqrt() ⇒ Decimal`

absoluteValue`.abs() ⇒ Decimal`

ceil`.ceil([sd]) ⇒ Decimal`

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

decimalPlaces`.dp() ⇒ number`

dividedBy`.div(n [, base]) ⇒ Decimal`

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

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

exponential`.exp() ⇒ Decimal`

floor`.floor([sd]) ⇒ Decimal`

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

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

isFinite`.isFinite() ⇒ boolean`

isInteger`.isInt() ⇒ boolean`

isNaN`.isNaN() ⇒ boolean`

isNegative`.isNeg() ⇒ boolean`

isZero`.isZero() ⇒ boolean`

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

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

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

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

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

naturalLogarithm`.ln() ⇒ Decimal`

negated`.neg() ⇒ Decimal`

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

precision`.sd([include_zeros]) ⇒ number`

round`.round([sd [, rm]]) ⇒ Decimal`

squareRoot`.sqrt() ⇒ Decimal`

times`.times(n [, base]) ⇒ Decimal`

+toDecimalPlaces`.toDP([dp [, rm]]) ⇒ Decimal` +

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

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

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

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

toInteger`.toInt([rm]) ⇒ Decimal`

toJSON`.toJSON() ⇒ string`

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

toNumber`.toNumber() ⇒ number`

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

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

toString`.toString([base]) ⇒ string`

truncated`.trunc([sd]) ⇒ Decimal`

valueOf`.valueOf() ⇒ string`