An arbitrary-precision Decimal type for JavaScript.
See the README on GitHub for a quick-start introduction.
In all examples below, var
and semicolons are not shown, and if a commented-out
value is in quotes it means toString
has been called on the preceding expression.
When the library is loaded, it defines a single function object,
Decimal
, the constructor of Decimal 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
.
Decimal(value [, base]) ⇒ Decimal
value
0
, ±Infinity
and
NaN
.
errors
is true) as calling
toString
or valueOf
on
such numbers may not result in the intended value.
console.log( 823456789123456.3 ); // 823456789123456.2
'0xff'
, are invalid, and string
values in octal literal form will be interpreted as decimals, e.g. '011'
is
interpreted as 11, not 9.
a-z
represents values from 10 to 35, A-Z
from
36 to 61, and $
and _
represent 62 and 63 respectively.
base
2
to 64
inclusive
value
.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'
The static methods of a Decimal constructor.
.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, format: { decimalSeparator : '.', groupSeparator : ',', groupSize : 3, secondaryGroupSize : 0, fractionGroupSeparator : '\xA0', // non-breaking space fractionGroupSize : 0 } })
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([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() ⇒ Decimal
See exponential
.
x = Decimal.exp(3) y = new Decimal(3).exp() x.equals(y) // true
.ln() ⇒ Decimal
See naturalLogarithm
.
x = Decimal.ln(4.321) y = new Decimal(4.321).ln() x.equals(y) // true
.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([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([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() ⇒ 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(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([dp]) ⇒ Decimal
dp
: number: integer, 0 to 1e+9 inclusive
Returns a new Decimal with a pseudo-random value equal to or greater than 0
and
less than 1
.
The return value will have dp
decimal places (or less if trailing zeros are
produced). If dp
is omitted then the number of decimal places will
default to the current precision
setting.
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.
Decimal.config({ precision: 10 }) Decimal.random() // '0.4117936847' Decimal.random(20) // '0.78193327636914089009'
.sqrt() ⇒ Decimal
See squareRoot.
x = Decimal.sqrt('987654321.123456789') y = new Decimal('987654321.123456789').sqrt() x.equals(y) // true
The static properties of a Decimal constructor.
A Decimal instance with value one.
new Decimal(3).times(Decimal.ONE) // '3'
The values of the configuration properties precision
,
rounding
, minE
,
maxE
, toExpNeg
,
toExpPos
, errors
,
modulo
, crypto
and
format
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 (the properties of the
format
object are not checked by
config
). 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
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
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
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
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
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.
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.
boolean/number: true, false, 1 or 0
Default value: true
The value that determines whether Decimal Errors are thrown.
If errors
is false, no erros will be thrown.
See Errors.
Decimal.config({ errors: false }) Decimal.errors // false
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
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
. If the crypto
property is set directly (i.e. without using config
) to true
, then
at the time the random
method is called, if
errors
is true
, an error will be thrown if the
crypto
methods are unavailable.
Decimal.crypto // false Decimal.config({ crypto: true })
If crypto.getRandomValues
and crypto.randomBytes
are undefined, the
crypto property will remain false
.
Decimal.crypto // false
object
The format
object configures the format of the string returned by the
toFormat
method.
The example below shows the properties of the format
object
that are recognised, and their default values.
Unlike setting other properties using config
, the values of the
properties of the format
object will not be checked for validity. The existing
format
object will simply be replaced by the object that is passed in. Only the
toFormat
method ever references a Decimal constructor's
format
object property.
See toFormat
for examples of usage, and of setting
format
properties individually and directly without using config
.
Decimal.config({ format : { // the decimal separator decimalSeparator : '.', // the grouping separator of the integer part of the number groupSeparator : ',', // the primary grouping size of the integer part of the number groupSize : 3, // the secondary grouping size of the integer part of the number secondaryGroupSize : 0, // the grouping separator of the fraction part of the number fractionGroupSeparator : ' ', // the grouping size of the fraction part of the number fractionGroupSize : 0 } });
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
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.)
.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() ⇒ 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'
.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
.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'
.div(n [, base]) ⇒ Decimal
n
: number|string|Decimalbase
: 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'
.divToInt(n [, base]) ⇒ Decimal
n
: number|string|Decimalbase
: 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'
.eq(n [, base]) ⇒ boolean
n
: number|string|Decimalbase
: 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
.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() ⇒ 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'
.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
.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() ⇒ 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
.
.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() ⇒ 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.
.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() ⇒ 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
.
.lt(n [, base]) ⇒ boolean
n
: number|string|Decimalbase
: 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
.lte(n [, base]) ⇒ boolean
n
: number|string|Decimalbase
: 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
.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(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'
.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'
.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.
.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(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'
.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() ⇒ 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'
.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(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'
.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([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([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([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 fixed-point notation rounded to
dp
decimal places using rounding mode rm
(as
toFixed
), and formatted according to the properties of this
Decimal's constructor's format
object property.
See the examples below for the properties of the format
object, their types and their usage.
If dp
is omitted or is null
or undefined, then the return value is
not rounded to a fixed number of decimal places.
If rm
is omitted or is null
or undefined, rounding mode
rounding
is used.
// Using config to assign values to the format object Decimal.config({ format : { decimalSeparator : '.', groupSeparator : ',', groupSize : 3, secondaryGroupSize : 0, fractionGroupSeparator : ' ', fractionGroupSize : 0 } }); x = new Decimal('123456789.123456789') x.toFormat() // '123,456,789.123456789' x.toFormat(1) // '123,456,789.1' // Assigning the format properties directly Decimal.format.groupSeparator = ' '; Decimal.format.fractionGroupSize = 5; x.toFormat() // '123 456 789.12345 6789' // Assigning the format object directly Decimal.format = { decimalSeparator = ',', groupSeparator = '.', groupSize = 3, secondaryGroupSize = 2 } x.toFormat() // '12.34.56.789,123456789'
.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() ⇒ 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":[17770]}, {"s":1,"e":2,"c":[235,4325000]}, {"s":1,"e":-3,"c":[98074]}]" */
.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() ⇒ 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
.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, 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([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'
.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([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'
.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() ⇒ string
As toString
, but does not accept a base argument.
x = new Decimal('1.777e+457') x.valueOf() // '1.777e+457'
A Decimal is an object with three properties:
Property | Description | Type | Value |
---|---|---|---|
c | coefficient* | number[] |
Array of integers, each 0 - 1e7 |
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 properties are best considered to be read-only.
From version 3 of this library, the value of a Decimal is stored in a normalised base
10000
floating point format. While previously it was acceptable to change the
exponent of a Decimal by writing to its exponent property directly, this is no longer
recommended (as the number of digits in the first element of the coefficient array is
dependent on the exponent, so the coefficient would also need to be altered).
As with JavaScript numbers, the original exponent and fractional trailing zeros of a number are not preserved.
x = new Decimal(0.123) // '0.123' x.toExponential() // '1.23e-1' x.c // [ 1230000 ] x.e // -1 x.s // 1 y = new Number(-123.4567000e+2) // '-12345.67' y.toExponential() // '-1.234567e+4' z = new Decimal('-123.4567000e+2') // '-12345.67' z.toExponential() // '-1.234567e+4' z.c // [ 12345, 6700000 ] z.e // 4 z.s // -1
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
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 |
---|---|---|
comparedTo
|
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 |
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 |
LN10 out of digits | Ignore |
precision |
argument not a boolean or binary digit | Ignore |
random |
crypto unavailable |
Use Math.random |
toDecimalPlaces
|
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 | |
toNearest |
number type has more than 15 significant digits |
Accept. |
rounding mode out of range | Ignore | |
toString |
base not an integer | Truncate to integer. Ignore if not a number |
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' ) { // ... } }
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.