A JavaScript library for arbitrary-precision arithmetic.
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.
BigNumber(n [, base]) ⇒ BigNumber
n
: number|string|BigNumber
base
: number: integer, 2
to 36
inclusive. (See
ALPHABET
to extend this range).
Returns a new instance of a BigNumber object with value n
, where n
is a numeric value in the specified base
, or base 10
if
base
is omitted or is null
or undefined
.
x = new BigNumber(123.4567) // '123.4567' // 'new' is optional y = BigNumber(x) // '123.4567'
If n
is a base 10
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'
Signed 0
, signed Infinity
and NaN
are supported.
new BigNumber('-Infinity') // '-Infinity' new BigNumber(NaN) // 'NaN' new BigNumber(-0) // '0' new BigNumber('.5') // '0.5' new BigNumber('+2') // '2'
String values in hexadecimal literal form, e.g. '0xff'
, are valid, as are
string values with the octal and binary prefixs '0o'
and '0b'
.
String values in octal literal form without the prefix will be interpreted as
decimals, e.g. '011'
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'
If a base is specified, n
is rounded according to the current
DECIMAL_PLACES
and
ROUNDING_MODE
settings. This includes base
10
so don't include a base
parameter for decimal values unless
this behaviour is wanted.
BigNumber.config({ DECIMAL_PLACES: 5 }) new BigNumber(1.23456789) // '1.23456789' new BigNumber(1.23456789, 10) // '1.23457'
An error is thrown if base
is invalid. See Errors.
There is no limit to the number of digits of a value of type string (other than
that of JavaScript's maximum array size). See RANGE
to set
the maximum and minimum possible exponent value of a BigNumber.
new BigNumber('5032485723458348569331745.33434346346912144534543') new BigNumber('4.321e10000000')
BigNumber NaN
is returned if n
is invalid
(unless BigNumber.DEBUG
is true
, see below).
new BigNumber('.1*') // 'NaN' new BigNumber('blurgh') // 'NaN' new BigNumber(9, 2) // 'NaN'
To aid in debugging, if BigNumber.DEBUG
is true
then an error will
be thrown on an invalid n
. An error will also be thrown if n
is of
type number with more than 15
significant digits, as calling
toString
or valueOf
on
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)
A BigNumber can also be created from an object literal.
Use isBigNumber
to check that it is well-formed.
new BigNumber({ s: 1, e: 2, c: [ 777, 12300000000000 ], _isBigNumber: true }) // '777.123'
The static methods of a BigNumber constructor.
.clone([object]) ⇒ BigNumber constructor
object
: object
Returns a new independent BigNumber constructor with configuration as described by
object
(see config
), or with the default
configuration if object
is null
or undefined
.
Throws if object
is not an object. See Errors.
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 })
set([object]) ⇒ object
object
: object: an object that contains some or all of the following
properties.
Configures the settings for this particular BigNumber constructor.
DECIMAL_PLACES
0
to 1e+9
inclusive20
BigNumber.config({ DECIMAL_PLACES: 5 }) BigNumber.set({ DECIMAL_PLACES: 5 }) // equivalent
ROUNDING_MODE
0
to 8
inclusive4
(ROUND_HALF_UP
)
decimalPlaces
,
precision
,
toExponential
,
toFixed
,
toFormat
and
toPrecision
.
BigNumber.config({ ROUNDING_MODE: 0 }) BigNumber.set({ ROUNDING_MODE: BigNumber.ROUND_UP }) // equivalent
EXPONENTIAL_AT
0
to 1e+9
inclusive, or
-1e+9
to 0
inclusive, integer
0
to 1e+9
inclusive ][-7, 20]
toString
returns exponential notation.
[-7, 20]
.
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 })
EXPONENTIAL_AT
, the toFixed
method
will always return a value in normal notation and the toExponential
method
will always return a value in exponential form.
toString
with a base argument, e.g. toString(10)
, will
also always return normal notation.
RANGE
1
to 1e+9
inclusive, or
-1e+9
to -1
inclusive, integer
1
to 1e+9
inclusive ][-1e+9, 1e+9]
Infinity
and underflow to
zero occurs.
Infinity
and those with a
negative exponent of greater magnitude become zero.
Infinity
, use [-324, 308]
.
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
9.999...e+1000000000
.1e-1000000000
.
CRYPTO
true
or false
.false
CRYPTO
is set to true
then the
random
method will generate random digits using
crypto.getRandomValues
in browsers that support it, or
crypto.randomBytes
if using Node.js.
CRYPTO
to true
will fail and an exception will be thrown.
CRYPTO
is false
then the source of randomness used will be
Math.random
(which is assumed to generate at least 30
bits of
randomness).
random
.// Node.js global.crypto = require('crypto') BigNumber.config({ CRYPTO: true }) BigNumber.config().CRYPTO // true BigNumber.random() // 0.54340758610486147524
MODULO_MODE
0
to 9
inclusive1
(ROUND_DOWN
)
a mod n
.q = a / n
, is calculated according to the
ROUNDING_MODE
that corresponds to the chosen
MODULO_MODE
.
r
, is calculated as: r = a - n * q
.Property | Value | Description |
---|---|---|
ROUND_UP | 0 | The remainder is positive if the dividend is negative, otherwise it 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))
|
modulo
.BigNumber.config({ MODULO_MODE: BigNumber.EUCLID }) BigNumber.config({ MODULO_MODE: 9 }) // equivalent
POW_PRECISION
0
to 1e+9
inclusive.0
0
, the number of significant digits will not be limited.exponentiatedBy
.BigNumber.config({ POW_PRECISION: 100 })
FORMAT
FORMAT
object configures the format of the string returned by the
toFormat
method.
FORMAT
object that are
recognised, and their default values.
FORMAT
object will not be checked for validity. The existing
FORMAT
object will simply be replaced by the object that is passed in.
The object can include any number of the properties shown below.
toFormat
for examples of usage.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: '' } });
ALPHABET
'0123456789abcdefghijklmnopqrstuvwxyz'
BigNumber
constructor or
toString
.
'+'
and '-'
, or the decimal separator '.'
.
// duodecimal (base 12) BigNumber.config({ ALPHABET: '0123456789TE' }) x = new BigNumber('T', 12) x.toString() // '10' x.toString(12) // 'T'
Returns an object with the above properties and their current values.
Throws if object
is not an object, or if an invalid value is assigned to
one or more of the above properties. See Errors.
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]
.isBigNumber(value) ⇒ boolean
value
: any
Returns true
if value
is a BigNumber instance, otherwise returns
false
.
x = 42 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
If value
is a BigNumber instance and BigNumber.DEBUG
is true
,
then this method will also check if value
is well-formed, and throw if it is not.
See Errors.
The check can be useful if creating a BigNumber from an object literal. See BigNumber.
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'
.max(n...) ⇒ BigNumber
n
: number|string|BigNumber
See BigNumber
for further parameter details.
Returns a BigNumber whose value is the maximum of the arguments.
The return value is always exact and unrounded.
x = new BigNumber('3257869345.0378653') BigNumber.maximum(4e9, x, '123456789.9') // '4000000000' arr = [12, '13', new BigNumber(14)] BigNumber.max.apply(null, arr) // '14'
.min(n...) ⇒ BigNumber
n
: number|string|BigNumber
See BigNumber
for further parameter details.
Returns a BigNumber whose value is the minimum of the arguments.
The return value is always exact and unrounded.
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'
.random([dp]) ⇒ BigNumber
dp
: number: integer, 0
to 1e+9
inclusive
Returns a new BigNumber 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
DECIMAL_PLACES
setting.
Depending on the value of this BigNumber constructor's
CRYPTO
setting 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).
To be able to set CRYPTO
to true
when using
Node.js, the crypto
object must be available globally:
global.crypto = require('crypto')
If CRYPTO
is true
, i.e. one of the
crypto
methods is to be used, the value of a returned BigNumber should be
cryptographically-secure and statistically indistinguishable from a random value.
Throws if dp
is invalid. See Errors.
BigNumber.config({ DECIMAL_PLACES: 10 }) BigNumber.random() // '0.4117936847' BigNumber.random(20) // '0.78193327636914089009'
.sum(n...) ⇒ BigNumber
n
: number|string|BigNumber
See BigNumber
for further parameter details.
Returns a BigNumber whose value is the sum of the arguments.
The return value is always exact and unrounded.
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'
The library's enumerated rounding modes are stored as properties of the 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
|
BigNumber.config({ ROUNDING_MODE: BigNumber.ROUND_CEIL }) BigNumber.config({ ROUNDING_MODE: 2 }) // equivalent
undefined|false|true
If BigNumber.DEBUG
is set true
then an error will be thrown
if this BigNumber constructor receives an invalid value, such as
a value of type number with more than 15
significant digits.
See BigNumber.
An error will also be thrown if the isBigNumber
method receives a BigNumber that is not well-formed.
See isBigNumber
.
BigNumber.DEBUG = true
The methods inherited by a BigNumber instance from its constructor's prototype object.
A BigNumber is immutable in the sense that it is not changed by its methods.
The treatment of ±0
, ±Infinity
and NaN
is
consistent with how JavaScript treats these values.
Many method names have a shorter alias.
.abs() ⇒ BigNumber
Returns a BigNumber whose value is the absolute value, i.e. the magnitude, of the value of this BigNumber.
The return value is always exact and unrounded.
x = new BigNumber(-0.8) y = x.absoluteValue() // '0.8' z = y.abs() // '0.8'
.comparedTo(n [, base]) ⇒ number
n
: number|string|BigNumber
base
: number
See BigNumber for further parameter details.
Returns | |
---|---|
1 |
If the value of this BigNumber is greater than the value of n |
-1 |
If the value of this BigNumber is less than the value of n |
0 |
If this BigNumber and n have the same value |
null |
If the value of either this BigNumber or n is NaN |
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
.dp([dp [, rm]]) ⇒ BigNumber|number
dp
: number: integer, 0
to 1e+9
inclusive
rm
: number: integer, 0
to 8
inclusive
If dp
is a number, returns a BigNumber whose value is the value of this BigNumber
rounded by rounding mode rm
to a maximum of dp
decimal places.
If dp
is omitted, or is null
or undefined
, the return
value is the number of decimal places of the value of this BigNumber, or null
if
the value of this BigNumber is ±Infinity
or NaN
.
If rm
is omitted, or is null
or undefined
,
ROUNDING_MODE
is used.
Throws if dp
or rm
is invalid. See Errors.
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') y.dp() // 102
.div(n [, base]) ⇒ BigNumber
n
: number|string|BigNumber
base
: number
See BigNumber for further parameter details.
Returns a BigNumber whose value is the value of this BigNumber divided by
n
, rounded according to the current
DECIMAL_PLACES
and
ROUNDING_MODE
settings.
x = new BigNumber(355) y = new BigNumber(113) x.dividedBy(y) // '3.14159292035398230088' x.div(5) // '71' x.div(47, 16) // '5'
.idiv(n [, base]) ⇒
BigNumber
n
: number|string|BigNumber
base
: number
See BigNumber for further parameter details.
Returns a BigNumber whose value is the integer part of dividing the value of this BigNumber by
n
.
x = new BigNumber(5) y = new BigNumber(3) x.dividedToIntegerBy(y) // '1' x.idiv(0.7) // '7' x.idiv('0.f', 16) // '5'
.pow(n [, m]) ⇒ BigNumber
n
: number|string|BigNumber: integer
m
: number|string|BigNumber
Returns a BigNumber whose value is the value of this BigNumber exponentiated by
n
, i.e. raised to the power n
, and optionally modulo a modulus
m
.
Throws if n
is not an integer. See Errors.
If n
is negative the result is rounded according to the current
DECIMAL_PLACES
and
ROUNDING_MODE
settings.
As the number of digits of the result of the power operation can grow so large so quickly,
e.g. 123.45610000 has over 50000
digits, the number of significant
digits calculated is limited to the value of the
POW_PRECISION
setting (unless a modulus
m
is specified).
By default POW_PRECISION
is set to 0
.
This means that an unlimited number of significant digits will be calculated, and that the
method's performance will decrease dramatically for larger exponents.
If m
is specified and the value of m
, n
and this
BigNumber are integers, and n
is positive, then a fast modular exponentiation
algorithm is used, otherwise the operation will be performed as
x.exponentiatedBy(n).modulo(m)
with a
POW_PRECISION
of 0
.
Math.pow(0.7, 2) // 0.48999999999999994 x = new BigNumber(0.7) x.exponentiatedBy(2) // '0.49' BigNumber(3).pow(-2) // '0.11111111111111111111'
.integerValue([rm]) ⇒ BigNumber
rm
: number: integer, 0
to 8
inclusive
Returns a BigNumber whose value is the value of this BigNumber rounded to an integer using
rounding mode rm
.
If rm
is omitted, or is null
or undefined
,
ROUNDING_MODE
is used.
Throws if rm
is invalid. See Errors.
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'
The following is an example of how to add a prototype method that emulates JavaScript's
Math.round
function. Math.ceil
, Math.floor
and
Math.trunc
can be emulated in the same way with
BigNumber.ROUND_CEIL
, BigNumber.ROUND_FLOOR
and
BigNumber.ROUND_DOWN
respectively.
BigNumber.prototype.round = function (n) { return n.integerValue(BigNumber.ROUND_HALF_CEIL); }; x.round() // '123'
.eq(n [, base]) ⇒ boolean
n
: number|string|BigNumber
base
: number
See BigNumber for further parameter details.
Returns true
if the value of this BigNumber is equal to the value of
n
, otherwise returns false
.
As with JavaScript, NaN
does not equal NaN
.
Note: This method uses the comparedTo
method internally.
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
.isFinite() ⇒ boolean
Returns true
if the value of this BigNumber is a finite number, otherwise
returns false
.
The only possible non-finite values of a BigNumber are NaN
, Infinity
and -Infinity
.
x = new BigNumber(1) x.isFinite() // true y = new BigNumber(Infinity) y.isFinite() // false
Note: The native method isFinite()
can be used if
n <= Number.MAX_VALUE
.
.gt(n [, base]) ⇒ boolean
n
: number|string|BigNumber
base
: number
See BigNumber for further parameter details.
Returns true
if the value of this BigNumber is greater than the value of
n
, otherwise returns false
.
Note: This method uses the comparedTo
method internally.
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
.gte(n [, base]) ⇒ boolean
n
: number|string|BigNumber
base
: number
See BigNumber for further parameter details.
Returns true
if the value of this BigNumber is greater than or equal to the value
of n
, otherwise returns false
.
Note: This method uses the comparedTo
method internally.
(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
.isInteger() ⇒ boolean
Returns true
if the value of this BigNumber is an integer, otherwise returns
false
.
x = new BigNumber(1) x.isInteger() // true y = new BigNumber(123.456) y.isInteger() // false
.lt(n [, base]) ⇒ boolean
n
: number|string|BigNumber
base
: number
See BigNumber for further parameter details.
Returns true
if the value of this BigNumber is less than the value of
n
, otherwise returns false
.
Note: This method uses the comparedTo
method internally.
(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
.lte(n [, base]) ⇒ boolean
n
: number|string|BigNumber
base
: number
See BigNumber for further parameter details.
Returns true
if the value of this BigNumber is less than or equal to the value of
n
, otherwise returns false
.
Note: This method uses the comparedTo
method internally.
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
.isNaN() ⇒ boolean
Returns true
if the value of this BigNumber is NaN
, otherwise
returns false
.
x = new BigNumber(NaN) x.isNaN() // true y = new BigNumber('Infinity') y.isNaN() // false
Note: The native method isNaN()
can also be used.
.isNegative() ⇒ boolean
Returns true
if the sign of this BigNumber is negative, otherwise returns
false
.
x = new BigNumber(-0) x.isNegative() // true y = new BigNumber(2) y.isNegative() // false
Note: n < 0
can be used if n <= -Number.MIN_VALUE
.
.isPositive() ⇒ boolean
Returns true
if the sign of this BigNumber is positive, otherwise returns
false
.
x = new BigNumber(-0) x.isPositive() // false y = new BigNumber(2) y.isPositive() // true
.isZero() ⇒ boolean
Returns true
if the value of this BigNumber is zero or minus zero, otherwise
returns false
.
x = new BigNumber(-0) x.isZero() && x.isNegative() // true y = new BigNumber(Infinity) y.isZero() // false
Note: n == 0
can be used if n >= Number.MIN_VALUE
.
.minus(n [, base]) ⇒ BigNumber
n
: number|string|BigNumber
base
: number
See BigNumber for further parameter details.
Returns a BigNumber whose value is the value of this BigNumber minus n
.
The return value is always exact and unrounded.
0.3 - 0.1 // 0.19999999999999998 x = new BigNumber(0.3) x.minus(0.1) // '0.2' x.minus(0.6, 20) // '0'
.mod(n [, base]) ⇒ BigNumber
n
: number|string|BigNumber
base
: number
See BigNumber for further parameter details.
Returns a BigNumber whose value is the value of this BigNumber modulo n
, i.e.
the integer remainder of dividing this BigNumber by n
.
The value returned, and in particular its sign, is dependent on the value of the
MODULO_MODE
setting of this BigNumber constructor.
If it is 1
(default value), the result will have the same sign as this BigNumber,
and it will match that of Javascript's %
operator (within the limits of double
precision) and BigDecimal's remainder
method.
The return value is always exact and unrounded.
See MODULO_MODE
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'
.times(n [, base]) ⇒ BigNumber
n
: number|string|BigNumber
base
: number
See BigNumber for further parameter details.
Returns a BigNumber whose value is the value of this BigNumber multiplied by n
.
The return value is always exact and unrounded.
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'
.negated() ⇒ BigNumber
Returns a BigNumber whose value is the value of this BigNumber negated, i.e. multiplied by
-1
.
x = new BigNumber(1.8) x.negated() // '-1.8' y = new BigNumber(-1.3) y.negated() // '1.3'
.plus(n [, base]) ⇒ BigNumber
n
: number|string|BigNumber
base
: number
See BigNumber for further parameter details.
Returns a BigNumber whose value is the value of this BigNumber plus n
.
The return value is always exact and unrounded.
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' x.plus('0.1', 8) // '0.225'
.sd([d [, rm]]) ⇒ BigNumber|number
d
: number|boolean: integer, 1
to 1e+9
inclusive, or true
or false
rm
: number: integer, 0
to 8
inclusive.
If d
is a number, returns a BigNumber whose value is the value of this BigNumber
rounded to a precision of d
significant digits using rounding mode
rm
.
If d
is omitted or is null
or undefined
, the return
value is the number of significant digits of the value of this BigNumber, or null
if the value of this BigNumber is ±Infinity
or NaN
.
If d
is true
then any trailing zeros of the integer
part of a number are counted as significant digits, otherwise they are not.
If rm
is omitted or is null
or undefined
,
ROUNDING_MODE
will be used.
Throws if d
or rm
is invalid. See Errors.
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 y.sd(true) // 6
.shiftedBy(n) ⇒ BigNumber
n
: number: integer,
-9007199254740991
to 9007199254740991
inclusive
Returns a BigNumber whose value is the value of this BigNumber shifted by n
places.
The shift is of the decimal point, i.e. of powers of ten, and is to the left if n
is negative or to the right if n
is positive.
The return value is always exact and unrounded.
Throws if n
is invalid. See Errors.
x = new BigNumber(1.23) x.shiftedBy(3) // '1230' x.shiftedBy(-3) // '0.00123'
.sqrt() ⇒ BigNumber
Returns a BigNumber whose value is the square root of the value of this BigNumber,
rounded according to the current
DECIMAL_PLACES
and
ROUNDING_MODE
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'
.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 BigNumber 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 BigNumber 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
is used.
Throws if dp
or rm
is invalid. See Errors.
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'
.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 BigNumber in normal (fixed-point) notation
rounded to dp
decimal places using rounding mode rm
.
If the value of this BigNumber 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
, the return
value will be unrounded and in normal notation. This is also unlike
Number.prototype.toFixed
, which returns the value to zero decimal places.
It is useful when fixed-point notation is required and the current
EXPONENTIAL_AT
setting causes
toString
to return exponential notation.
If rm
is omitted or is null
or undefined
,
ROUNDING_MODE
is used.
Throws if dp
or rm
is invalid. See Errors.
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'
.toFormat([dp [, rm[, format]]]) ⇒ string
dp
: number: integer, 0
to 1e+9
inclusive
rm
: number: integer, 0
to 8
inclusive
format
: object: see FORMAT
Returns a string representing the value of this BigNumber in normal (fixed-point) notation
rounded to dp
decimal places using rounding mode rm
, and formatted
according to the properties of the format
object.
See FORMAT
and the examples below for the properties of the
format
object, their types, and their usage. A formatting object may contain
some or all of the recognised properties.
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
is used.
If format
is omitted or is null
or undefined
, the
FORMAT
object is used.
Throws if dp
, rm
or format
is invalid. See
Errors.
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'
.toFraction([maximum_denominator])
⇒ [BigNumber, BigNumber]
maximum_denominator
:
number|string|BigNumber: integer >= 1
and <=
Infinity
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 maximum_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.
Throws if maximum_denominator
is invalid. See Errors.
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'
.toJSON() ⇒ string
As valueOf
.
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) })
.toNumber() ⇒ number
Returns the value of this BigNumber as a JavaScript number primitive.
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
.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 BigNumber 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 n.toString()
.
If rm
is omitted or is null
or undefined
,
ROUNDING_MODE
is used.
Throws if sd
or rm
is invalid. See Errors.
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'
.toString([base]) ⇒ string
base
: number: integer, 2
to ALPHABET.length
inclusive (see ALPHABET
).
Returns a string representing the value of this BigNumber in the specified base, or base
10
if base
is omitted or is null
or
undefined
.
For bases above 10
, and using the default base conversion alphabet
(see ALPHABET
), values from 10
to
35
are represented by a-z
(as with Number.prototype.toString
).
If a base is specified the value is rounded according to the current
DECIMAL_PLACES
and ROUNDING_MODE
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 EXPONENTIAL_AT
setting,
or a negative exponent equal to or less than the negative component of the
setting, then exponential notation is returned.
If base
is null
or undefined
it is ignored.
Throws if base
is invalid. See Errors.
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'
.valueOf() ⇒ string
As toString
, 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'
The properties of a BigNumber instance:
Property | Description | Type | Value |
---|---|---|---|
c | coefficient* | number[] |
Array of base 1e14 numbers |
e | exponent | number | Integer, -1000000000 to 1000000000 inclusive |
s | sign | number | -1 or 1 |
*significand
The value of any of the c
, e
and s
properties may also
be null
.
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.
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 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 BigNumber(-0) // '0' y.c // '0' ( [0].toString() ) y.e // 0 y.s // -1
The table below shows the errors that are thrown.
The errors are generic Error
objects whose message begins
'[BigNumber Error]'
.
Method | Throws |
---|---|
BigNumber comparedTo dividedBy dividedToIntegerBy isEqualTo isGreaterThan isGreaterThanOrEqualTo isLessThan isLessThanOrEqualTo minus modulo plus multipliedBy
|
Base not a primitive number |
Base not an integer | |
Base out of range | |
Number primitive has more than 15 significant digits* | |
Not a base... number* | |
Not a number* | |
clone |
Object expected |
config |
Object expected |
DECIMAL_PLACES not a primitive number |
|
DECIMAL_PLACES not an integer |
|
DECIMAL_PLACES out of range |
|
ROUNDING_MODE not a primitive number |
|
ROUNDING_MODE not an integer |
|
ROUNDING_MODE out of range |
|
EXPONENTIAL_AT not a primitive number |
|
EXPONENTIAL_AT not an integer |
|
EXPONENTIAL_AT out of range |
|
RANGE not a primitive number |
|
RANGE not an integer |
|
RANGE cannot be zero |
|
RANGE cannot be zero |
|
CRYPTO not true or false |
|
crypto unavailable |
|
MODULO_MODE not a primitive number |
|
MODULO_MODE not an integer |
|
MODULO_MODE out of range |
|
POW_PRECISION not a primitive number |
|
POW_PRECISION not an integer |
|
POW_PRECISION out of range |
|
FORMAT not an object |
|
ALPHABET invalid |
|
decimalPlaces precision random shiftedBy toExponential toFixed toFormat toPrecision
|
Argument not a primitive number |
Argument not an integer | |
Argument out of range | |
decimalPlaces precision
|
Argument not true or false |
exponentiatedBy |
Argument not an integer |
isBigNumber |
Invalid BigNumber* |
minimum maximum
|
Not a number* |
random
|
crypto unavailable |
toFormat
|
Argument not an object |
toFraction |
Argument not an integer |
Argument out of range | |
toString |
Base not a primitive number |
Base not an integer | |
Base out of range |
*Only thrown if BigNumber.DEBUG
is true
.
To determine if an exception is a BigNumber Error:
try { // ... } catch (e) { if (e instanceof Error && e.message.indexOf('[BigNumber Error]') === 0) { // ... } }
To prevent the accidental use of a BigNumber in primitive number operations, or the
accidental addition of a BigNumber to a string, the valueOf
method can be safely
overwritten as shown below.
The valueOf
method is the same as the
toJSON
method, and both are the same as the
toString
method except they do not take a base
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!'
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.