bignumber.js

A JavaScript library for arbitrary-precision arithmetic.

API

See the README on GitHub for a quick-start introduction.

In all examples below, var and semicolons are not shown, and if a commented-out value is in quotes it means toString has been called on the preceding expression.

CONSTRUCTOR

BigNumber`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)

Methods

The static methods of a BigNumber constructor.

clone `.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 })

config`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

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

The maximum 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.

BigNumber.config({ DECIMAL_PLACES: 5 })
BigNumber.set({ DECIMAL_PLACES: 5 })    // equivalent

ROUNDING_MODE

number: integer, 0 to 8 inclusive
Default value: 4 (ROUND_HALF_UP)

The rounding mode used in the above operations and the default rounding mode of decimalPlaces, precision, toExponential, toFixed, toFormat and toPrecision.

The modes are available as enumerated properties of the BigNumber constructor.

BigNumber.config({ ROUNDING_MODE: 0 })
BigNumber.set({ ROUNDING_MODE: BigNumber.ROUND_UP })    // equivalent

EXPONENTIAL_AT

number: integer, magnitude 0 to 1e+9 inclusive, or
number[]: [ integer -1e+9 to 0 inclusive, integer 0 to 1e+9 inclusive ]
Default value: [-7, 20]

The exponent value(s) at which toString returns exponential notation.

If a single number is assigned, the value is the exponent magnitude.
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 [-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 })

Regardless of the value of 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.

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

RANGE

number: integer, magnitude 1 to 1e+9 inclusive, or
number[]: [ integer -1e+9 to -1 inclusive, integer 1 to 1e+9 inclusive ]
Default value: [-1e+9, 1e+9]

The exponent value(s) beyond which overflow to Infinity 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 Infinity 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 become zero and 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

The largest possible magnitude of a finite BigNumber is 9.999...e+1000000000.
The smallest possible magnitude of a non-zero BigNumber is 1e-1000000000.

CRYPTO

boolean: true or false.
Default value: false

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

If 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 a version of Node.js that supports it.

If neither function is supported by the host environment then attempting to set CRYPTO to true will fail and an exception will be thrown.

If CRYPTO is false then the source of randomness used will be Math.random (which is assumed to generate at least 30 bits of randomness).

See random.

BigNumber.config({ CRYPTO: true })
BigNumber.config().CRYPTO       // true
BigNumber.random()              // 0.54340758610486147524

MODULO_MODE

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

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

The quotient, q = a / n, is calculated according to the ROUNDING_MODE that corresponds to the chosen MODULO_MODE.

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

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

Property	Value	Description
ROUND_UP	0	The remainder is positive if the dividend is negative, 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))`

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

See modulo.

BigNumber.config({ MODULO_MODE: BigNumber.EUCLID })
BigNumber.config({ MODULO_MODE: 9 })          // equivalent

POW_PRECISION

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

The maximum precision, i.e. number of significant digits, of the result of the power operation (unless a modulus is specified).

If set to 0, the number of significant digits will not be limited.

See exponentiatedBy.

BigNumber.config({ POW_PRECISION: 100 })

FORMAT

object

The FORMAT object configures the format of the string returned by the toFormat method.

The example below shows the properties of the FORMAT object that are recognised, and their default values.

Unlike the other configuration properties, the values of the properties of the FORMAT object will not be checked for validity. The existing FORMAT object will simply be replaced by the object that is passed in. The object can include any number of the properties shown below.

See toFormat for examples of usage.

BigNumber.config({
    FORMAT: {
        // the decimal separator
        decimalSeparator: '.',
        // the grouping separator of the integer part
        groupSeparator: ',',
        // the primary grouping size of the integer part
        groupSize: 3,
        // the secondary grouping size of the integer part
        secondaryGroupSize: 0,
        // the grouping separator of the fraction part
        fractionGroupSeparator: ' ',
        // the grouping size of the fraction part
        fractionGroupSize: 0
    }
});

ALPHABET

string
Default value: '0123456789abcdefghijklmnopqrstuvwxyz'

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 BigNumber constructor or toString.

There is no maximum length for the alphabet, but it must be at least 2 characters long, and it must not contain a repeated character, or '.', as that is used as the decimal separator for all values whatever their base.

// 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`.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

maximum`.max([arg1 [, arg2, ...]]) ⇒ BigNumber`

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

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

The argument to this method can also be an array of values.

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(arr)                            // '14'

minimum`.min([arg1 [, arg2, ...]]) ⇒ BigNumber`

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

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

The argument to this method can also be an array of values.

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(arr)                            // '-15.9999'

random`.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).

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'

Properties

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

INSTANCE

Methods

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.

absoluteValue`.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`.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

decimalPlaces`.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

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

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

exponentiatedBy`.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.456¹⁰⁰⁰⁰ 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`.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'

isEqualTo`.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`.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.

isGreaterThan`.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

isGreaterThanOrEqualTo`.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`.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

isLessThan`.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

isLessThanOrEqualTo`.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`.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`.isNegative() ⇒ boolean`

Returns true if the value 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`.isPositive() ⇒ boolean`

Returns true if the value of this BigNumber is positive, otherwise returns false.

x = new BigNumber(-0)
x.isPositive()                  // false
y = new BigNumber(2)
y.isPositive()                  // true

