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_PLACES0 to 1e+9 inclusive20
- BigNumber.config({ DECIMAL_PLACES: 5 })
-BigNumber.set({ DECIMAL_PLACES: 5 }) // equivalent
- ROUNDING_MODE0 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_AT0 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.
- RANGE1 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.
- CRYPTOtrue 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_MODE0 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_PRECISION0 to 1e+9 inclusive.0
- 0, the number of significant digits will not be limited.exponentiatedBy.BigNumber.config({ POW_PRECISION: 100 })FORMATFORMAT 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() ⇒ stringAs 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() ⇒ numberReturns 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.
-