+
+
bignumber.js
+
+
A JavaScript library for arbitrary-precision arithmetic.
+
+
+ Hosted on GitHub.
+
+
+
+
API
+
+
+ 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 as calling
toString or
+ valueOf on such numbers may not result in the intended
+ value.
+
+ -
+ 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
+ (non-exponential) notation. Non-decimal values must be in normal
+ notation.
+
+ -
+ String values in hexadecimal literal form, e.g.
'0xff', are
+ invalid, and string values in octal literal form 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 ediiting the DIGITS 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 and
+ ROUNDING_MODE settings.
+ Usefully, this means the decimal places of a decimal value
+ passed to the constructor can be limited by explicitly specifying base 10.
+
+
+ See Errors for the treatment of an invalid
+ value or base.
+
+
+x = new BigNumber(9) // '9'
+y = new BigNumber(x) // '9'
+BigNumber(435.345) // 'new' is optional
+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('123412421.234324', 5) // '607236.557696'
+new BigNumber('ff.8', 16) // '255.5'
+
+new BigNumber(9, 2)
+// Throws 'not a base 2 number' if ERRORS is true, otherwise 'NaN'
+
+new BigNumber(96517860459076817.4395)
+// Throws 'number type has more than 15 significant digits'
+// if ERRORS is true, otherwise '96517860459076820'
+
+new BigNumber('blurgh')
+// Throws 'not a number' if ERRORS is true, otherwise 'NaN'
+
+BigNumber.config({DECIMAL_PLACES : 5})
+new BigNumber(1.23456789) // '1.23456789'
+new BigNumber(1.23456789, 10) // '1.23457'
+
+
+
Methods
+
+ The BigNumber constructor has one added method,
+ config, which configures the library-wide settings for
+ arithmetic, formatting and errors.
+
+
+
+ configconfig([settings]) ⇒ object
+
+
+ Note: the settings can also be supplied as an argument list,
+ see below.
+
+
+ settings- object
+
+ -
+ An object that contains some or all of the following properties:
+
+
+
+
+ DECIMAL_PLACES-
+ number : integer,
0 to 1e+9
+ inclusive
+ Default value: 20
+
+ -
+ The maximum number of decimal places of the results of
+ division, square root and base conversion operations, and power
+ operations with negative exponents.
+ I.e. aside from the base conversion which may be involved with any
+ method that accepts a base argument, the value is only relevant to
+ the dividedBy, squareRoot and
+ toPower methods.
+
+ -
+
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 by
+
round,
+ toExponential,
+ toFixed 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, 1 or 0
+ Default value: true
+
+ -
+ The value that determines whether BigNumber Errors are thrown.
+ If ERRORS is false, this library will not throw errors.
+
+ -
+ See Errors.
+
+ -
+
BigNumber.config({ ERRORS : false })
+
+
+
+
+
+
Returns an object with the above properties and their current
+ values.
+
+
+ If the value to be assigned to any of the above properties is
+ null or undefined it is ignored. See
+ Errors for the treatment of invalid values.
+
+
+BigNumber.config({
+ DECIMAL_PLACES : 40,
+ ROUNDING_MODE : BigNumber.ROUND_HALF_CEIL,
+ EXPONENTIAL_AT : [-10, 20],
+ RANGE : [-500, 500],
+ ERRORS : true
+});
+
+// Alternatively but equivalently:
+BigNumber.config( 40, 7, [-10, 20], 500, 1 )
+
+obj = BigNumber.config();
+obj.ERRORS // true
+obj.RANGE // [-500, 500]
+
+
+
+
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.
+
+
+ Method names over 5 letters in length have a shorter alias (except
+ valueOf).
+ Internally, the library always uses the shorter method names.
+
+
+
+
+
+ absoluteValue.abs() ⇒ BigNumber
+
+
+ Returns a BigNumber whose value is the absolute value, i.e. the magnitude,
+ of this BigNumber.
+
+
+x = new BigNumber(-0.8)
+y = x.absoluteValue() // '0.8'
+z = y.abs() // '0.8'
+
+
+
+
+ ceil.ceil() ⇒ BigNumber
+
+
+ Returns a BigNumber whose value is the value of this BigNumber rounded to
+ a whole number in the direction of Infinity.
+
+
+x = new BigNumber(1.3)
+x.ceil() // '2'
+y = new BigNumber(-1.8)
+y.ceil() // '-1'
+
+
+
+
+ floor.floor() ⇒
+ BigNumber
+
+
+ Returns a BigNumber whose value is the value of this BigNumber rounded to
+ a whole number in the direction of -Infinity.
+
+
+x = new BigNumber(1.8)
+x.floor() // '1'
+y = new BigNumber(-1.3)
+y.floor() // '-2'
+
+
+
+
+ negated.neg() ⇒ 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.neg() // '1.3'
+
+
+
+
+ squareRoot.sqrt() ⇒ BigNumber
+
+
+ Returns a BigNumber whose value is the square root of this BigNumber,
+ correctly rounded according to the current
+ DECIMAL_PLACES and
+ ROUNDING_MODE settings.
+
+
+x = new BigNumber(16)
+x.squareRoot() // '4'
+y = new BigNumber(3)
+y.sqrt() // '1.73205080756887729353'
+
+
+
+
+ isFinite.isF() ⇒ 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.isF() // false
+
+ Note: The native method isFinite() can be used if
+ n <= Number.MAX_VALUE.
+
+
+
+
+
+ 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.isNeg() ⇒ 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.isNeg // false
+
+ Note: n < 0 can be used if
+ n <= -Number.MIN_VALUE.
+
+
+
+
+
+ isZero.isZ() ⇒ 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.isZ() // false
+
+ Note: n == 0 can be used if
+ n >= Number.MIN_VALUE.
+
+
+
+
+
+ comparedTo.cmp(n [, base]) ⇒ number
+
+
+ n : number|string|BigNumber
+ base : number
+
+ See constructor 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.cmp(NaN) // null
+y.cmp('110', 2) // -1
+
+
+
+
+ dividedBy.div(n [, base]) ⇒
+ BigNumber
+
+
+ n : number|string|BigNumber
+ base : number
+ See constructor 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'
+
+
+
+
+ minus.minus(n [, base]) ⇒ BigNumber
+
+
+ n : number|string|BigNumber
+ base : number
+ See constructor for further parameter details.
+
+
+
+ Returns a BigNumber whose value is the value of this BigNumber minus
+ n.
+
+
+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 constructor 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 result will have the same sign as this BigNumber, and it will match
+ that of JavaScript's % operator (within the limits of its precision) and
+ BigDecimal's remainder method.
+
+
+1 % 0.9 // 0.09999999999999998
+x = new BigNumber(1)
+x.modulo(0.9) // '0.1'
+y = new BigNumber(33)
+y.mod('a', 33) // '3'
+
+
+
+
+ plus.plus(n [, base]) ⇒ BigNumber
+
+
+ n : number|string|BigNumber
+ base : number
+ See constructor for further parameter details.
+
+
+
+ Returns a BigNumber whose value is the value of this BigNumber plus
+ n.
+
+
+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'
+
+
+
+
+ times.times(n [, base]) ⇒ BigNumber
+
+
+ n : number|string|BigNumber
+ base : number
+ See constructor for further parameter details.
+
+
+
+ Returns a BigNumber whose value is the value of this BigNumber times
+ n.
+
+
+0.6 * 3 // 1.7999999999999998
+x = new BigNumber(0.6)
+y = x.times(3) // '1.8'
+BigNumber('7e+500').times(y) // '1.26e+501'
+x.times('-a', 16) // '-6'
+
+
+
+
+ toPower.pow(exp) ⇒ BigNumber
+
+
+ exp : number : integer, -1e+6 to 1e+6 inclusive
+
+
+ Returns a BigNumber whose value is the value of this BigNumber raised to
+ the power exp.
+
+
+ If exp is negative the result is rounded according to the
+ current DECIMAL_PLACES and
+ ROUNDING_MODE settings.
+
+
+ If exp is not an integer or is out of range:
+
+
+ If ERRORS is true a BigNumber
+ Error is thrown,
+ else if exp is greater than 1e+6, it is interpreted as
+ Infinity;
+ else if exp is less than -1e+6, it is interpreted as
+ -Infinity;
+ else if exp is otherwise a number, it is truncated to an
+ integer;
+ else it is interpreted as NaN.
+
+
+ Note: High value exponents may cause this method to be slow to return.
+
+
+Math.pow(0.7, 2) // 0.48999999999999994
+x = new BigNumber(0.7)
+x.toPower(2) // '0.49'
+BigNumber(3).pow(-2) // '0.11111111111111111111'
+
+new BigNumber(123.456).toPower(1000).toString().length // 5099
+new BigNumber(2).pow(1e+6) // Time taken (Node.js): 9 minutes 34 secs.
+
+
+
+
+ equals.eq(n [, base]) ⇒ boolean
+
+
+ n : number|string|BigNumber
+ base : number
+ See constructor for further parameter details.
+
+
+
+ Returns true if the value of this BigNumber equals 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.equals('1e-324') // false
+BigNumber(-0).eq(x) // true ( -0 === 0 )
+BigNumber(255).eq('ff', 16) // true
+
+y = new BigNumber(NaN)
+y.equals(NaN) // false
+
+
+
+
+ greaterThan.gt(n [, base]) ⇒
+ boolean
+
+
+ n : number|string|BigNumber
+ base : number
+ See constructor 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.greaterThan(BigNumber(0.3).minus(0.2)) // false
+BigNumber(0).gt(x) // false
+BigNumber(11, 3).gt(11.1, 2) // true
+
+
+
+
+ greaterThanOrEqualTo.gte(n [, base]) ⇒
+ boolean
+
+
+ n : number|string|BigNumber
+ base : number
+ See constructor 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.greaterThanOrEqualTo(0.1) // true
+BigNumber(1).gte(x) // true
+BigNumber(10, 18).gte('i', 36) // true
+
+
+
+
+ lessThan.lt(n [, base]) ⇒ boolean
+
+
+ n : number|string|BigNumber
+ base : number
+ See constructor 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.lessThan(0.1) // false
+BigNumber(0).lt(x) // true
+BigNumber(11.1, 2).lt(11, 3) // true
+
+
+
+
+ lessThanOrEqualTo.lte(n [, base]) ⇒
+ boolean
+
+
+ n : number|string|BigNumber
+ base : number
+ See constructor 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.lessThanOrEqualTo(BigNumber(0.3).minus(0.2)) // true
+BigNumber(-1).lte(x) // true
+BigNumber(10, 18).lte('i', 36) // true
+
+
+
+
+ toExponential.toE([decimal_places]) ⇒
+ string
+
+
+ decimal_places : number : integer, 0 to 1e+9 inclusive
+
+
+ Returns a string representing the value of this BigNumber in exponential
+ notation to the specified decimal places, i.e with one digit before the
+ decimal point and decimal_places digits after it. If rounding
+ is necessary, the current
+ ROUNDING_MODE is used.
+
+
+ If the value of this BigNumber in exponential notation has fewer fraction
+ digits then is specified by decimal_places, the return value
+ will be appended with zeros accordingly.
+
+
+ If decimal_places 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.
+
+
+ See Errors for the treatment of other
+ non-integer or out of range decimal_places values.
+
+
+x = 45.6
+y = new BigNumber(x)
+x.toExponential() // '4.56e+1'
+y.toExponential() // '4.56e+1'
+x.toExponential(0) // '5e+1'
+y.toE(0) // '5e+1'
+x.toExponential(1) // '4.6e+1'
+y.toE(1) // '4.6e+1'
+x.toExponential(3) // '4.560e+1'
+y.toE(3) // '4.560e+1'
+
+
+
+
+ toFixed.toF([decimal_places]) ⇒
+ string
+
+
+ decimal_places : number : integer, 0 to 1e+9 inclusive
+
+
+ Returns a string representing the value of this BigNumber in normal
+ notation to the specified fixed number of decimal places, i.e. with
+ decimal_places digits after the decimal point. If rounding is
+ necessary, the current
+ ROUNDING_MODE setting is used.
+
+
+ If the value of this BigNumber in normal notation has fewer fraction
+ digits then is specified by decimal_places, 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 decimal_places is omitted, or is null or
+ undefined, then the return value is the same as n.toString().
+ This is also unlike Number.prototype.toFixed, which returns
+ the value to zero decimal places.
+
+
+ See Errors for the treatment of other
+ non-integer or out of range decimal_places values.
+
+
+x = 45.6
+y = new BigNumber(x)
+x.toFixed() // '46'
+y.toFixed() // '45.6'
+y.toF(0) // '46'
+x.toFixed(3) // '45.600'
+y.toF(3) // '45.600'
+
+
+
+
toNumber.toN() ⇒ number
+
Returns the value of this BigNumber as a number primitive.
+
+ Type coercion with, for example, JavaScript's unary plus operator can alternatively be used,
+ but then a BigNumber with the value minus zero will convert to positive zero.
+
+
+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 // Infinity
+1 / z.toNumber() // -Infinity
+
+
+
+
+ toPrecision.toP([significant_figures]) ⇒
+ string
+
+
+ significant_figures : number : integer, 1 to 1e+9
+ inclusive
+
+
+ Returns a string representing the value of this BigNumber to the
+ specified number of significant digits. If rounding is necessary, the
+ current ROUNDING_MODE setting is
+ used.
+
+
+ If significant_figures is less than the number of digits
+ necessary to represent the integer part of the value in normal notation,
+ then exponential notation is used.
+
+
+ If significant_figures is omitted, or is null or
+ undefined, then the return value is the same as n.toString().
+
+
+ See Errors for the treatment of other
+ non-integer or out of range significant_figures values.
+
+
+x = 45.6
+y = new BigNumber(x)
+x.toPrecision() // '45.6'
+y.toPrecision() // '45.6'
+x.toPrecision(1) // '5e+1'
+y.toP(1) // '5e+1'
+x.toPrecision(5) // '45.600'
+y.toP(5) // '45.600'
+
+
+
+
+ toString.toS([base]) ⇒ string
+
+
+ base : number : integer, 2 to 64 inclusive
+
+
+ Returns a string representing the value of this BigNumber in the specified
+ base, or base 10 if base is omitted. For bases above 10,
+ values from 10 to 35 are represented by a-z (as with
+ Number.toString), 36 to 61 by A-Z, and 62 and 63
+ by $ and _ respectively.
+
+
+ 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.
+
+ See Errors for the treatment of other non-integer or
+ out of range base values.
+
+
+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.
+
+
+x = new BigNumber('1.777e+457')
+x.valueOf() // '1.777e+457'
+
+
+
+
+ toFraction.toFr([max_denominator]) ⇒
+ [string, string]
+
+
+ max_denominator : 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_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.
+
+
+ See Errors for the treatment of other non-integer or
+ out of range max_denominator values.
+
+
+x = new BigNumber(1.75)
+x.toFraction() // '7, 4'
+
+pi = new BigNumber('3.14159265358')
+pi.toFr() // '157079632679,50000000000'
+pi.toFr(100000) // '312689, 99532'
+pi.toFr(10000) // '355, 113'
+pi.toFr(100) // '311, 99'
+pi.toFr(10) // '22, 7'
+pi.toFr(1) // '3, 1'
+
+
+
+
+ round.round([decimal_places [, rounding_mode]])
+ ⇒ BigNumber
+
+
+ decimal_places : number : integer, 0 to 1e+9 inclusive
+
+ rounding_mode : number : integer, 0 to 8 inclusive
+
+
+ Returns a BigNumber whose value is the value of this BigNumber rounded by
+ the specified rounding_mode to a maximum of
+ decimal_places digits after the decimal point.
+
+
+ if decimal_places is omitted, or is null or
+ undefined, the return value is n rounded to a whole number.
+
+
+ if rounding_mode is omitted, or is null or
+ undefined, the current
+ ROUNDING_MODE setting is used.
+
+
+ See Errors for the treatment of other
+ non-integer or out of range decimal_places or
+ rounding_mode values.
+
+
+x = 1234.56
+Math.round(x) // 1235
+
+y = new BigNumber(x)
+y.round() // '1235'
+y.round(1) // '1234.6'
+y.round(2) // '1234.56'
+y.round(10) // '1234.56'
+y.round(0, 1) // '1234'
+y.round(0, 6) // '1235'
+y.round(1, 1) // '1234.5'
+y.round(1, BigNumber.ROUND_HALF_EVEN) // '1234.6'
+y // '1234.56'
+
+
+
+
Properties
+
+ A BigNumber is an object with three properties:
+
+
+
+ | Property |
+ Description |
+ Type |
+ Value |
+
+
+ | c |
+ coefficient* |
+ number[] |
+ Array of single digits |
+
+
+ | e |
+ exponent |
+ number |
+ Integer, -1e+9 to 1e+9 inclusive |
+
+
+ | s |
+ sign |
+ number |
+ -1 or 1 |
+
+
+
*significand
+
+ The value of any of the three properties may also be null.
+
+
+ The value of a BigNumber is stored in a normalised decimal floating point
+ format which corresponds to the value's toExponential form,
+ with the decimal point to be positioned after the most significant
+ (left-most) digit of the coefficient.
+
+
+ Note that, as with JavaScript numbers, the original exponent and
+ fractional trailing zeros are not 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
+
+
+
+ A BigNumber is mutable in the sense that the value of its properties can
+ be changed.
+ For example, to rapidly shift a value by a power of 10:
+
+
+x = new BigNumber('1234.000') // '1234'
+x.toExponential() // '1.234e+3'
+x.c // '1,2,3,4'
+x.e // 3
+
+x.e = -5
+x // '0.00001234'
+
+ If changing the coefficient array directly, which is not recommended, be
+ careful to avoid leading or trailing zeros (unless zero itself is being
+ represented).
+
+
+
+
+
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 errors that are thrown are generic Error objects with
+ name BigNumber Error. The table below shows the errors
+ that may be thrown if ERRORS is true, and the
+ action taken if ERRORS is false.
+
+
+
+ | Method(s) |
+ ERRORS : true
Throw BigNumber Error |
+ ERRORS : false
Action on invalid argument |
+
+
+
+ BigNumber
+ comparedTo
+ dividedBy
+ equals
+ greaterThan
+ greaterThanOrEqualTo
+ lessThan
+ lessThanOrEqualTo
+ minus
+ mod
+ plus
+ times |
+ number type has more than
15 significant digits |
+ Accept. |
+
+
+ | not a base... number |
+ Substitute NaN. |
+
+
+ | base not an integer |
+ Truncate to integer.
Ignore if not a number. |
+
+
+ | base out of range |
+ Ignore. |
+
+
+ | not a number* |
+ Substitute NaN. |
+
+
+ config |
+ DECIMAL_PLACES not an integer |
+ Truncate to integer.
Ignore if not a number. |
+
+
+ DECIMAL_PLACES out of range |
+ Ignore. |
+
+
+ ROUNDING_MODE not an integer |
+ Truncate to integer.
Ignore if not a number. |
+
+
+ ROUNDING_MODE out of range |
+ Ignore. |
+
+
+
+ EXPONENTIAL_AT not an integer
+ or not [integer, integer]
+ |
+ Truncate to integer(s).
Ignore if not number(s). |
+
+
+
+ EXPONENTIAL_AT out of range
+ or not [negative, positive]
+ |
+ Ignore. |
+
+
+
+ RANGE not a non-zero integer
+ or not [integer, integer]
+ |
+ Truncate to integer(s).
Ignore if zero or not number(s). |
+
+
+
+ RANGE out of range
+ or not [negative, positive]
+ |
+ Ignore. |
+
+
+
+ ERRORS not a boolean
+ or binary digit
+ |
+ Ignore. |
+
+
+ toPower |
+ exponent not an integer |
+ Truncate to integer.
Substitute NaN if not a number. |
+
+
+ | exponent out of range |
+ Substitute ±Infinity.
+ |
+
+
+ round |
+ decimal places not an integer |
+ Truncate to integer.
Ignore if not a number. |
+
+
+ | decimal places out of range |
+ Ignore. |
+
+
+ | mode not an integer |
+ Truncate to integer.
Ignore if not a number. |
+
+
+ | mode out of range |
+ Ignore. |
+
+
+ toExponential |
+ decimal places not an integer |
+ Truncate to integer.
Ignore if not a number. |
+
+
+ | decimal places out of range |
+ Ignore. |
+
+
+ toFixed |
+ decimal places not an integer |
+ Truncate to integer.
Ignore if not a number. |
+
+
+ | decimal places out of range |
+ Ignore. |
+
+
+ toFraction |
+ max denominator not an integer |
+ Truncate to integer.
Ignore if not a number. |
+
+
+ | max denominator out of range |
+ Ignore. |
+
+
+ toPrecision |
+ precision not an integer |
+ Truncate to integer.
Ignore if not a number. |
+
+
+ | precision out of range |
+ Ignore. |
+
+
+ toString |
+ base not an integer |
+ Truncate to integer.
Ignore if not a number. |
+
+
+ | base out of range |
+ Ignore. |
+
+
+
+ *No error is thrown if the value is NaN or 'NaN'
+
+
+ The message of a BigNumber Error will also contain the name of the
+ method from which the error originated.
+
+
+ To determine if an exception is a BigNumber Error:
+
+
+try {
+ // ...
+} catch (e) {
+ if ( e instanceof Error && e.name == 'BigNumber Error' ) {
+ // ...
+ }
+}
+
+
FAQ
+
Why are trailing fractional zeros removed from BigNumbers?
+
+ Many 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 get 0.95 +
+ 1.09995 = 2.04995 and if we add the two highest values we get 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 is 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 is
+ 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.
+
+
+
+