isZero`.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.isneg()         // true
y = new BigNumber(Infinity)
y.isZero()                      // false

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

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

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

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

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

squareRoot`.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`.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`.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 10²¹, 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`.toFormat([dp [, rm]]) ⇒ string`

dp: number: integer, 0 to 1e+9 inclusive
rm: number: integer, 0 to 8 inclusive

Returns a string representing the value of this 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 the examples below for the properties of the FORMAT object, their types and their usage.

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

Throws if dp or rm is invalid. See Errors.

format = {
    decimalSeparator: '.',
    groupSeparator: ',',
    groupSize: 3,
    secondaryGroupSize: 0,
    fractionGroupSeparator: ' ',
    fractionGroupSize: 0
}
BigNumber.config({ FORMAT: format })

x = new BigNumber('123456789.123456789')
x.toFormat()                    // '123,456,789.123456789'
x.toFormat(1)                   // '123,456,789.1'

// If a reference to the object assigned to FORMAT has been retained,
// the format properties can be changed directly
format.groupSeparator = ' '
format.fractionGroupSize = 5
x.toFormat()                    // '123 456 789.12345 6789'

BigNumber.config({
    FORMAT: {
        decimalSeparator: ',',
        groupSeparator: '.',
        groupSize: 3,
        secondaryGroupSize: 2
    }
})

x.toFormat(6)                   // '12.34.56.789,123'

toFraction`.toFraction([max]) ⇒ [string, string]`

max: number|string|BigNumber: integer >= 1 and <= Infinity

Returns a string array 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 max.

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

Throws if max 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`.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`.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`.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`.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`.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'

Properties

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

Zero, NaN and Infinity

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

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

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

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

Errors

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
`minimum` `maximum`	Not a number^*
`random`	crypto unavailable
`toFraction`	Argument not an integer
`toFraction`	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) {
        // ...
    }
}

FAQ

Why are trailing fractional zeros removed from BigNumbers?

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.

bignumber.js

API

CONSTRUCTOR

BigNumberBigNumber(n [, base]) ⇒ BigNumber

Methods

clone .clone([object]) ⇒ BigNumber constructor

configset([object]) ⇒ object

isBigNumber.isBigNumber(value) ⇒ boolean

maximum.max([arg1 [, arg2, ...]]) ⇒ BigNumber

minimum.min([arg1 [, arg2, ...]]) ⇒ BigNumber

random.random([dp]) ⇒ BigNumber

Properties

INSTANCE

Methods

absoluteValue.abs() ⇒ BigNumber

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

decimalPlaces.dp([dp [, rm]]) ⇒ BigNumber|number

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

dividedToIntegerBy.idiv(n [, base]) ⇒ BigNumber

exponentiatedBy.pow(n [, m]) ⇒ BigNumber

integerValue.integerValue([rm]) ⇒ BigNumber

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

isFinite.isFinite() ⇒ boolean

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

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

isInteger.isInteger() ⇒ boolean

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

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

isNaN.isNaN() ⇒ boolean

isNegative.isNegative() ⇒ boolean

isPositive.isPositive() ⇒ boolean

isZero.isZero() ⇒ boolean

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

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

multipliedBy.times(n [, base]) ⇒ BigNumber

negated.negated() ⇒ BigNumber

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

precision.sd([d [, rm]]) ⇒ BigNumber|number

shiftedBy.shiftedBy(n) ⇒ BigNumber

squareRoot.sqrt() ⇒ BigNumber

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

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

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

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

toJSON.toJSON() ⇒ string

toNumber.toNumber() ⇒ number

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

toString.toString([base]) ⇒ string

valueOf.valueOf() ⇒ string

Properties

Zero, NaN and Infinity

Errors

FAQ

Why are trailing fractional zeros removed from BigNumbers?

BigNumber`BigNumber(n [, base]) ⇒ BigNumber`

clone `.clone([object]) ⇒ BigNumber constructor`

config`set([object]) ⇒ object`

isBigNumber`.isBigNumber(value) ⇒ boolean`

maximum`.max([arg1 [, arg2, ...]]) ⇒ BigNumber`

minimum`.min([arg1 [, arg2, ...]]) ⇒ BigNumber`

random`.random([dp]) ⇒ BigNumber`

absoluteValue`.abs() ⇒ BigNumber`

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

decimalPlaces`.dp([dp [, rm]]) ⇒ BigNumber|number`

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

dividedToIntegerBy`.idiv(n [, base]) ⇒ BigNumber`

exponentiatedBy`.pow(n [, m]) ⇒ BigNumber`

integerValue`.integerValue([rm]) ⇒ BigNumber`

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

isFinite`.isFinite() ⇒ boolean`

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

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

isInteger`.isInteger() ⇒ boolean`

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

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

isNaN`.isNaN() ⇒ boolean`

isNegative`.isNegative() ⇒ boolean`

isPositive`.isPositive() ⇒ boolean`

isZero`.isZero() ⇒ boolean`

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

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

multipliedBy`.times(n [, base]) ⇒ BigNumber`

negated`.negated() ⇒ BigNumber`

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

precision`.sd([d [, rm]]) ⇒ BigNumber|number`

shiftedBy`.shiftedBy(n) ⇒ BigNumber`

squareRoot`.sqrt() ⇒ BigNumber`

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

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

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

toFraction`.toFraction([max]) ⇒ [string, string]`

toJSON`.toJSON() ⇒ string`

toNumber`.toNumber() ⇒ number`

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

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

valueOf`.valueOf() ⇒ string`