<!DOCTYPE HTML>
<
meta http-equiv="X-UA-Compatible" content="IE=edge">
<
meta name="Author" content="M Mclaughlin">
html{font-size:100%}
body{background:#fff;font-family:"Helvetica Neue",Helvetica,Arial,sans-serif;font-size:13px;
line-height:1.65em;min-height:100%;margin:0}
body,i{color:#000}
.nav{background:#fff;position:fixed;top:0;bottom:0;left:0;width:200px;overflow-y:auto;
padding:15px 0 30px 15px}
div.container{width:600px;margin:50px 0 50px 240px}
p{margin:0 0 1em;width:600px}
pre,ul{margin:1em 0}
h1,h2,h3,h4,h5{margin:0;padding:1.5em 0 0}
h1,h2{padding:.75em 0}
h1{font:400 3em Verdana,sans-serif;color:#000;margin-bottom:1em}
h2{font-size:2.25em;color:#ff2a00}
h3{font-size:1.75em;color:#4dc71f}
h4{font-size:1.75em;color:#ff2a00;padding-bottom:.75em}
h5{font-size:1.2em;margin-bottom:.4em}
h6{font-size:1.1em;margin-bottom:0.8em;padding:0.5em 0}
dd{padding-top:.35em}
dt{padding-top:.5em}
b{font-weight:700}
dt b{font-size:1.3em}
a,a:visited{color:#ff2a00;text-decoration:none}
a:active,a:hover{outline:0;text-decoration:underline}
.nav a,.nav b,.nav a:visited{display:block;color:#ff2a00;font-weight:700; margin-top:15px}
.nav b{color:#4dc71f;margin-top:20px;cursor:default;width:auto}
ul{list-style-type:none;padding:0 0 0 20px}
.nav ul{line-height:14px;padding-left:0;margin:5px 0 0}
.nav ul a,.nav ul a:visited,span{display:inline;color:#000;font-family:Verdana,Geneva,sans-serif;
font-size:11px;font-weight:400;margin:0}
.inset,ul.inset{margin-left:20px}
.inset{font-size:.9em}
.nav li{width:auto;margin:0 0 3px}
.alias{font-style:italic;margin-left:20px}
table{border-collapse:collapse;border-spacing:0;border:2px solid #a7dbd8;margin:1.75em 0;padding:0}
td,th{text-align:left;margin:0;padding:2px 5px;border:1px dotted #a7dbd8}
th{border-top:2px solid #a7dbd8;border-bottom:2px solid #a7dbd8;color:#ff2a00}
code,pre{font-family:Consolas, monaco, monospace;font-weight:400}
pre{background:#f5f5f5;white-space:pre-wrap;word-wrap:break-word;border-left:5px solid #abef98;
padding:1px 0 1px 15px;margin:1.2em 0}
code,.nav-title{color:#ff2a00}
.end{margin-bottom:25px}
.centre{text-align:center}
.error-table{font-size:13px;width:100%}
#faq{margin:3em 0 0}
li span{float:right;margin-right:10px;color:#c0c0c0}
#js{font:inherit;color:#4dc71f}
<
a class='nav-title' href="#">API<
/a>
<
li><
a href="#bignumber">BigNumber<
/a><
/li>
<
a href="#methods">Methods<
/a>
<
li><
a href="#clone">clone<
/a><
/li>
<
li><
a href="#decimal-places">DECIMAL_PLACES<
/a><
/li>
<
li><
a href="#rounding-mode" >ROUNDING_MODE<
/a><
/li>
<
li><
a href="#exponential-at">EXPONENTIAL_AT<
/a><
/li>
<
li><
a href="#range" >RANGE<
/a><
/li>
<
li><
a href="#crypto" >CRYPTO<
/a><
/li>
<
li><
a href="#modulo-mode" >MODULO_MODE<
/a><
/li>
<
li><
a href="#pow-precision" >POW_PRECISION<
/a><
/li>
<
li><
a href="#format" >FORMAT<
/a><
/li>
<
li><
a href="#alphabet" >ALPHABET<
/a><
/li>
<
li><
a href="#isBigNumber">isBigNumber<
/a><
/li>
<
li><
a href="#random" >random<
/a><
/li>
<
li><
a href="#sum" >sum<
/a><
/li>
<
a href="#constructor-properties">Properties<
/a>
<
li><
a href="#round-up" >ROUND_UP<
/a><
/li>
<
li><
a href="#round-down" >ROUND_DOWN<
/a><
/li>
<
li><
a href="#round-ceil" >ROUND_CEIL<
/a><
/li>
<
li><
a href="#round-floor" >ROUND_FLOOR<
/a><
/li>
<
li><
a href="#round-half-up" >ROUND_HALF_UP<
/a><
/li>
<
li><
a href="#round-half-down" >ROUND_HALF_DOWN<
/a><
/li>
<
li><
a href="#round-half-even" >ROUND_HALF_EVEN<
/a><
/li>
<
li><
a href="#round-half-ceil" >ROUND_HALF_CEIL<
/a><
/li>
<
li><
a href="#round-half-floor">ROUND_HALF_FLOOR<
/a><
/li>
<
li><
a href="#debug" >DEBUG<
/a><
/li>
<
a href="#prototype-methods">Methods<
/a>
<
li><
a href="#cmp" >comparedTo <
/a> <
/li>
<
li><
a href="#int" >integerValue <
/a> <
/li>
<
li><
a href="#isF" >isFinite <
/a> <
/li>
<
li><
a href="#isInt" >isInteger <
/a> <
/li>
<
li><
a href="#isNaN" >isNaN <
/a> <
/li>
<
li><
a href="#isNeg" >isNegative <
/a> <
/li>
<
li><
a href="#isPos" >isPositive <
/a> <
/li>
<
li><
a href="#isZ" >isZero <
/a> <
/li>
<
li><
a href="#minus" >minus <
/a> <
/li>
<
li><
a href="#neg" >negated <
/a> <
/li>
<
li><
a href="#plus" >plus <
/a> <
/li>
<
li><
a href="#shift" >shiftedBy <
/a> <
/li>
<
li><
a href="#toE" >toExponential <
/a> <
/li>
<
li><
a href="#toFix" >toFixed <
/a> <
/li>
<
li><
a href="#toFor" >toFormat <
/a> <
/li>
<
li><
a href="#toFr" >toFraction <
/a> <
/li>
<
li><
a href="#toJSON" >toJSON <
/a> <
/li>
<
li><
a href="#toN" >toNumber <
/a> <
/li>
<
li><
a href="#toP" >toPrecision <
/a> <
/li>
<
li><
a href="#toS" >toString <
/a> <
/li>
<
li><
a href="#valueOf">valueOf <
/a> <
/li>
<
a href="#instance-properties">Properties<
/a>
<
li><
a href="#coefficient">c: coefficient<
/a><
/li>
<
li><
a href="#exponent" >e: exponent<
/a><
/li>
<
li><
a href="#sign" >s: sign<
/a><
/li>
<
a href="#zero-nan-infinity">Zero, NaN & Infinity<
/a>
<
a href="#Errors">Errors<
/a>
<
a href="#type-coercion">
Type coercion<
/a>
<
a class='end' href="#faq">FAQ<
/a>
<
p>A JavaScript library
for arbitrary-precision arithmetic.<
/p>
<
p><
a href="https://github.com/MikeMcl/bignumber.js">Hosted on GitHub<
/a>. <
/p>
See the <
a href='https://github.com/MikeMcl/bignumber.js'>README<
/a> on GitHub
for a
quick-start introduction.
In all examples below, <
code>var<
/code> and semicolons are not shown, and if a commented-out
value is in quotes it means <
code>toString<
/code> has been called on the preceding expression.
BigNumber<
code class='inset'>BigNumber
(n
[, base
]) <
i>⇒ BigNumber<
/i><
/code>
<
a href='#alphabet'><
code>ALPHABET<
/code><
/a> to extend this range
).
Returns a new instance of a BigNumber
object with
value <
code>n<
/code>, where <
code>n<
/code>
is a numeric
value in the specified <
code>base<
/code>, or base <
code>
10<
/code> if
x = new BigNumber(123.4567) // '123.4567'
// 'new' is optional
y
= BigNumber
(x
) // '123.4567'<
/pre>
If <
code>n<
/code> is a base <
code>
10<
/code>
value it can be in normal
(fixed-point
) or
exponential notation. Values in other bases must be in normal notation. Values in any base can
have fraction digits, i.e. digits after the decimal point.
new BigNumber(43210) // '43210'
new BigNumber('4.321e+4') // '43210'
new BigNumber('-735.0918e-430') // '-7.350918e-428'
new BigNumber
('123412421.234324',
5) // '607236.557696'<
/pre>
new BigNumber('-Infinity') // '-Infinity'
new BigNumber(NaN) // 'NaN'
new BigNumber(-0) // '0'
new BigNumber('.5') // '0.5'
new BigNumber
('+2') // '2'<
/pre>
String values in hexadecimal literal form, e.g. <
code>
'0xff'<
/code>, are valid, as are
string values with the octal and binary prefixs <
code>
'0o'<
/code> and <
code>
'0b'<
/code>.
String values in octal literal form without the prefix will be interpreted as
decimals, e.g. <
code>
'011'<
/code> is interpreted as
11, not
9.
new BigNumber(-10110100.1, 2) // '-180.5'
new BigNumber('-0b10110100.1') // '-180.5'
new BigNumber('ff.8', 16) // '255.5'
new BigNumber
('0xff.8') // '255.5'<
/pre>
If a base is specified, <
code>n<
/code> is rounded according to the current
<
a href='#decimal-places'><
code>DECIMAL_PLACES<
/code><
/a> and
<
a href='#rounding-mode'><
code>ROUNDING_MODE<
/code><
/a> settings. <
em>This includes base
<
code>
10<
/code> so don
't include a <code>base</code> parameter for decimal values unless
this behaviour is wanted.</em>
</p>
<pre>BigNumber.config({ DECIMAL_PLACES: 5 })
new BigNumber(1.23456789) // '1.23456789'
new BigNumber(1.23456789, 10) // '1.23457'</pre>
<p>An error is thrown if <code>base</code> is invalid. See <a href='#Errors'>Errors</a>.</p>
<p>
There is no limit to the number of digits of a value of type <em>string</em> (other than
that of JavaScript's maximum array
size). See <
a href='#range'><
code>RANGE<
/code><
/a> to set
the maximum and minimum possible exponent value of a BigNumber.
new BigNumber('5032485723458348569331745.33434346346912144534543')
new BigNumber
('4.321e10000000')<
/pre>
new BigNumber('.1*') // 'NaN'
new BigNumber('blurgh') // 'NaN'
new BigNumber
(9,
2) // 'NaN'<
/pre>
To aid in debugging, if <
code>BigNumber.DEBUG<
/code> is <
code>true<
/code> then an error will
be thrown on an invalid <
code>n<
/code>. An error will also be thrown if <
code>n<
/code> is of
type <
em>number<
/em> with more than <
code>
15<
/code> significant digits, as calling
these numbers may not result in the intended value.
console.log(823456789123456.3) // 823456789123456.2
new BigNumber(823456789123456.3) // '823456789123456.2'
BigNumber.DEBUG = true
// '[BigNumber Error] Number primitive has more than 15 significant digits'
new BigNumber(823456789123456.3)
// '[BigNumber Error] Not a base 2 number'
new BigNumber
(9,
2)<
/pre>
A BigNumber can also be created from an object literal.
Use <
code><
a href='#isBigNumber'>isBigNumber<
/a><
/code> to check that it is well-formed.
<
pre>new BigNumber
({ s:
1, e:
2, c:
[ 777,
12300000000000 ], _isBigNumber: true
}) // '777.123'<
/pre>
<
h4 id="methods">Methods<
/h4>
<
p>The static methods of a BigNumber constructor.<
/p>
<
code class='inset'>.clone
([object]) <
i>⇒ BigNumber constructor<
/i><
/code>
Returns a new independent BigNumber constructor with configuration as described by
Throws if <
code>object<
/code> is not an
object. See <
a href='#Errors'>Errors<
/a>.
<
pre>BigNumber.config
({ DECIMAL_PLACES:
5 })
BN = BigNumber.clone({ DECIMAL_PLACES: 9 })
x = new BigNumber(1)
y = new BN(1)
x.div(3) // 0.33333
y.div(3) // 0.333333333
// BN = BigNumber.clone({ DECIMAL_PLACES: 9 }) is equivalent to:
BN = BigNumber.clone()
BN.config
({ DECIMAL_PLACES:
9 })<
/pre>
<
h5 id="config">config<
code class='inset'>set
([object]) <
i>⇒ object<
/i><
/code><
/h5>
<
code>object<
/code>: <
i>object<
/i>: an
object that contains some or all of the following
properties.
<
p>Configures the settings
for this particular BigNumber constructor.<
/p>
The <
span style="text-decoration:underline">maximum<
/span> number of decimal places of the results of operations involving
division, i.e. division, square root and base conversion operations, and power
operations with negative exponents.<
br />
<
pre>BigNumber.config
({ DECIMAL_PLACES:
5 })
BigNumber.set
({ DECIMAL_PLACES:
5 }) // equivalent<
/pre>
The rounding mode used in the above operations and the default rounding mode of
<
dd>The modes are available as enumerated properties of the BigNumber constructor.<
/dd>
<
pre>BigNumber.config
({ ROUNDING_MODE:
0 })
BigNumber.set
({ ROUNDING_MODE: BigNumber.ROUND_UP
}) // equivalent<
/pre>
The exponent
value(s
) at which <
code>toString<
/code> returns exponential notation.
If a single number is assigned, the
value is the exponent magnitude.<
br />
If an array of two numbers is assigned then the first number is the negative exponent
value at and beneath which exponential notation is used, and the second number is the
positive exponent value at and above which the same.
For example, to emulate JavaScript numbers in terms of the exponent values at which they
begin to use exponential notation, use <
code>
[-
7,
20]<
/code>.
<
pre>BigNumber.config
({ EXPONENTIAL_AT:
2 })
new BigNumber(12.3) // '12.3' e is only 1
new BigNumber(123) // '1.23e+2'
new BigNumber(0.123) // '0.123' e is only -1
new BigNumber(0.0123) // '1.23e-2'
BigNumber.config({ EXPONENTIAL_AT: [-7, 20] })
new BigNumber(123456789) // '123456789' e is only 8
new BigNumber(0.000000123) // '1.23e-7'
// Almost never return exponential notation:
BigNumber.config({ EXPONENTIAL_AT: 1e+9 })
// Always return exponential notation:
BigNumber.config
({ EXPONENTIAL_AT:
0 })<
/pre>
Regardless of the
value of <
code>EXPONENTIAL_AT<
/code>, the <
code>toFixed<
/code>
method
will always return a
value in normal notation and the <
code>toExponential<
/code>
method
will always return a value in exponential form.
Calling <
code>toString<
/code> with a base argument, e.g. <
code>toString
(10)<
/code>, will
also always return normal notation.
Default
value: <
code>
[-1e+9, 1e+9
]<
/code>
The exponent
value(s
) beyond which overflow to <
code>Infinity<
/code> and underflow to
zero occurs.
If a single number is assigned, it is the maximum exponent magnitude: values wth a
positive exponent of greater magnitude become <
code>Infinity<
/code> and those with a
negative exponent of greater magnitude become zero.
If an array of two numbers is assigned then the first number is the negative exponent
limit and the second number is the positive exponent limit.
For example, to emulate JavaScript numbers in terms of the exponent values at which they
<
pre>BigNumber.config
({ RANGE:
500 })
BigNumber.config().RANGE // [ -500, 500 ]
new BigNumber('9.999e499') // '9.999e+499'
new BigNumber('1e500') // 'Infinity'
new BigNumber('1e-499') // '1e-499'
new BigNumber('1e-500') // '0'
BigNumber.config({ RANGE: [-3, 4] })
new BigNumber(99999) // '99999' e is only 4
new BigNumber(100000) // 'Infinity' e is 5
new BigNumber(0.001) // '0.01' e is only -3
new BigNumber
(0.0001) // '0' e is -
4<
/pre>
The largest possible magnitude of a finite BigNumber is
The smallest possible magnitude of a non-zero BigNumber is <
code>1e-1000000000<
/code>.
The value that determines whether cryptographically-secure pseudo-random number
generation is used.
<
a href='#random'><
code>random<
/code><
/a>
method will generate random digits using
<
code>crypto.getRandomValues<
/code> in browsers that support it, or
<
code>crypto.randomBytes<
/code> if using Node.js.
If neither function is supported by the host environment then attempting to set
<
code>CRYPTO<
/code> to <
code>true<
/code> will fail and an exception will be thrown.
If <
code>CRYPTO<
/code> is <
code>false<
/code> then the source of randomness used will be
<
code>Math.random<
/code>
(which is assumed to generate at least <
code>
30<
/code> bits of
randomness).
// Node.js
global.crypto = require('crypto')
BigNumber.config({ CRYPTO: true })
BigNumber.config().CRYPTO // true
BigNumber.random
() // 0.54340758610486147524<
/pre>
<
dd>The modulo mode used when calculating the modulus: <
code>a mod n<
/code>.<
/dd>
The quotient, <
code>q
= a
/ n<
/code>, is calculated according to the
<
a href='#rounding-mode'><
code>ROUNDING_MODE<
/code><
/a> that corresponds to the chosen
The modes that are most commonly used for the modulus/remainder operation are shown in
the following table. Although the other rounding modes can be used, they may not give
useful results.
The remainder is positive if the dividend is negative, otherwise it is negative.
<
td><
b>ROUND_DOWN<
/b><
/td><
td class='centre'>
1<
/td>
The remainder has the same sign as the dividend.<
br />
This uses 'truncating division' and matches the behaviour of JavaScript's
remainder operator <code>%</code>.
</td>
</tr>
<tr>
<td><b>ROUND_FLOOR</b></td><td class='centre'>3</td>
<td>
The remainder has the same sign as the divisor.<br />
This matches Python's <
code>%<
/code> operator.
<
td><
b>ROUND_HALF_EVEN<
/b><
/td><
td class='centre'>
6<
/td>
<
td>The <
i>IEEE
754<
/i> remainder function.<
/td>
The remainder is always positive. Euclidian division: <
br />
<
code>q
= sign
(n
) * floor
(a
/ abs
(n
))<
/code>
The rounding/modulo modes are available as enumerated properties of the BigNumber
constructor.
<
pre>BigNumber.config
({ MODULO_MODE: BigNumber.EUCLID
})
BigNumber.config
({ MODULO_MODE:
9 }) // equivalent<
/pre>
The <
i>maximum<
/i> precision, i.e. number of significant digits, of the result of the power
operation (unless a modulus is specified).
<
dd>If set to <
code>
0<
/code>, the number of significant digits will not be limited.<
/dd>
<
dd><
pre>BigNumber.config
({ POW_PRECISION:
100 })<
/pre><
/dd>
The <
code>FORMAT<
/code>
object configures the format of the string returned by the
<
a href='#toFor'><
code>toFormat<
/code><
/a>
method.
The example below shows the properties of the <
code>FORMAT<
/code>
object that are
recognised, and their default values.
Unlike the other configuration properties, the values of the properties of the
<
code>FORMAT<
/code>
object will not be
checked for validity. The existing
<
code>FORMAT<
/code>
object will simply be replaced by the
object that is passed in.
The object can include any number of the properties shown below.
<
dd>See <
a href='#toFor'><
code>toFormat<
/code><
/a>
for examples of usage.<
/dd>
BigNumber.config({
FORMAT: {
// string to prepend
prefix: '',
// decimal separator
decimalSeparator: '.',
// grouping separator of the integer part
groupSeparator: ',',
// primary grouping size of the integer part
groupSize: 3,
// secondary grouping size of the integer part
secondaryGroupSize: 0,
// grouping separator of the fraction part
fractionGroupSeparator: ' ',
// grouping size of the fraction part
fractionGroupSize: 0,
// string to append
suffix: ''
}
Default
value: <
code>
'0123456789abcdefghijklmnopqrstuvwxyz'<
/code>
The alphabet used for base conversion. The length of the alphabet corresponds to the
maximum value of the base argument that can be passed to the
<
a href='#bignumber'><
code>BigNumber<
/code><
/a> constructor or
There is no maximum length for the alphabet, but it must be at least 2 characters long, and
it must not contain whitespace or a repeated character, or the sign indicators
<
pre>
// duodecimal
(base
12)
BigNumber.config({ ALPHABET: '0123456789TE' })
x = new BigNumber('T', 12)
x.toString() // '10'
x.toString
(12) // 'T'<
/pre>
<
p>Returns an
object with the above properties and their current values.<
/p>
Throws if <
code>object<
/code> is not an
object, or if an invalid
value is assigned to
one or more of the above properties. See <
a href='#Errors'>Errors<
/a>.
BigNumber.config({
DECIMAL_PLACES: 40,
ROUNDING_MODE: BigNumber.ROUND_HALF_CEIL,
EXPONENTIAL_AT: [-10, 20],
RANGE: [-500, 500],
CRYPTO: true,
MODULO_MODE: BigNumber.ROUND_FLOOR,
POW_PRECISION: 80,
FORMAT: {
groupSize: 3,
groupSeparator: ' ',
decimalSeparator: ','
},
ALPHABET: '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ$_'
});
obj = BigNumber.config();
obj.DECIMAL_PLACES // 40
obj.RANGE
// [-
500,
500]<
/pre>
isBigNumber<
code class='inset'>.isBigNumber
(value) <
i>⇒ boolean<
/i><
/code>
Returns <
code>true<
/code> if <
code>value<
/code> is a BigNumber instance, otherwise returns
y = new BigNumber(x)
BigNumber.isBigNumber(x) // false
y instanceof BigNumber // true
BigNumber.isBigNumber(y) // true
BN = BigNumber.clone();
z = new BN(x)
z instanceof BigNumber // false
BigNumber.isBigNumber
(z
) // true<
/pre>
then this
method will also check if <
code>value<
/code> is well-formed, and throw if it is not.
See <
a href='#Errors'>Errors<
/a>.
The check can be useful if creating a BigNumber from an object literal.
See <
a href='#bignumber'>BigNumber<
/a>.
x = new BigNumber(10)
// Change x.c to an illegitimate value.
x.c = NaN
BigNumber.DEBUG = false
// No error.
BigNumber.isBigNumber(x) // true
BigNumber.DEBUG = true
// Error.
BigNumber.isBigNumber
(x
) // '[BigNumber Error] Invalid BigNumber'<
/pre>
<
h5 id="max">maximum<
code class='inset'>.max
(n...
) <
i>⇒ BigNumber<
/i><
/code><
/h5>
<
i>See <
code><
a href="#bignumber">BigNumber<
/a><
/code>
for further parameter details.<
/i>
Returns a BigNumber whose value is the maximum of the arguments.
<
p>The return
value is always exact and unrounded.<
/p>
<
pre>x
= new BigNumber
('3257869345.0378653')
BigNumber.maximum(4e9, x, '123456789.9') // '4000000000'
arr = [12, '13', new BigNumber(14)]
BigNumber.max.apply
(null, arr
) // '14'<
/pre>
<
h5 id="min">minimum<
code class='inset'>.min
(n...
) <
i>⇒ BigNumber<
/i><
/code><
/h5>
<
i>See <
code><
a href="#bignumber">BigNumber<
/a><
/code>
for further parameter details.<
/i>
Returns a BigNumber whose value is the minimum of the arguments.
<
p>The return
value is always exact and unrounded.<
/p>
<
pre>x
= new BigNumber
('3257869345.0378653')
BigNumber.minimum(4e9, x, '123456789.9') // '123456789.9'
arr = [2, new BigNumber(-14), '-15.9999', -12]
BigNumber.min.apply
(null, arr
) // '-15.9999'<
/pre>
random<
code class='inset'>.random
([dp
]) <
i>⇒ BigNumber<
/i><
/code>
Returns a new BigNumber with a pseudo-random
value equal to or greater than <
code>
0<
/code> and
The return
value will have <
code>dp<
/code> decimal places
(or less if trailing zeros are
If <
code>dp<
/code> is omitted then the number of decimal places will default to the current
<
a href='#decimal-places'><
code>DECIMAL_PLACES<
/code><
/a> setting.
Depending on the value of this BigNumber constructor's
<a href='#crypto'><code>CRYPTO</code></a> setting and the support for the
<code>crypto</code> object in the host environment, the random digits of the return value are
generated by either <code>Math.random</code> (fastest), <code>crypto.getRandomValues</code>
(Web Cryptography API in recent browsers) or <code>crypto.randomBytes</code> (Node.js).
</p>
<p>
To be able to set <a href='#crypto'><code>CRYPTO</code></a> to <code>true</code> when using
Node.js, the <code>crypto</code> object must be available globally:
</p>
<pre>global.crypto = require('crypto')</pre>
<p>
If <a href='#crypto'><code>CRYPTO</code></a> is <code>true</code>, i.e. one of the
<code>crypto</code> methods is to be used, the value of a returned BigNumber should be
cryptographically-secure and statistically indistinguishable from a random value.
</p>
<p>
Throws if <code>dp</code> is invalid. See <a href='#Errors'>Errors</a>.
</p>
<pre>BigNumber.config({ DECIMAL_PLACES: 10 })
BigNumber.random() // '0.4117936847'
BigNumber.random(20) // '0.78193327636914089009'</pre>
<h5 id="sum">sum<code class='inset'>.sum(n...) <i>⇒ BigNumber</i></code></h5>
<p>
<code>n</code>: <i>number|string|BigNumber</i><br />
<i>See <code><a href="#bignumber">BigNumber</a></code> for further parameter details.</i>
</p>
<p>Returns a BigNumber whose value is the sum of the arguments.</p>
<p>The return value is always exact and unrounded.</p>
<pre>x = new BigNumber('3257869345.0378653')
BigNumber.sum(4e9, x, '123456789.9') // '7381326134.9378653'
arr = [2, new BigNumber(14), '15.9999', 12]
BigNumber.sum.apply(null, arr) // '43.9999'</pre>
<h4 id="constructor-properties">Properties</h4>
<p>
The library's enumerated rounding modes are stored as properties of the constructor.<
br />
(They are not referenced internally by the library itself.)
Rounding modes <
code>
0<
/code> to <
code>
6<
/code>
(inclusive
) are the same as those of Java
's
BigDecimal class.
</p>
<table>
<tr>
<th>Property</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td id="round-up"><b>ROUND_UP</b></td>
<td class='centre'>0</td>
<td>Rounds away from zero</td>
</tr>
<tr>
<td id="round-down"><b>ROUND_DOWN</b></td>
<td class='centre'>1</td>
<td>Rounds towards zero</td>
</tr>
<tr>
<td id="round-ceil"><b>ROUND_CEIL</b></td>
<td class='centre'>2</td>
<td>Rounds towards <code>Infinity</code></td>
</tr>
<tr>
<td id="round-floor"><b>ROUND_FLOOR</b></td>
<td class='centre'>3</td>
<td>Rounds towards <code>-Infinity</code></td>
</tr>
<tr>
<td id="round-half-up"><b>ROUND_HALF_UP</b></td>
<td class='centre'>4</td>
<td>
Rounds towards nearest neighbour.<br />
If equidistant, rounds away from zero
</td>
</tr>
<tr>
<td id="round-half-down"><b>ROUND_HALF_DOWN</b></td>
<td class='centre'>5</td>
<td>
Rounds towards nearest neighbour.<br />
If equidistant, rounds towards zero
</td>
</tr>
<tr>
<td id="round-half-even"><b>ROUND_HALF_EVEN</b></td>
<td class='centre'>6</td>
<td>
Rounds towards nearest neighbour.<br />
If equidistant, rounds towards even neighbour
</td>
</tr>
<tr>
<td id="round-half-ceil"><b>ROUND_HALF_CEIL</b></td>
<td class='centre'>7</td>
<td>
Rounds towards nearest neighbour.<br />
If equidistant, rounds towards <code>Infinity</code>
</td>
</tr>
<tr>
<td id="round-half-floor"><b>ROUND_HALF_FLOOR</b></td>
<td class='centre'>8</td>
<td>
Rounds towards nearest neighbour.<br />
If equidistant, rounds towards <code>-Infinity</code>
</td>
</tr>
</table>
<pre>
BigNumber.config({ ROUNDING_MODE: BigNumber.ROUND_CEIL })
BigNumber.config({ ROUNDING_MODE: 2 }) // equivalent</pre>
<h5 id="debug">DEBUG</h5>
<p><i>undefined|false|true</i></p>
<p>
If <code>BigNumber.DEBUG</code> is set <code>true</code> then an error will be thrown
if this <a href='#bignumber'>BigNumber</a> constructor receives an invalid value, such as
a value of type <em>number</em> with more than <code>15</code> significant digits.
See <a href='#bignumber'>BigNumber</a>.
</p>
<p>
An error will also be thrown if the <code><a href='#isBigNumber'>isBigNumber</a></code>
method receives a BigNumber that is not well-formed.
See <code><a href='#isBigNumber'>isBigNumber</a></code>.
</p>
<pre>BigNumber.DEBUG = true</pre>
<h3>INSTANCE</h3>
<h4 id="prototype-methods">Methods</h4>
<p>The methods inherited by a BigNumber instance from its constructor's prototype
object.<
/p>
<
p>A BigNumber is immutable in the sense that it is not changed by its methods. <
/p>
consistent with how JavaScript treats these values.
<
p>Many
method names have a shorter alias.<
/p>
<
h5 id="abs">absoluteValue<
code class='inset'>.abs
() <
i>⇒ BigNumber<
/i><
/code><
/h5>
Returns a BigNumber whose value is the absolute value, i.e. the magnitude, of the value of
this BigNumber.
<
p>The return
value is always exact and unrounded.<
/p>
x = new BigNumber(-0.8)
y = x.absoluteValue() // '0.8'
z
= y.abs
() // '0.8'<
/pre>
comparedTo<
code class='inset'>.comparedTo
(n
[, base
]) <
i>⇒ number<
/i><
/code>
<
i>See <
a href="#bignumber">BigNumber<
/a>
for further parameter details.<
/i>
<
td>If the
value of this BigNumber is greater than the
value of <
code>n<
/code><
/td>
<
td>If the
value of this BigNumber is less than the
value of <
code>n<
/code><
/td>
<
td>If this BigNumber and <
code>n<
/code> have the same value<
/td>
x = new BigNumber(Infinity)
y = new BigNumber(5)
x.comparedTo(y) // 1
x.comparedTo(x.minus(1)) // 0
y.comparedTo(NaN) // null
y.comparedTo
('110',
2) // -
1<
/pre>
decimalPlaces<
code class='inset'>.dp
([dp
[, rm
]]) <
i>⇒ BigNumber|number<
/i><
/code>
If <
code>dp<
/code> is a number, returns a BigNumber whose
value is the
value of this BigNumber
rounded by rounding mode <
code>rm<
/code> to a maximum of <
code>dp<
/code> decimal places.
value is the number of decimal places of the
value of this BigNumber, or <
code>null<
/code> if
the
value of this BigNumber is ±<
code>Infinity<
/code> or <
code>NaN<
/code>.
<
a href='#rounding-mode'><
code>ROUNDING_MODE<
/code><
/a> is used.
Throws if <
code>dp<
/code> or <
code>rm<
/code> is invalid. See <
a href='#Errors'>Errors<
/a>.
x = new BigNumber(1234.56)
x.decimalPlaces(1) // '1234.6'
x.dp() // 2
x.decimalPlaces(2) // '1234.56'
x.dp(10) // '1234.56'
x.decimalPlaces(0, 1) // '1234'
x.dp(0, 6) // '1235'
x.decimalPlaces(1, 1) // '1234.5'
x.dp(1, BigNumber.ROUND_HALF_EVEN) // '1234.6'
x // '1234.56'
y = new BigNumber('9.9e-101')
<
h5 id="div">dividedBy<
code class='inset'>.div
(n
[, base
]) <
i>⇒ BigNumber<
/i><
/code>
<
i>See <
a href="#bignumber">BigNumber<
/a>
for further parameter details.<
/i>
Returns a BigNumber whose value is the value of this BigNumber divided by
<
code>n<
/code>, rounded according to the current
<
a href='#decimal-places'><
code>DECIMAL_PLACES<
/code><
/a> and
<
a href='#rounding-mode'><
code>ROUNDING_MODE<
/code><
/a> settings.
x = new BigNumber(355)
y = new BigNumber(113)
x.dividedBy(y) // '3.14159292035398230088'
x.div(5) // '71'
x.div
(47,
16) // '5'<
/pre>
dividedToIntegerBy<
code class='inset'>.idiv
(n
[, base
]) ⇒
<
i>See <
a href="#bignumber">BigNumber<
/a>
for further parameter details.<
/i>
Returns a BigNumber whose value is the integer part of dividing the value of this BigNumber by
x = new BigNumber(5)
y = new BigNumber(3)
x.dividedToIntegerBy(y) // '1'
x.idiv(0.7) // '7'
x.idiv
('0.f',
16) // '5'<
/pre>
exponentiatedBy<
code class='inset'>.pow
(n
[, m
]) <
i>⇒ BigNumber<
/i><
/code>
<
code>n<
/code>: <
i>number|string|BigNumber<
/i>: integer<
br />
Returns a BigNumber whose value is the value of this BigNumber exponentiated by
<
code>n<
/code>, i.e. raised to the power <
code>n<
/code>, and optionally modulo a modulus
Throws if <
code>n<
/code> is not an integer. See <
a href='#Errors'>Errors<
/a>.
If <
code>n<
/code> is negative the result is rounded according to the current
<
a href='#decimal-places'><
code>DECIMAL_PLACES<
/code><
/a> and
<
a href='#rounding-mode'><
code>ROUNDING_MODE<
/code><
/a> settings.
As the number of digits of the result of the power operation can grow so large so quickly,
e.g.
123.456<
sup>
10000<
/sup> has over <
code>
50000<
/code> digits, the number of significant
digits calculated is limited to the value of the
<
a href='#pow-precision'><
code>POW_PRECISION<
/code><
/a> setting
(unless a modulus
By default <
a href='#pow-precision'><
code>POW_PRECISION<
/code><
/a> is set to <
code>
0<
/code>.
This means that an unlimited number of significant digits will be calculated, and that the
method's performance will decrease dramatically for larger exponents.
</p>
<p>
If <code>m</code> is specified and the value of <code>m</code>, <code>n</code> and this
BigNumber are integers, and <code>n</code> is positive, then a fast modular exponentiation
algorithm is used, otherwise the operation will be performed as
<code>x.exponentiatedBy(n).modulo(m)</code> with a
<a href='#pow-precision'><code>POW_PRECISION</code></a> of <code>0</code>.
</p>
<pre>
Math.pow(0.7, 2) // 0.48999999999999994
x = new BigNumber(0.7)
x.exponentiatedBy(2) // '0.49'
BigNumber(3).pow(-2) // '0.11111111111111111111'</pre>
<h5 id="int">
integerValue<code class='inset'>.integerValue([rm]) <i>⇒ BigNumber</i></code>
</h5>
<p>
<code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive
</p>
<p>
Returns a BigNumber whose value is the value of this BigNumber rounded to an integer using
rounding mode <code>rm</code>.
</p>
<p>
If <code>rm</code> is omitted, or is <code>null</code> or <code>undefined</code>,
<a href='#rounding-mode'><code>ROUNDING_MODE</code></a> is used.
</p>
<p>
Throws if <code>rm</code> is invalid. See <a href='#Errors'>Errors</a>.
</p>
<pre>
x = new BigNumber(123.456)
x.integerValue() // '123'
x.integerValue(BigNumber.ROUND_CEIL) // '124'
y = new BigNumber(-12.7)
y.integerValue() // '-13'
y.integerValue(BigNumber.ROUND_DOWN) // '-12'</pre>
<p>
The following is an example of how to add a prototype method that emulates JavaScript's
<
code>Math.trunc<
/code> can be emulated in the same way with
<
code> BigNumber.ROUND_DOWN<
/code> respectively.
BigNumber.prototype.round = function (n) {
return n.integerValue(BigNumber.ROUND_HALF_CEIL);
};
<
h5 id="eq">isEqualTo<
code class='inset'>.eq
(n
[, base
]) <
i>⇒ boolean<
/i><
/code><
/h5>
<
i>See <
a href="#bignumber">BigNumber<
/a>
for further parameter details.<
/i>
Returns <
code>true<
/code> if the
value of this BigNumber is equal to the
value of
<
p>Note: This
method uses the <
a href='#cmp'><
code>comparedTo<
/code><
/a>
method internally.<
/p>
0 === 1e-324 // true
x = new BigNumber(0)
x.isEqualTo('1e-324') // false
BigNumber(-0).eq(x) // true ( -0 === 0 )
BigNumber(255).eq('ff', 16) // true
y = new BigNumber(NaN)
y.isEqualTo
(NaN
) // false<
/pre>
<
h5 id="isF">isFinite<
code class='inset'>.isFinite
() <
i>⇒ boolean<
/i><
/code><
/h5>
Returns <
code>true<
/code> if the
value of this BigNumber is a finite number, otherwise
The only possible non-finite values of a BigNumber are <
code>NaN<
/code>, <
code>Infinity<
/code>
x = new BigNumber(1)
x.isFinite() // true
y = new BigNumber(Infinity)
y.isFinite
() // false<
/pre>
Note: The native
method <
code>isFinite
()<
/code> can be used if
<
h5 id="gt">isGreaterThan<
code class='inset'>.gt
(n
[, base
]) <
i>⇒ boolean<
/i><
/code><
/h5>
<
i>See <
a href="#bignumber">BigNumber<
/a>
for further parameter details.<
/i>
Returns <
code>true<
/code> if the
value of this BigNumber is greater than the
value of
<
p>Note: This
method uses the <
a href='#cmp'><
code>comparedTo<
/code><
/a>
method internally.<
/p>
0.1 > (0.3 - 0.2) // true
x = new BigNumber(0.1)
x.isGreaterThan(BigNumber(0.3).minus(0.2)) // false
BigNumber(0).gt(x) // false
BigNumber
(11,
3).gt
(11.1,
2) // true<
/pre>
isGreaterThanOrEqualTo<
code class='inset'>.gte
(n
[, base
]) <
i>⇒ boolean<
/i><
/code>
<
i>See <
a href="#bignumber">BigNumber<
/a>
for further parameter details.<
/i>
Returns <
code>true<
/code> if the
value of this BigNumber is greater than or equal to the
value
<
p>Note: This
method uses the <
a href='#cmp'><
code>comparedTo<
/code><
/a>
method internally.<
/p>
(0.3 - 0.2) >= 0.1 // false
x = new BigNumber(0.3).minus(0.2)
x.isGreaterThanOrEqualTo(0.1) // true
BigNumber(1).gte(x) // true
BigNumber
(10,
18).gte
('i',
36) // true<
/pre>
<
h5 id="isInt">isInteger<
code class='inset'>.isInteger
() <
i>⇒ boolean<
/i><
/code><
/h5>
Returns <
code>true<
/code> if the
value of this BigNumber is an integer, otherwise returns
x = new BigNumber(1)
x.isInteger() // true
y = new BigNumber(123.456)
y.isInteger
() // false<
/pre>
<
h5 id="lt">isLessThan<
code class='inset'>.lt
(n
[, base
]) <
i>⇒ boolean<
/i><
/code><
/h5>
<
i>See <
a href="#bignumber">BigNumber<
/a>
for further parameter details.<
/i>
Returns <
code>true<
/code> if the
value of this BigNumber is less than the
value of
<
p>Note: This
method uses the <
a href='#cmp'><
code>comparedTo<
/code><
/a>
method internally.<
/p>
(0.3 - 0.2) < 0.1 // true
x = new BigNumber(0.3).minus(0.2)
x.isLessThan(0.1) // false
BigNumber(0).lt(x) // true
BigNumber
(11.1,
2).lt
(11,
3) // true<
/pre>
isLessThanOrEqualTo<
code class='inset'>.lte
(n
[, base
]) <
i>⇒ boolean<
/i><
/code>
<
i>See <
a href="#bignumber">BigNumber<
/a>
for further parameter details.<
/i>
Returns <
code>true<
/code> if the
value of this BigNumber is less than or equal to the
value of
<
p>Note: This
method uses the <
a href='#cmp'><
code>comparedTo<
/code><
/a>
method internally.<
/p>
0.1 <= (0.3 - 0.2) // false
x = new BigNumber(0.1)
x.isLessThanOrEqualTo(BigNumber(0.3).minus(0.2)) // true
BigNumber(-1).lte(x) // true
BigNumber
(10,
18).lte
('i',
36) // true<
/pre>
<
h5 id="isNaN">isNaN<
code class='inset'>.isNaN
() <
i>⇒ boolean<
/i><
/code><
/h5>
Returns <
code>true<
/code> if the
value of this BigNumber is <
code>NaN<
/code>, otherwise
x = new BigNumber(NaN)
x.isNaN() // true
y = new BigNumber('Infinity')
<
p>Note: The native
method <
code>isNaN
()<
/code> can also be used.<
/p>
<
h5 id="isNeg">isNegative<
code class='inset'>.isNegative
() <
i>⇒ boolean<
/i><
/code><
/h5>
Returns <
code>true<
/code> if the sign of this BigNumber is negative, otherwise returns
x = new BigNumber(-0)
x.isNegative() // true
y = new BigNumber(2)
y.isNegative
() // false<
/pre>
<
h5 id="isPos">isPositive<
code class='inset'>.isPositive
() <
i>⇒ boolean<
/i><
/code><
/h5>
Returns <
code>true<
/code> if the sign of this BigNumber is positive, otherwise returns
x = new BigNumber(-0)
x.isPositive() // false
y = new BigNumber(2)
y.isPositive
() // true<
/pre>
<
h5 id="isZ">isZero<
code class='inset'>.isZero
() <
i>⇒ boolean<
/i><
/code><
/h5>
Returns <
code>true<
/code> if the
value of this BigNumber is zero or minus zero, otherwise
x = new BigNumber(-0)
x.isZero() && x.isNegative() // true
y = new BigNumber(Infinity)
y.isZero
() // false<
/pre>
minus<
code class='inset'>.minus
(n
[, base
]) <
i>⇒ BigNumber<
/i><
/code>
<
i>See <
a href="#bignumber">BigNumber<
/a>
for further parameter details.<
/i>
<
p>Returns a BigNumber whose
value is the
value of this BigNumber minus <
code>n<
/code>.<
/p>
<
p>The return
value is always exact and unrounded.<
/p>
0.3 - 0.1 // 0.19999999999999998
x = new BigNumber(0.3)
x.minus(0.1) // '0.2'
x.minus
(0.6,
20) // '0'<
/pre>
<
h5 id="mod">modulo<
code class='inset'>.mod
(n
[, base
]) <
i>⇒ BigNumber<
/i><
/code><
/h5>
<
i>See <
a href="#bignumber">BigNumber<
/a>
for further parameter details.<
/i>
Returns a BigNumber whose
value is the
value of this BigNumber modulo <
code>n<
/code>, i.e.
the integer remainder of dividing this BigNumber by <
code>n<
/code>.
The value returned, and in particular its sign, is dependent on the value of the
<
a href='#modulo-mode'><
code>MODULO_MODE<
/code><
/a> setting of this BigNumber constructor.
If it is <
code>
1<
/code>
(default
value), the result will have the same sign as this BigNumber,
and it will match that of Javascript's <code>%</code> operator (within the limits of double
precision) and BigDecimal's <
code>remainder<
/code>
method.
<
p>The return
value is always exact and unrounded.<
/p>
See <
a href='#modulo-mode'><
code>MODULO_MODE<
/code><
/a>
for a description of the other
modulo modes.
1 % 0.9 // 0.09999999999999998
x = new BigNumber(1)
x.modulo(0.9) // '0.1'
y = new BigNumber(33)
y.mod
('a',
33) // '3'<
/pre>
multipliedBy<
code class='inset'>.times
(n
[, base
]) <
i>⇒ BigNumber<
/i><
/code>
<
i>See <
a href="#bignumber">BigNumber<
/a>
for further parameter details.<
/i>
Returns a BigNumber whose
value is the
value of this BigNumber multiplied by <
code>n<
/code>.
<
p>The return
value is always exact and unrounded.<
/p>
0.6 * 3 // 1.7999999999999998
x = new BigNumber(0.6)
y = x.multipliedBy(3) // '1.8'
BigNumber('7e+500').times(y) // '1.26e+501'
x.multipliedBy
('-a',
16) // '-6'<
/pre>
<
h5 id="neg">negated<
code class='inset'>.negated
() <
i>⇒ BigNumber<
/i><
/code><
/h5>
Returns a BigNumber whose value is the value of this BigNumber negated, i.e. multiplied by
x = new BigNumber(1.8)
x.negated() // '-1.8'
y = new BigNumber(-1.3)
y.negated
() // '1.3'<
/pre>
<
h5 id="plus">plus<
code class='inset'>.plus
(n
[, base
]) <
i>⇒ BigNumber<
/i><
/code><
/h5>
<
i>See <
a href="#bignumber">BigNumber<
/a>
for further parameter details.<
/i>
<
p>Returns a BigNumber whose
value is the
value of this BigNumber plus <
code>n<
/code>.<
/p>
<
p>The return
value is always exact and unrounded.<
/p>
0.1 + 0.2 // 0.30000000000000004
x = new BigNumber(0.1)
y = x.plus(0.2) // '0.3'
BigNumber(0.7).plus(x).plus(y) // '1.1'
x.plus
('0.1',
8) // '0.225'<
/pre>
precision<
code class='inset'>.sd
([d
[, rm
]]) <
i>⇒ BigNumber|number<
/i><
/code>
If <
code>d<
/code> is a number, returns a BigNumber whose
value is the
value of this BigNumber
rounded to a precision of <
code>d<
/code> significant digits using rounding mode
value is the number of significant digits of the
value of this BigNumber, or <
code>null<
/code>
if the
value of this BigNumber is ±<
code>Infinity<
/code> or <
code>NaN<
/code>.
part of a number are counted as significant digits, otherwise they are not.
<
a href='#rounding-mode'><
code>ROUNDING_MODE<
/code><
/a> will be used.
x = new BigNumber(9876.54321)
x.precision(6) // '9876.54'
x.sd() // 9
x.precision(6, BigNumber.ROUND_UP) // '9876.55'
x.sd(2) // '9900'
x.precision(2, 1) // '9800'
x // '9876.54321'
y = new BigNumber(987000)
y.precision() // 3
<
h5 id="shift">shiftedBy<
code class='inset'>.shiftedBy
(n
) <
i>⇒ BigNumber<
/i><
/code><
/h5>
Returns a BigNumber whose
value is the
value of this BigNumber shifted by <
code>n<
/code>
places.
The shift is of the decimal point, i.e. of powers of ten, and is to the left if <
code>n<
/code>
is negative or to the right if <
code>n<
/code> is positive.
<
p>The return
value is always exact and unrounded.<
/p>
Throws if <
code>n<
/code> is invalid. See <
a href='#Errors'>Errors<
/a>.
x = new BigNumber(1.23)
x.shiftedBy(3) // '1230'
x.shiftedBy
(-
3) // '0.00123'<
/pre>
<
h5 id="sqrt">squareRoot<
code class='inset'>.sqrt
() <
i>⇒ BigNumber<
/i><
/code><
/h5>
Returns a BigNumber whose value is the square root of the value of this BigNumber,
rounded according to the current
<
a href='#decimal-places'><
code>DECIMAL_PLACES<
/code><
/a> and
<
a href='#rounding-mode'><
code>ROUNDING_MODE<
/code><
/a> settings.
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.
x = new BigNumber(16)
x.squareRoot() // '4'
y = new BigNumber(3)
y.sqrt
() // '1.73205080756887729353'<
/pre>
toExponential<
code class='inset'>.toExponential
([dp
[, rm
]]) <
i>⇒ string<
/i><
/code>
Returns a string representing the value of this BigNumber in exponential notation rounded
using rounding mode <
code>rm<
/code> to <
code>dp<
/code> decimal places, i.e with one digit
before the decimal point and <
code>dp<
/code> digits after it.
If the
value of this BigNumber in exponential notation has fewer than <
code>dp<
/code> fraction
digits, the return value will be appended with zeros accordingly.
of digits after the decimal point defaults to the minimum number of digits necessary to
represent the
value exactly.<
br />
<
a href='#rounding-mode'><
code>ROUNDING_MODE<
/code><
/a> is used.
Throws if <
code>dp<
/code> or <
code>rm<
/code> is invalid. See <
a href='#Errors'>Errors<
/a>.
x = 45.6
y = new BigNumber(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'<
/pre>
toFixed<
code class='inset'>.toFixed
([dp
[, rm
]]) <
i>⇒ string<
/i><
/code>
Returns a string representing the value of this BigNumber in normal (fixed-point) notation
If the
value of this BigNumber in normal notation has fewer than <
code>dp<
/code> fraction
digits, the return value will be appended with zeros accordingly.
Unlike <
code>Number.prototype.toFixed<
/code>, which returns exponential notation if a number
is greater or equal to <
code>
10<
sup>
21<
/sup><
/code>, this
method will always return normal
notation.
value will be unrounded and in normal notation. This is also unlike
<
code>Number.prototype.toFixed<
/code>, which returns the
value to zero decimal places.<
br />
It is useful when fixed-point notation is required and the current
<
a href="#exponential-at"><
code>EXPONENTIAL_AT<
/code><
/a> setting causes
<
code><
a href='#toS'>toString<
/a><
/code> to return exponential notation.<
br />
<
a href='#rounding-mode'><
code>ROUNDING_MODE<
/code><
/a> is used.
Throws if <
code>dp<
/code> or <
code>rm<
/code> is invalid. See <
a href='#Errors'>Errors<
/a>.
x = 3.456
y = new BigNumber(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'<
/pre>
toFormat<
code class='inset'>.toFormat
([dp
[, rm
[, format
]]]) <
i>⇒ string<
/i><
/code>
Returns a string representing the value of this BigNumber in normal (fixed-point) notation
rounded to <
code>dp<
/code> decimal places using rounding mode <
code>rm<
/code>, and formatted
according to the properties of the <
code>format<
/code>
object.
See <
a href='#format'><
code>FORMAT<
/code><
/a> and the examples below
for the properties of the
<
code>format<
/code>
object, their types, and their usage. A formatting
object may contain
some or all of the recognised properties.
return
value is not rounded to a fixed number of decimal places.<
br />
<
a href='#rounding-mode'><
code>ROUNDING_MODE<
/code><
/a> is used.<
br />
<
a href='#format'><
code>FORMAT<
/code><
/a>
object is used.
<
a href='#Errors'>Errors<
/a>.
fmt = {
prefix: '',
decimalSeparator: '.',
groupSeparator: ',',
groupSize: 3,
secondaryGroupSize: 0,
fractionGroupSeparator: ' ',
fractionGroupSize: 0,
suffix: ''
}
x = new BigNumber('123456789.123456789')
// Set the global formatting options
BigNumber.config({ FORMAT: fmt })
x.toFormat() // '123,456,789.123456789'
x.toFormat(3) // '123,456,789.123'
// If a reference to the object assigned to FORMAT has been retained,
// the format properties can be changed directly
fmt.groupSeparator = ' '
fmt.fractionGroupSize = 5
x.toFormat() // '123 456 789.12345 6789'
// Alternatively, pass the formatting options as an argument
fmt = {
prefix: '=> ',
decimalSeparator: ',',
groupSeparator: '.',
groupSize: 3,
secondaryGroupSize: 2
}
x.toFormat() // '123 456 789.12345 6789'
x.toFormat(fmt) // '=> 12.34.56.789,123456789'
x.toFormat(2, fmt) // '=> 12.34.56.789,12'
x.toFormat
(3, BigNumber.ROUND_UP, fmt
) // '=> 12.34.56.789,124'<
/pre>
toFraction<
code class='inset'>.toFraction
([maximum_denominator
])
<
i>⇒
[BigNumber, BigNumber
]<
/i><
/code>
<
i>number|string|BigNumber<
/i>: integer >
= <
code>
1<
/code> and <
=
Returns an array of two BigNumbers representing the value of this BigNumber 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 <
code>maximum_denominator<
/code>.
If a <
code>maximum_denominator<
/code> is not specified, or is <
code>null<
/code> or
<
code>undefined<
/code>, the denominator will be the lowest
value necessary to represent the
number exactly.
Throws if <
code>maximum_denominator<
/code> is invalid. See <
a href='#Errors'>Errors<
/a>.
x = new BigNumber(1.75)
x.toFraction() // '7, 4'
pi = new BigNumber('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'<
/pre>
<
h5 id="toJSON">toJSON<
code class='inset'>.toJSON
() <
i>⇒ string<
/i><
/code><
/h5>
x = new BigNumber('177.7e+457')
y = new BigNumber(235.4325)
z = new BigNumber('0.0098074')
// Serialize an array of three BigNumbers
str = JSON.stringify( [x, y, z] )
// "["1.777e+459","235.4325","0.0098074"]"
// Return an array of three BigNumbers
JSON.parse(str, function (key, val) {
return key === '' ? val : new BigNumber(val)
<
h5 id="toN">toNumber<
code class='inset'>.toNumber
() <
i>⇒ number<
/i><
/code><
/h5>
<
p>Returns the
value of this BigNumber as a JavaScript number primitive.<
/p>
This method is identical to using type coercion with the unary plus operator.
x = new BigNumber(456.789)
x.toNumber() // 456.789
+x // 456.789
y = new BigNumber('45987349857634085409857349856430985')
y.toNumber() // 4.598734985763409e+34
z = new BigNumber(-0)
1 / z.toNumber() // -Infinity
1 / +z
// -Infinity<
/pre>
toPrecision<
code class='inset'>.toPrecision
([sd
[, rm
]]) <
i>⇒ string<
/i><
/code>
Returns a string representing the
value of this BigNumber rounded to <
code>sd<
/code>
significant digits using rounding mode <
code>rm<
/code>.
If <
code>sd<
/code> 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.
return
value is the same as <
code>n.toString
()<
/code>.<
br />
<
a href='#rounding-mode'><
code>ROUNDING_MODE<
/code><
/a> is used.
Throws if <
code>sd<
/code> or <
code>rm<
/code> is invalid. See <
a href='#Errors'>Errors<
/a>.
x = 45.6
y = new BigNumber(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'<
/pre>
<
h5 id="toS">toString<
code class='inset'>.toString
([base
]) <
i>⇒ string<
/i><
/code><
/h5>
inclusive
(see <
a href='#alphabet'><
code>ALPHABET<
/code><
/a>
).
Returns a string representing the value of this BigNumber in the specified base, or base
For bases above <
code>
10<
/code>, and using the default base conversion alphabet
(as with <
code>Number.prototype.toString<
/code>
).
If a base is specified the value is rounded according to the current
<
a href='#decimal-places'><
code>DECIMAL_PLACES<
/code><
/a>
and <
a href='#rounding-mode'><
code>ROUNDING_MODE<
/code><
/a> settings.
If a base is not specified, and this BigNumber has a positive
exponent that is equal to or greater than the positive component of the
current <
a href="#exponential-at"><
code>EXPONENTIAL_AT<
/code><
/a> setting,
or a negative exponent equal to or less than the negative component of the
setting, then exponential notation is returned.
Throws if <
code>base<
/code> is invalid. See <
a href='#Errors'>Errors<
/a>.
x = new BigNumber(750000)
x.toString() // '750000'
BigNumber.config({ EXPONENTIAL_AT: 5 })
x.toString() // '7.5e+5'
y = new BigNumber(362.875)
y.toString(2) // '101101010.111'
y.toString(9) // '442.77777777777777777778'
y.toString(32) // 'ba.s'
BigNumber.config({ DECIMAL_PLACES: 4 });
z = new BigNumber('1.23456789')
z.toString() // '1.23456789'
z.toString
(10) // '1.2346'<
/pre>
<
h5 id="valueOf">valueOf<
code class='inset'>.valueOf
() <
i>⇒ string<
/i><
/code><
/h5>
As <
a href='#toS'><
code>toString<
/code><
/a>, but does not
accept a base argument and includes
the minus sign for negative zero.
x = new BigNumber('-0')
x.toString() // '0'
x.valueOf() // '-0'
y = new BigNumber('1.777e+457')
y.valueOf
() // '1.777e+457'<
/pre>
<
h4 id="instance-properties">Properties<
/h4>
<
p>The properties of a BigNumber instance:<
/p>
<
td class='centre' id='coefficient'><
b>c<
/b><
/td>
<
td class='centre' id='exponent'><
b>e<
/b><
/td>
<
td class='centre' id='sign'><
b>s<
/b><
/td>
The above properties are best considered to be read-only. In early versions of this library it
was okay to change the exponent of a BigNumber by writing to its exponent property directly,
but this is no longer reliable as the value of the first element of the coefficient array is
now dependent on the exponent.
Note that, as with JavaScript numbers, the original exponent and fractional trailing zeros are
not necessarily preserved.
<
pre>x
= new BigNumber
(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 BigNumber('-123.4567000e+2') // '-12345.67'
z.toExponential() // '-1.234567e+4'
z.c // '1,2,3,4,5,6,7'
z.e // 4
<
h4 id="zero-nan-infinity">Zero, NaN and Infinity<
/h4>
±<
code>Infinity<
/code> are stored.
<
th class='centre'>c<
/th>
<
th class='centre'>e<
/th>
<
th class='centre'>s<
/th>
<
td>±Infinity<
/td>
x = new Number(-0) // 0
1 / x == -Infinity // true
y = new BigNumber(-0) // '0'
y.c // '0' ( [0].toString() )
y.e // 0
<
h4 id='Errors'>Errors<
/h4>
<
p>The table below shows the errors that are thrown.<
/p>
The errors are generic <
code>Error<
/code> objects whose message begins
<
table class='error-table'>
<
td>Base not a primitive number<
/td>
<
td>Base not an integer<
/td>
<
td>Base out of range<
/td>
<
td>Number primitive has more than
15 significant digits<
sup>*<
/sup><
/td>
<
td>Argument not a primitive number<
/td>
<
td>Argument not an integer<
/td>
<
td>Argument out of range<
/td>
<
td>Argument not true or false<
/td>
<
td>Argument not an integer<
/td>
<
td>crypto unavailable<
/td>
<
td>Argument not an object<
/td>
<
td>Argument not an integer<
/td>
<
td>Argument out of range<
/td>
<
td>Base not a primitive number<
/td>
<
td>Base not an integer<
/td>
<
td>Base out of range<
/td>
<
p>To determine if an exception is a BigNumber Error:<
/p>
try {
// ...
} catch (e) {
if (e instanceof Error && e.message.indexOf('[BigNumber Error]') === 0) {
// ...
}
<
h4 id="type-coercion">
Type coercion<
/h4>
To prevent the accidental use of a BigNumber in primitive number operations, or the
accidental addition of a BigNumber to a string, the <
code>valueOf<
/code>
method can be safely
overwritten as shown below.
The <
a href='#valueOf'><
code>valueOf<
/code><
/a>
method is the same as the
<
a href='#toJSON'><
code>toJSON<
/code><
/a>
method, and both are the same as the
<
a href='#toS'><
code>toString<
/code><
/a>
method except they do not take a <
code>base<
/code>
argument and they include the minus sign for negative zero.
BigNumber.prototype.valueOf = function () {
throw Error('valueOf called!')
}
x = new BigNumber(1)
x / 2 // '[BigNumber Error] valueOf called!'
x + 'abc' // '[BigNumber Error] valueOf called!'
<
h6>Why are trailing fractional zeros removed from BigNumbers?<
/h6>
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<
/pre>
To specify the precision of a value is to specify that the value lies
within a certain range.
In the first example, <
code>x<
/code> has a
value of <
code>
1.0<
/code>. The trailing zero shows
the precision of the
value, implying that it is in the range <
code>
0.95<
/code> to
<
code>
1.05<
/code>. Similarly, the precision indicated by the trailing zeros of <
code>y<
/code>
indicates that the
value is in the range <
code>
1.09995<
/code> to <
code>
1.10005<
/code>.
If we add the two lowest values in the ranges we have, <
code>
0.95 +
1.09995 = 2.04995<
/code>,
and if we add the two highest values we have, <
code>
1.05 +
1.10005 = 2.15005<
/code>, so the
range of the result of the addition implied by the precision of its operands is
The result given by BigDecimal of <
code>
2.1000<
/code> however, indicates that the
value is in
the range <
code>
2.09995<
/code> to <
code>
2.10005<
/code> and therefore the precision implied by
its trailing zeros may be misleading.
In the second example, the true range is <
code>
4.122744<
/code> to <
code>
4.157256<
/code> yet
the BigDecimal answer of <
code>
4.1400000<
/code> indicates a range of <
code>
4.13999995<
/code>
to <
code>
4.14000005<
/code>. 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 <
code>toExponential<
/code>, <
code>toFixed<
/code> and
<
code>toPrecision<
/code> methods enable trailing zeros to be added if and when required.<
br />