bignumber.js

A JavaScript library for arbitrary-precision arithmetic.

Hosted on GitHub. 

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

BigNumberBigNumber(value [, base]) ⇒ BigNumber

value

number|string|BigNumber: see RANGE for range.

A numeric value.

Legitimate values include ±0, ±Infinity and NaN.

Values of type number with more than 15 significant digits are considered invalid (if ERRORS is true) as calling toString or valueOf on such numbers may not result in the intended value.

console.log( 823456789123456.3 );    // 823456789123456.2

There is no limit to the number of digits of a value of type string (other than that of JavaScript's maximum array size).

Decimal string values may be in exponential, as well as normal (fixed-point) notation. Non-decimal values must be in normal notation.

String values in hexadecimal literal form, e.g. '0xff', are 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.

Values in any base may have fraction digits.

For bases from 10 to 36, lower and/or upper case letters can be used to represent values from 10 to 35.

For bases above 36, a-z represents values from 10 to 35, A-Z from 36 to 61, and $ and _represent 62 and 63 respectively (this can be changed by editing the ALPHABET variable near the top of the source file).

base

number: integer, 2 to 64 inclusive

The base of value.

If base is omitted, or is null or undefined, base 10 is assumed.

Returns a new instance of a BigNumber object.

If a base is specified, the value is rounded according to the current DECIMAL_PLACES andROUNDING_MODE configuration.

See Errors for the treatment of an invalid value or base.

x = new BigNumber(9)                       // '9'
y = new BigNumber(x)                       // '9'

// 'new' is optional if ERRORS is false
BigNumber(435.345)                         // '435.345'

new BigNumber('5032485723458348569331745.33434346346912144534543')
new BigNumber('4.321e+4')                  // '43210'
new BigNumber('-735.0918e-430')            // '-7.350918e-428'
new BigNumber(Infinity)                    // 'Infinity'
new BigNumber(NaN)                         // 'NaN'
new BigNumber('.5')                        // '0.5'
new BigNumber('+2')                        // '2'
new BigNumber(-10110100.1, 2)              // '-180.5'
new BigNumber(-0b10110100.1)               // '-180.5'
new BigNumber('123412421.234324', 5)       // '607236.557696'
new BigNumber('ff.8', 16)                  // '255.5'
new BigNumber('0xff.8')                    // '255.5'

The following throws 'not a base 2 number' if ERRORS is true, otherwise it returns a BigNumber with value NaN.

new BigNumber(9, 2)

The following throws 'number type has more than 15 significant digits' if errors is true, otherwise it returns a BigNumber with value 96517860459076820.

new BigNumber(96517860459076817.4395)

The following throws 'not a number' if ERRORS is true, otherwise it returns a BigNumber with value NaN.

new BigNumber('blurgh')

A value is only rounded by the constructor if a base is specified.

BigNumber.config({ DECIMAL_PLACES: 5 })
new BigNumber(1.23456789)                  // '1.23456789'
new BigNumber(1.23456789, 10)              // '1.23457'

Methods

The static methods of a BigNumber constructor.

another.another([obj]) ⇒ BigNumber constructor

obj: object

Returns a new independent BigNumber constructor with configuration as described by obj (see config), or with the default configuration if obj is null or undefined.

BigNumber.config({ DECIMAL_PLACES: 5 })
BN = BigNumber.another({ DECIMAL_PLACES: 9 })

x = new BigNumber(1)
y = new BN(1)

x.div(3)                        // 0.33333
y.div(3)                        // 0.333333333

// BN = BigNumber.another({ DECIMAL_PLACES: 9 }) is equivalent to:
BN = BigNumber.another()
BN.config({ DECIMAL_PLACES: 9 })

configconfig([obj]) ⇒ object

obj: object: an object that contains some or all of the following properties.

Configures the 'global' settings for this particular BigNumber constructor.

Note: the configuration can also be supplied as an argument list, see below.

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.config(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 round,toExponential, toFixed, toFormat and toPrecision.

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

BigNumber.config({ ROUNDING_MODE: 0 })
BigNumber.config(null, 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.

ERRORS

boolean|number: true, false, 0 or 1.
Default value: true

The value that determines whether BigNumber Errors are thrown.
If ERRORS is false, no errors will be thrown.

See Errors.

BigNumber.config({ ERRORS: false })

CRYPTO

boolean|number: true, false, 0 or 1.
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 usingcrypto.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 if ERRORS is true 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