An arbitrary-precision Decimal type for JavaScript.
The library is incorporated into this page, so it should be available in the console now.
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.
When the library is loaded, it defines a single function object, Decimal, the constructor of Decimal numbers.
Multiple Decimal constructors can be created, each with their own independent configuration, e.g. precision and range, which applies to all Decimal numbers created from it.
A new Decimal constructor is created by calling the constructor method of an already existing Decimal constructor - when the library is loaded this will be Decimal.
Decimal(value [, base]) ⇒ Decimalvalue0, ±Infinity and NaN.errors is true) as calling toString or valueOf on such numbers may not result in the intended value.console.log( 823456789123456.3 ); // 823456789123456.2
'0xff', are invalid, and string values in octal literal form will be interpreted as decimals, e.g. '011' is interpreted as 11, not 9.a-z represents values from 10 to 35, A-Z from 36 to 61, and $ and _ represent 62 and 63 respectively.base2 to 64 inclusivevalue.base is omitted or is null or undefined, base 10 is assumed.Returns a new instance of a Decimal object.
If a base is specified, value is rounded according to the current precision and rounding settings.
See Errors for the treatment of an invalid value or base.
+ + + +++ ++z = x.multiply(y) // 4.1400000decimal.js
+ +An arbitrary-precision Decimal type for JavaScript.
+ ++ + The library is incorporated into this page, so it should be available in the console now. + +
+ +API
+ ++ See the README on GitHub for a quick-start + introduction. +
++ In all examples below,
varand semicolons are not shown, and if a commented-out + value is in quotes it meanstoStringhas been called on the preceding expression. +
++ When the library is loaded, it defines a single function object, +
+Decimal, the constructor of Decimal numbers. ++ Multiple Decimal constructors can be created, each with their own independent configuration, + e.g. precision and range, which applies to all Decimal numbers created from it. +
++ A new Decimal constructor is created by calling the +
+ + + +constructormethod of an already existing Decimal + constructor - when the library is loaded this will be +Decimal. +CONSTRUCTOR
+ ++ Decimal
+Decimal(value [, base]) ⇒ Decimal++
+- +
value- number|string|Decimal
+- A numeric value.
+- + Legitimate values include ±
+0, ±Infinityand +NaN. +- + Values of type number with more than 15 significant digits are considered invalid + (if
+errorsis true) as calling +toStringorvalueOfon + 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). +
+- + See minE and maxE for the allowable range of a + Decimal in terms of exponent limits. +
+- + 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 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-zrepresents values from 10 to 35,A-Zfrom + 36 to 61, and$and_represent 62 and 63 respectively. ++
+- +
base- + number: integer,
+2to64inclusive +- The base of
+value.- + If
+baseis omitted or isnullor undefined, base 10 is assumed. +Returns a new instance of a Decimal object.
++ If a base is specified,
+valueis rounded according to the current +precisionand +roundingsettings. ++ See Errors for the treatment of an invalid
+valueor +base. +x = new Decimal(9) // '9' y = new Decimal(x) // '9' @@ -25,9 +289,60 @@ new Decimal('.5') // '0.5' new Decimal('+2') // '2' new Decimal(-10110100.1, 2) // '-180.5' new Decimal('123412421.234324', 5) // '607236.557696' -new Decimal('ff.8', 16) // '255.5'The following throws
'not a base 2 number'iferrorsis true, otherwise it returns a Decimal with valueNaN.new Decimal(9, 2)The following throws
'number type has more than 15 significant digits'iferrorsis true, otherwise it returns a Decimal with value96517860459076820.new Decimal(96517860459076817.4395)The following throws
'not a number'iferrorsis true, otherwise it returns a Decimal with valueNaN.new Decimal('blurgh')A value is rounded only if a base is specified.
Decimal.config({ precision: 5 }) +new Decimal('ff.8', 16) // '255.5'++ The following throws
+'not a base 2 number'if +errorsis true, otherwise it returns a Decimal with value +NaN. +new Decimal(9, 2)++ The following throws
+'number type has more than 15 significant digits'if +errorsis true, otherwise it returns a Decimal with value +96517860459076820. +new Decimal(96517860459076817.4395)++ The following throws
+'not a number'iferrors+ is true, otherwise it returns a Decimal with valueNaN. +new Decimal('blurgh')++ A value is rounded only if a base is specified. +
+Decimal.config({ precision: 5 }) new Decimal(1.23456789) // '1.23456789' -new Decimal(1.23456789, 10) // '1.2346'Methods
The static methods of a Decimal constructor.
config
.config(object) ⇒ Decimal constructor
object: objectConfigures the 'global' settings for this particular Decimal constructor.
Returns this Decimal constructor.
The configuration object,
object, can contain some or all of the properties described in detail at Properties and shown in the example below.The values of the configuration object properties are checked for validity and then stored as equivalently-named properties of this Decimal constructor.
If the value to be assigned to any of the properties is
nullor undefined it is ignored.
See Errors for the treatment of invalid values.+new Decimal(1.23456789, 10) // '1.2346'+ + + + + +Methods
+The static methods of a Decimal constructor.
+ + + ++ config
+.config(object) ⇒ Decimal constructor++
object: objectConfigures the 'global' settings for this particular Decimal constructor.
+Returns this Decimal constructor.
++ The configuration object,
+object, can contain some or all of the properties + described in detail at Properties and shown in the + example below. ++ The values of the configuration object properties are checked for validity and then stored as + equivalently-named properties of this Decimal constructor. +
++ If the value to be assigned to any of the properties is
+nullor undefined + it is ignored.
See Errors for the treatment of invalid values. +// Defaults Decimal.config({ precision: 20, @@ -39,7 +354,24 @@ Decimal.config({ errors: true, crypto: false, modulo: 1 -})The properties of a Decimal constructor can also be set by direct assignment, but that will obviously by-pass the validity checking that this method performs.
constructor
.constructor([object]) ⇒ Decimal constructor
object: objectReturns a new independent Decimal constructor with configuration settings as described by
object(seeconfig).Decimal.config({ precision: 5 }) +})++ The properties of a Decimal constructor can also be set by direct assignment, but that will + obviously by-pass the validity checking that this method performs. +
+ + + ++ constructor +
+.constructor([object]) ⇒ Decimal constructor++
object: object+ Returns a new independent Decimal constructor with configuration settings as described by +
+object(seeconfig). +Decimal.config({ precision: 5 }) D9 = Decimal.constructor({ precision: 9 }) x = new Decimal(1) @@ -50,21 +382,96 @@ y.div(3) // 0.333333333 // D9 = Decimal.constructor({ precision: 9 }) is equivalent to: D9 = Decimal.constructor() -D9.config({ precision: 9 })It is not inefficient in terms of memory usage to use multiple Decimal constructors as functions are shared between them.
constructoris a factory method so it is not necessary or desirable to usenewbut it will do no harm.D = new Decimal.constructor()exp
.exp() ⇒ DecimalSee
exponential.x = Decimal.exp(3) +D9.config({ precision: 9 })++ It is not inefficient in terms of memory usage to use multiple Decimal constructors as + functions are shared between them. +
++
+constructoris a factory method so it is not necessary or desirable to use +newbut it will do no harm. +D = new Decimal.constructor()+ + + +exp
+.exp() ⇒ DecimalSee
+exponential.x = Decimal.exp(3) y = new Decimal(3).exp() -x.equals(y) // trueln
.ln() ⇒ DecimalSee
naturalLogarithm.x = Decimal.ln(4.321) +x.equals(y) // true+ + + +ln
+.ln() ⇒ DecimalSee
+naturalLogarithm.x = Decimal.ln(4.321) y = new Decimal(4.321).ln() -x.equals(y) // truelog
.log(arg [, base]) ⇒ Decimal
arg: number|string|Decimalbase: number|string|Decimal
SeeDecimalfor further parameter details.See
logarithm.x = Decimal.log(100, 2.5) +x.equals(y) // true+ + + +log
+.log(arg [, base]) ⇒ Decimal+
+arg: number|string|Decimal
+base: number|string|Decimal
+ SeeDecimalfor further parameter details. +See
+logarithm.x = Decimal.log(100, 2.5) y = new Decimal(100).log(2.5) -x.equals(y) // truemax
.max([arg1 [, arg2, ...]]) ⇒ Decimal
arg1,arg2, ... : number|string|Decimal
SeeDecimalfor further parameter details.Returns a new Decimal whose value is the maximum of
arg1,arg2,... .Alternatively, the argument to this method can be an array of values.
x = new Decimal('3257869345.0378653') +x.equals(y) // true+ + + ++ max
+.max([arg1 [, arg2, ...]]) ⇒ Decimal++
+arg1,arg2, ... : number|string|Decimal
+ SeeDecimalfor further parameter details. ++ Returns a new Decimal whose value is the maximum of
+arg1,arg2,... . +Alternatively, the argument to this method can be an array of values.
+x = new Decimal('3257869345.0378653') Decimal.max(4e9, x, '123456789.9') // '4000000000' arr = [12, '13', new Decimal(14)] -Decimal.max(arr) // '14'min
.min([arg1 [, arg2, ...]]) ⇒ Decimal
arg1,arg2, ... : number|string|Decimal
SeeDecimalfor further parameter details.Returns a new Decimal whose value is the minimum of
arg1,arg2,... .Alternatively, the argument to this method can be an array of values.
x = new Decimal('3257869345.0378653') +Decimal.max(arr) // '14'+ + + ++ min
+.min([arg1 [, arg2, ...]]) ⇒ Decimal++
+arg1,arg2, ... : number|string|Decimal
+ SeeDecimalfor further parameter details. ++ Returns a new Decimal whose value is the minimum of
+arg1,arg2,... . +Alternatively, the argument to this method can be an array of values.
+x = new Decimal('3257869345.0378653') Decimal.min(4e9, x, '123456789.9') // '123456789.9' arr = [2, new Decimal(-14), '-15.9999', -12] -Decimal.min(arr) // '-15.9999'noConflict
.noConflict() ⇒ Decimal constructorBrowsers only.
Reverts the
Decimalvariable to the value it had before this library was loaded and returns a reference to the original Decimal constructor so it can be assigned to a variable with a different name.+Decimal.min(arr) // '-15.9999'+ + + ++ noConflict
+.noConflict() ⇒ Decimal constructor+Browsers only.
++ Reverts the
+Decimalvariable to the value it had before this library + was loaded and returns a reference to the original Decimal constructor so it can be assigned + to a variable with a different name. +<script> Decimal = 1 </script> <script src='/path/to/decimal.js'></script> <script> @@ -72,104 +479,576 @@ Decimal.min(arr) // '-15.9999'noC D = Decimal.noConflict() Decimal // 1 y = new D(3) // '3' -</script>
pow
.pow(base, exponent) ⇒ Decimal
base: number|string|Decimalexponent: number|string|Decimal
SeeDecimalfor further parameter details.See
toPower.x = Decimal.pow(3257.4, 17.01) +</script>+ + + +pow
+.pow(base, exponent) ⇒ Decimal+
+base: number|string|Decimal
+exponent: number|string|Decimal
+ SeeDecimalfor further parameter details. +See
+toPower.x = Decimal.pow(3257.4, 17.01) y = new Decimal(3257.4).pow(17.01) -x.equals(y) // truerandom
.random([limit [, sd]]) ⇒ Decimal
limit: number|string|Decimal
Default value:1sd: number: integer, 1 to 1e+9 inclusive
SeeDecimalfor further parameter details.Returns a new Decimal with a pseudo-random value equal to or greater in magnitude than
0and lower in magnitude thanlimit, and with the same sign aslimit.If
limitis omitted then it will be1and the return value will haveprecisionsignificant digits (or less if there are trailing zeros produced).If
limitis included andsdis omitted then the return value will be an integer. Ifsdis included, the return value will havesdsignificant digits (or less if there are trailing zeros produced).If
limitis a high value be sure to include a precision, otherwise this method may be slow to return because all integer digits will be generated.Depending on the value of a Decimal constructor's
cryptoproperty and the support for thecryptoobject in the host environment, the random digits of the return value are generated by eitherMath.random(fastest),crypto.getRandomValues(Web Cryptography API in recent browsers) orcrypto.randomBytes(Node.js).If
cryptoistrue, i.e. one of thecryptomethods is to be used, the value of a returned Decimal should be cryptographically-secure and statistically indistinguishable from a random value.// A value in the range [0, 1) with precision significant digits -Decimal.config({ precision: 10 }) -Decimal.random() // '0.4117936847' +x.equals(y) // true-// A value in the range [0, 1) with 20 significant digits -Decimal.random(1, 20) // '0.48193327636914089007' -// An integer in the range [0, 1) -Decimal.random(1) // '0' (always zero) -// An integer in the range [0, 10) -Decimal.random(10) // '6' ++ random
+.random([dp]) ⇒ Decimal++
dp: number: integer, 0 to 1e+9 inclusive+ Returns a new Decimal with a pseudo-random value equal to or greater than
+0and + less than1. ++ The return value will have
+dpdecimal places (or less if trailing zeros are + produced). Ifdpis omitted then the number of decimal places will + default to the currentprecisionsetting. ++ Depending on the value of a Decimal constructor's
+crypto+ property and the support for thecryptoobject in the host environment, the + random digits of the return value are generated by eitherMath.random(fastest), +crypto.getRandomValues(Web Cryptography API in recent browsers) or +crypto.randomBytes(Node.js). ++ If
+cryptoistrue, i.e. one of the +cryptomethods is to be used, the value of a returned Decimal should be + cryptographically-secure and statistically indistinguishable from a random value. +Decimal.config({ precision: 10 }) +Decimal.random() // '0.4117936847' -// An integer in the range (-100, 0] -Decimal.random(-100) // '-82' +Decimal.random(20) // '0.78193327636914089009'-// An integer in the range [0, 9e9999999999) -Decimal.random('9e99999999999') // A browser will hang -// A value in the range [0, 9e9999999999) with 10 significant digits -Decimal.random('9e99999999999', 25) // '1.508652055e+99999999999' -// A value in the range (-0.0125, 0] with 16 significant digits -Decimal.random(-0.0125, 16) // '-0.0001963482803540358' -// A value in the range [0, 0.9) with 1 significant digit -Decimal.random(0.9, 1) // '0.2'sqrt
.sqrt() ⇒ DecimalSee squareRoot.
x = Decimal.sqrt('987654321.123456789') +sqrt
+.sqrt() ⇒ DecimalSee squareRoot.
+x = Decimal.sqrt('987654321.123456789') y = new Decimal('987654321.123456789').sqrt() -x.equals(y) // trueProperties
The static properties of a Decimal constructor.
ONE
A Decimal instance with value one.
new Decimal(3).times(Decimal.ONE) // '3'Configuration properties
The values of the configuration properties
precision,rounding,minE,maxE,toExpNeg,toExpPos,errors,moduloandcryptoare set using theconfigmethod.As simple object properties they can be set directly without using
config, and it is fine to do so, but the values assigned will not then be checked for validity. For example:Decimal.config({ precision: 0 }) +x.equals(y) // true+ + + + + +Properties
++ The static properties of a Decimal constructor. +
+ + + +ONE
+A Decimal instance with value one.
+new Decimal(3).times(Decimal.ONE) // '3'+ + + +Configuration properties
++ The values of the configuration properties
+precision, +rounding,minE, +maxE,toExpNeg, +toExpPos,errors, +moduloandcryptoare + set using theconfigmethod. ++ As simple object properties they can be set directly without using +
+config, and it is fine to do so, but the values assigned + will not then be checked for validity. For example: +Decimal.config({ precision: 0 }) // 'Decimal Error: config() precision out of range: 0' Decimal.precision = 0 -// No error is thrown and the results of calculations are unpredictableprecision
number: integer,
1to1e+9inclusive
Default value:20The maximum number of significant digits of the result of a calculation or base conversion.
All methods which return a Decimal will round the return value to
precisionsignificant digits exceptabsoluteValue,ceil,floor,negated,round,toDecimalPlaces,toNearestandtruncated.A Decimal constructor will also not round to
precisionunless a base is specified.Decimal.config({ precision: 5 }) -Decimal.precision // 5rounding
number: integer,
0to8inclusive
Default value:4(ROUND_HALF_UP)The default rounding mode used when rounding the result of a calculation or base conversion to
precisionsignificant digits, and when rounding the return value of theround,toDecimalPlaces,toExponential,toFixed,toFormat,toNearest,toPrecisionandtoSignificantDigitsmethods.The rounding modes are available as enumerated properties of the constructor.
Decimal.config({ rounding: Decimal.ROUND_UP }) +// No error is thrown and the results of calculations are unpredictable+ + + +precision
++ number: integer,
+1to1e+9inclusive
+ Default value:20++ The maximum number of significant digits of the result of a calculation or base + conversion. +
++ All methods which return a Decimal will round the return value to
+precision+ significant digits exceptabsoluteValue, +ceil,floor, +negated,round, +toDecimalPlaces,toNearest+ andtruncated. ++ A Decimal constructor will also not round to
+precisionunless a base is + specified. +Decimal.config({ precision: 5 }) +Decimal.precision // 5+ + + +rounding
++ number: integer,
+0to8inclusive
+ Default value:4(ROUND_HALF_UP) ++ The default rounding mode used when rounding the result of a calculation or base conversion to +
+precisionsignificant digits, and when rounding the + return value of theround, +toDecimalPlaces, +toExponential,toFixed, +toFormat,toNearest, +toPrecisionand +toSignificantDigitsmethods. ++ The rounding modes are available as enumerated properties of the + constructor. +
+Decimal.config({ rounding: Decimal.ROUND_UP }) Decimal.config({ rounding: 0 }) // equivalent -Decimal.rounding // 0minE
number: integer,
-9e15to0inclusive
Default value:-9e15The negative exponent limit, i.e. the exponent value below which underflow to zero occurs.
If the
Decimalto be returned by a calculation would have an exponent lower thanminEthen its value becomes zero.JavaScript numbers underflow to zero for exponents below
-324.Decimal.config({ minE: -500 }) +Decimal.rounding // 0+ + + +minE
++ number: integer,
+-9e15to0inclusive
+ Default value:-9e15++ The negative exponent limit, i.e. the exponent value below which underflow to zero occurs. +
++ If the
Decimalto be returned by a calculation would have an exponent lower than +minEthen its value becomes zero. ++ JavaScript numbers underflow to zero for exponents below
+-324. +Decimal.config({ minE: -500 }) Decimal.minE // -500 new Decimal('1e-500') // '1e-500' new Decimal('9.9e-501') // '0' Decimal.config({ minE: -3 }) new Decimal(0.001) // '0.01' e is -3 -new Decimal(0.0001) // '0' e is -4The smallest possible magnitude of a non-zero Decimal is
1e-9000000000000000maxE
number: integer,
0to9e15inclusive
Default value:9e15The positive exponent limit, i.e. the exponent value above which overflow to
Infinityoccurs.If the
Decimalto be returned by a calculation would have an exponent higher thanmaxEthen its value becomesInfinity.JavaScript numbers overflow to
Infinityfor exponents above308.Decimal.config({ maxE: 500 }) +new Decimal(0.0001) // '0' e is -4++ The smallest possible magnitude of a non-zero Decimal is
+ + + +1e-9000000000000000+maxE
++ number: integer,
+0to9e15inclusive
+ Default value:9e15++ The positive exponent limit, i.e. the exponent value above which overflow to +
+Infinityoccurs. ++ If the
Decimalto be returned by a calculation would have an exponent higher than +maxEthen its value becomesInfinity. ++ JavaScript numbers overflow to
+Infinityfor exponents above308. +Decimal.config({ maxE: 500 }) Decimal.maxE // 500 new Decimal('9.999e500') // '9.999e+500' new Decimal('1e501') // 'Infinity' Decimal.config({ maxE: 4 }) new Decimal(99999) // '99999' e is 4 -new Decimal(100000) // 'Infinity'The largest possible magnitude of a finite Decimal is
9.999...e+9000000000000000toExpNeg
number: integer,
-9e15to0inclusive
Default value:-7The negative exponent value at and below which
toStringreturns exponential notation.Decimal.config({ toExpNeg: -7 }) -Decimal.toExpNeg // -7 +new Decimal(100000) // 'Infinity'++ The largest possible magnitude of a finite Decimal is
+ + + +9.999...e+9000000000000000+toExpNeg
++ number: integer,
+-9e15to0inclusive
+ Default value:-7++ The negative exponent value at and below which
+toString+ returns exponential notation. +Decimal.config({ toExpNeg: -7 }) +Decimal.toExpNeg // -7 new Decimal(0.00000123) // '0.00000123' e is -6 new Decimal(0.000000123) // '1.23e-7' // Always return exponential notation: -Decimal.config({ toExpNeg: 0 })JavaScript numbers use exponential notation for negative exponents of
-7and below.Regardless of the value of
toExpNeg, thetoFixedmethod will always return a value in normal notation and thetoExponentialmethod will always return a value in exponential form.Calling
toStringwith a base argument, e.g.toString(10), will also always return normal notation.toExpPos
number: integer,
0to9e15inclusive
Default value:20The positive exponent value at and above which
toStringreturns exponential notation.Decimal.config({ toExpPos: 2 }) +Decimal.config({ toExpNeg: 0 })++ JavaScript numbers use exponential notation for negative exponents of
+-7and + below. ++ Regardless of the value of
+toExpNeg, the +toFixedmethod will always return a value in normal notation + and thetoExponentialmethod will always return a value in + exponential form. ++ Calling
+ + + +toStringwith a base argument, e.g. +toString(10), will also always return normal notation. +toExpPos
++ number: integer,
+0to9e15inclusive
+ Default value:20++ The positive exponent value at and above which
+toString+ returns exponential notation. +Decimal.config({ toExpPos: 2 }) Decimal.toExpPos // 2 new Decimal(12.3) // '12.3' e is 1 new Decimal(123) // '1.23e+2' // Always return exponential notation: -Decimal.config({ toExpPos: 0 })JavaScript numbers use exponential notation for positive exponents of
20and above.Regardless of the value of
toExpPos, thetoFixedmethod will always return a value in normal notation and thetoExponentialmethod will always return a value in exponential form.Calling
toStringwith a base argument, e.g.toString(10), will also always return normal notation.errors
boolean/number:
true, false, 1 or 0
Default value:trueThe value that determines whether Decimal Errors are thrown.
Iferrorsis false, this library will not throw errors.See Errors.
Decimal.config({ errors: false }) -Decimal.errors // falsemodulo
number: integer,
0to9inclusive
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 theroundingmode that corresponds to the chosenmodulomode.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
roundingmodes can be used, they may not give useful results.
Property Value Description ROUND_UP 0 The remainder is positive if the dividend is negative, else 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 Decimal constructor.
Decimal.config({ modulo: Decimal.EUCLID }) +Decimal.config({ toExpPos: 0 })++ JavaScript numbers use exponential notation for positive exponents of
+20and + above. ++ Regardless of the value of
+toExpPos, the +toFixedmethod will always return a value in normal notation + and thetoExponentialmethod will always return a value in + exponential form. ++ Calling
+ + + +toStringwith a base argument, e.g. +toString(10), will also always return normal notation. +errors
++ boolean/number:
+true, false, 1 or 0
Default value:true++ The value that determines whether Decimal Errors are thrown.
+
+ Iferrorsis false, this library will not throw errors. +See Errors.
+Decimal.config({ errors: false }) +Decimal.errors // false+ + + +modulo
++ number: integer,
+0to9inclusive
+ 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 +roundingmode that corresponds to the chosen +modulomode. +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
+roundingmodes can + be used, they may not give useful results. ++
++ Property Value Description + +ROUND_UP 0 +The remainder is positive if the dividend is negative, else 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 Decimal + constructor. +
+Decimal.config({ modulo: Decimal.EUCLID }) Decimal.config({ modulo: 9 }) // equivalent -Decimal.modulo // 9crypto
boolean/number:
true, false, 1 or 0
Default value:falseThe value that determines whether cryptographically-secure pseudo-random number generation is used.
If
cryptois truthy then therandommethod will generate random digits usingcrypto.getRandomValuesin browsers that support it, orcrypto.randomBytesif using a version of Node.js that supports it.If neither function is supported by the host environment or if
cryptois falsey then the source of randomness will beMath.random.+Decimal.modulo // 9+ + + +crypto
++ boolean/number:
+true, false, 1 or 0
Default value: +false++ The value that determines whether cryptographically-secure pseudo-random number generation + is used. +
++ If
+cryptois truthy then therandommethod will + generate random digits usingcrypto.getRandomValuesin browsers that support it, + orcrypto.randomBytesif using a version of Node.js that supports it. ++ If neither function is supported by the host environment or if
+ +cryptois falsey + then the source of randomness will beMath.random. If thecrypto+ property is set directly (i.e. without usingconfig) totrue, then + at the time therandommethod is called, if +errorsistrue, an error will be thrown if the +cryptomethods are unavailable. +Decimal.crypto // false -Decimal.config({ crypto: true })If
crypto.getRandomValuesandcrypto.randomBytesare undefined, the crypto property will remainfalse.Decimal.crypto // falseRounding modes
The library's enumerated rounding modes are stored as properties of a Decimal 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 zeroROUND_HALF_DOWN 5 Rounds towards nearest neighbour.
If equidistant, rounds towards zeroROUND_HALF_EVEN 6 Rounds towards nearest neighbour.
If equidistant, rounds towards even neighbourROUND_HALF_CEIL 7 Rounds towards nearest neighbour.
If equidistant, rounds towards InfinityROUND_HALF_FLOOR 8 Rounds towards nearest neighbour.
If equidistant, rounds towards -InfinityEUCLID 9 Not a rounding mode, see modulo Decimal.config({ rounding: Decimal.ROUND_CEIL }) +Decimal.config({ crypto: true })++ If
+crypto.getRandomValuesandcrypto.randomBytesare undefined, the + crypto property will remainfalse. +Decimal.crypto // false+ + + +Rounding modes
++ The library's enumerated rounding modes are stored as properties of a Decimal 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+ +EUCLID 9 +Not a rounding mode, see modulo +Decimal.config({ rounding: Decimal.ROUND_CEIL }) Decimal.config({ rounding: 2 }) // equivalent -Decimal.rounding // 2INSTANCE
Methods
The methods inherited by a Decimal instance from its constructor's prototype object.
A Decimal is immutable in the sense that it is not changed by its methods.
Methods that return a Decimal can be chained:
x = new Decimal(2).times('999.999999999999999').dividedBy(4).ceil()Methods do not round their arguments before execution.
The treatment of ±
0, ±InfinityandNaNis consistent with how JavaScript treats these values.Some method names have a shorter alias. (Internally, the library always uses the shorter method names.)
absoluteValue
.abs() ⇒ DecimalReturns a new Decimal whose value is the absolute value, i.e. the magnitude, of the value of this Decimal.
The return value is not rounded.
+Decimal.rounding // 2+ + + + + +INSTANCE
+ +Methods
+The methods inherited by a Decimal instance from its constructor's prototype object.
+A Decimal is immutable in the sense that it is not changed by its methods.
+Methods that return a Decimal can be chained:
+x = new Decimal(2).times('999.999999999999999').dividedBy(4).ceil()+Methods do not round their arguments before execution.
++ The treatment of ±
+0, ±InfinityandNaN+ is consistent with how JavaScript treats these values. ++ Some method names have a shorter alias. (Internally, the library always uses the shorter method + names.) +
+ + + +absoluteValue
+.abs() ⇒ Decimal+ Returns a new Decimal whose value is the absolute value, i.e. the magnitude, of the value of + this Decimal. +
+The return value is not rounded.
+x = new Decimal(-0.8) y = x.absoluteValue() // '0.8' -z = y.abs() // '0.8'ceil
.ceil() ⇒ DecimalReturns a new Decimal whose value is the value of this Decimal rounded to a whole number in the direction of positive
Infinity.The return value is not rounded to
precision.+z = y.abs() // '0.8'+ + + +ceil
+.ceil() ⇒ Decimal+ Returns a new Decimal whose value is the value of this Decimal rounded to a whole number in + the direction of positive
+Infinity. +The return value is not rounded to
+precision.x = new Decimal(1.3) x.ceil() // '2' y = new Decimal(-1.8) -y.ceil() // '-1'comparedTo
.cmp(n [, base]) ⇒ number
n: number|string|Decimalbase: number
SeeDecimalfor further parameter details.
Returns 1If the value of this Decimal is greater than the value of n-1If the value of this Decimal is less than the value of n0If this Decimal and nhave the same valuenullIf the value of either this Decimal or nisNaN+y.ceil() // '-1'+ + + +comparedTo
+.cmp(n [, base]) ⇒ number+
+n: number|string|Decimal
+base: number
+ SeeDecimalfor further parameter details. ++
++ Returns + ++ 1If the value of this Decimal is greater than the value of +n+ ++ -1If the value of this Decimal is less than the value of +n+ ++ 0If this Decimal and +nhave the same value+ ++ nullIf the value of either this Decimal or +nisNaNx = new Decimal(Infinity) y = new Decimal(5) x.comparedTo(y) // 1 x.comparedTo(x.minus(1)) // 0 y.cmp(NaN) // null -y.cmp('110', 2) // -1decimalPlaces
.dp() ⇒ numberReturns the number of decimal places, i.e. the number of digits after the decimal point, of the value of this Decimal.
+y.cmp('110', 2) // -1+ + + +decimalPlaces
+.dp() ⇒ number+ Returns the number of decimal places, i.e. the number of digits after the decimal point, of + the value of this Decimal. +
+x = new Decimal(1.234) x.decimalPlaces() // '3' y = new Decimal(987.654321) -y.dp() // '6'dividedBy
.div(n [, base]) ⇒ Decimal
n: number|string|Decimalbase: number
SeeDecimalfor further parameter details.Returns a new Decimal whose value is the value of this Decimal divided by
n, rounded toprecisionsignificant digits using rounding moderounding.+y.dp() // '6'+ + + +dividedBy
+.div(n [, base]) ⇒ Decimal+
+n: number|string|Decimalbase: number
+ SeeDecimalfor further parameter details. ++ Returns a new Decimal whose value is the value of this Decimal divided by
+n, + rounded toprecisionsignificant digits using rounding + moderounding. +x = new Decimal(355) y = new Decimal(113) x.dividedBy(y) // '3.14159292035398230088' x.div(5) // '71' -x.div(47, 16) // '5'dividedToIntegerBy
.divToInt(n [, base]) ⇒ Decimal
n: number|string|Decimalbase: number
SeeDecimalfor further parameter details.Return a new Decimal whose value is the integer part of dividing this Decimal by
n, rounded toprecisionsignificant digits using rounding moderounding.+x.div(47, 16) // '5'+ + + ++ dividedToIntegerBy
+.divToInt(n [, base]) ⇒ Decimal++
+n: number|string|Decimalbase: number
+ SeeDecimalfor further parameter details. ++ Return a new Decimal whose value is the integer part of dividing this Decimal by +
+n, rounded toprecisionsignificant digits + using rounding moderounding. +x = new Decimal(5) y = new Decimal(3) x.dividedToIntegerBy(y) // '1' x.divToInt(0.7) // '7' -x.divToInt('0.f', 16) // '5'equals
.eq(n [, base]) ⇒ boolean
n: number|string|Decimalbase: number
SeeDecimalfor further parameter details.Returns
trueif the value of this Decimal equals the value ofn, otherwise returnsfalse.
As with JavaScript,NaNdoes not equalNaN.Note: This method uses the
cmpmethod internally.+x.divToInt('0.f', 16) // '5'+ + + +equals
+.eq(n [, base]) ⇒ boolean+
+n: number|string|Decimalbase: number
+ SeeDecimalfor further parameter details. ++ Returns
+trueif the value of this Decimal equals the value ofn, + otherwise returnsfalse.
As with JavaScript,NaNdoes not + equalNaN. +Note: This method uses the
+cmpmethod internally.0 === 1e-324 // true x = new Decimal(0) x.equals('1e-324') // false @@ -177,63 +1056,281 @@ new Decimal(-0).eq(x) // true ( -0 === 0 ) new Decimal(255).eq('ff', 16) // true y = new Decimal(NaN) -y.equals(NaN) // falseexponential
.exp() ⇒ DecimalReturns a new Decimal whose value is the base
e(Euler's number, the base of the natural logarithm) exponential of the value of this Decimal, rounded toprecisionsignificant digits using rounding moderounding.The
naturalLogarithmfunction is the inverse of this function.+y.equals(NaN) // false+ + + +exponential
+.exp() ⇒ Decimal+ Returns a new Decimal whose value is the base
+e(Euler's number, the base of the + natural logarithm) exponential of the value of this Decimal, rounded to +precisionsignificant digits using rounding mode +rounding. ++ The
+naturalLogarithmfunction is the inverse of this function. +x = new Decimal(1) x.exponential() // '2.7182818284590452354' y = new Decimal(2) -y.exp() // '7.3890560989306502272'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. (The mathematical result of the exponential function is non-terminating, unless its argument is
0).The performance of this method degrades exponentially with increasing digits.
floor
.floor() ⇒ DecimalReturns a new Decimal whose value is the value of this Decimal rounded to a whole number in the direction of negative
Infinity.The return value is not rounded to
precision.+y.exp() // '7.3890560989306502272'++ 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. (The mathematical result of the + exponential function is non-terminating, unless its argument is
+0). +The performance of this method degrades exponentially with increasing digits.
+ + + +floor
+.floor() ⇒ Decimal+ Returns a new Decimal whose value is the value of this Decimal rounded to a whole number in + the direction of negative
+Infinity. +The return value is not rounded to
+precision.x = new Decimal(1.8) x.floor() // '1' y = new Decimal(-1.3) -y.floor() // '-2'greaterThan
.gt(n [, base]) ⇒ boolean
n: number|string|Decimalbase: number
SeeDecimalfor further parameter details.Returns
trueif the value of this Decimal is greater than the value ofn, otherwise returnsfalse.Note: This method uses the
cmpmethod internally.+y.floor() // '-2'+ + + +greaterThan
+.gt(n [, base]) ⇒ boolean+
+n: number|string|Decimal
+base: number
+ SeeDecimalfor further parameter details. ++ Returns
+trueif the value of this Decimal is greater than the value of +n, otherwise returnsfalse. +Note: This method uses the
+cmpmethod internally.0.1 > (0.3 - 0.2) // true x = new Decimal(0.1) x.greaterThan(Decimal(0.3).minus(0.2)) // false new Decimal(0).gt(x) // false -new Decimal(11, 3).gt(11.1, 2) // truegreaterThanOrEqualTo
.gte(n [, base]) ⇒ boolean
n: number|string|Decimalbase: number
SeeDecimalfor further parameter details.Returns
trueif the value of this Decimal is greater than or equal to the value ofn, otherwise returnsfalse.Note: This method uses the
cmpmethod internally.+new Decimal(11, 3).gt(11.1, 2) // true+ + + ++ greaterThanOrEqualTo
+.gte(n [, base]) ⇒ boolean++
+n: number|string|Decimal
+base: number
+ SeeDecimalfor further parameter details. ++ Returns
+trueif the value of this Decimal is greater than or equal to the value + ofn, otherwise returnsfalse. +Note: This method uses the
+cmpmethod internally.(0.3 - 0.2) >= 0.1 // false x = new Decimal(0.3).minus(0.2) x.greaterThanOrEqualTo(0.1) // true new Decimal(1).gte(x) // true -new Decimal(10, 18).gte('i', 36) // trueisFinite
.isFinite() ⇒ booleanReturns
trueif the value of this Decimal is a finite number, otherwise returnsfalse.
The only possible non-finite values of a Decimal areNaN,Infinityand-Infinity.+new Decimal(10, 18).gte('i', 36) // true+ + + +isFinite
+.isFinite() ⇒ boolean+ Returns
+trueif the value of this Decimal is a finite number, otherwise returns +false.
+ The only possible non-finite values of a Decimal areNaN,Infinity+ and-Infinity. +x = new Decimal(1) x.isFinite() // true y = new Decimal(Infinity) -y.isFinite() // falseNote: The native method
isFinite()can be used ifn <= Number.MAX_VALUE.isInteger
.isInt() ⇒ booleanReturns
trueif the value of this Decimal is a whole number, otherwise returnsfalse.+y.isFinite() // false++ Note: The native method
+ + + +isFinite()can be used if +n <= Number.MAX_VALUE. +isInteger
+.isInt() ⇒ boolean+ Returns
+trueif the value of this Decimal is a whole number, otherwise returns +false. +x = new Decimal(1) x.isInteger() // true y = new Decimal(123.456) -y.isInt() // falseisNaN
.isNaN() ⇒ booleanReturns
trueif the value of this Decimal isNaN, otherwise returnsfalse.+y.isInt() // false+ + + +isNaN
+.isNaN() ⇒ boolean+ Returns
+trueif the value of this Decimal isNaN, otherwise returns +false. +x = new Decimal(NaN) x.isNaN() // true y = new Decimal('Infinity') -y.isNaN() // falseNote: The native method
isNaN()can also be used.isNegative
.isNeg() ⇒ booleanReturns
trueif the value of this Decimal is negative, otherwise returnsfalse.+y.isNaN() // false+Note: The native method
+ + + +isNaN()can also be used.isNegative
+.isNeg() ⇒ boolean+ Returns
+trueif the value of this Decimal is negative, otherwise returns +false. +x = new Decimal(-0) x.isNegative() // true y = new Decimal(2) -y.isNeg // falseNote:
n < 0can be used ifn <= -Number.MIN_VALUE.isZero
.isZero() ⇒ booleanReturns
trueif the value of this Decimal is zero or minus zero, otherwise returnsfalse.+y.isNeg // false+Note:
+ + + +n < 0can be used ifn <= -Number.MIN_VALUE.isZero
+.isZero() ⇒ boolean+ Returns
+trueif the value of this Decimal is zero or minus zero, otherwise + returnsfalse. +x = new Decimal(-0) x.isZero() && x.isNeg() // true y = new Decimal(Infinity) -y.isZero() // falseNote:
n == 0can be used ifn >= Number.MIN_VALUE.lessThan
.lt(n [, base]) ⇒ boolean
n: number|string|Decimalbase: number
SeeDecimalfor further parameter details.Returns
trueif the value of this Decimal is less than the value ofn, otherwise returnsfalse.Note: This method uses the
cmpmethod internally.+y.isZero() // false+Note:
+ + + +n == 0can be used ifn >= Number.MIN_VALUE.lessThan
+.lt(n [, base]) ⇒ boolean+
+n: number|string|Decimalbase: number
+ SeeDecimalfor further parameter details. ++ Returns
+trueif the value of this Decimal is less than the value of +n, otherwise returnsfalse. +Note: This method uses the
+cmpmethod internally.(0.3 - 0.2) < 0.1 // true x = new Decimal(0.3).minus(0.2) x.lessThan(0.1) // false new Decimal(0).lt(x) // true -new Decimal(11.1, 2).lt(11, 3) // truelessThanOrEqualTo
.lte(n [, base]) ⇒ boolean
n: number|string|Decimalbase: number
SeeDecimalfor further parameter details.Returns
trueif the value of this Decimal is less than or equal to the value ofn, otherwise returnsfalse.Note: This method uses the
cmpmethod internally.+new Decimal(11.1, 2).lt(11, 3) // true+ + + ++ lessThanOrEqualTo
+.lte(n [, base]) ⇒ boolean++
+n: number|string|Decimalbase: number
+ SeeDecimalfor further parameter details. ++ Returns
+trueif the value of this Decimal is less than or equal to the value of +n, otherwise returnsfalse. +Note: This method uses the
+cmpmethod internally.0.1 <= (0.3 - 0.2) // false x = new Decimal(0.1) x.lessThanOrEqualTo(Decimal(0.3).minus(0.2)) // true new Decimal(-1).lte(x) // true -new Decimal(10, 18).lte('i', 36) // truelogarithm
.log([n [, base]]) ⇒ Decimal
n: number|string|Decimalbase: number (This is not the base of the logarithm but the base ofn)
SeeDecimalfor further parameter details.Returns a new Decimal whose value is the base
nlogarithm of the value of this Decimal, rounded toprecisionsignificant digits using rounding moderounding.If
nisnullor undefined, then the base 10 logarithm of the value of this Decimal will be returned.+new Decimal(10, 18).lte('i', 36) // true+ + + +logarithm
+.log([n [, base]]) ⇒ Decimal+
+n: number|string|Decimal
+base: number (This is not the base of the logarithm but the base of +n)
+ SeeDecimalfor further parameter details. ++ Returns a new Decimal whose value is the base
+nlogarithm of the value of this + Decimal, rounded toprecisionsignificant digits using + rounding moderounding. ++ If
+nisnullor undefined, then the base 10 logarithm of the + value of this Decimal will be returned. +x = new Decimal(1000) x.logarithm() // '3' y = new Decimal(256) -y.log(2) // '8'The return value will almost always be correctly rounded, i.e. rounded as if the result was first calculated to an infinite number of correct digits before rounding. If a result is incorrectly rounded the maximum error will be
1ulp (unit in the last place).Logarithms to base
2or10will always be correctly rounded.See
toPowerfor the circumstances in which this method may return an incorrectly rounded result.The performance of this method degrades exponentially with increasing digits.
minus
.minus(n [, base]) ⇒ Decimal
n: number|string|Decimalbase: number
SeeDecimalfor further parameter details.Returns a new Decimal whose value is the value of this Decimal minus
n, rounded toprecisionsignificant digits using rounding moderounding.+y.log(2) // '8'++ The return value will almost always be correctly rounded, i.e. rounded as if the result + was first calculated to an infinite number of correct digits before rounding. If a result is + incorrectly rounded the maximum error will be
+1ulp (unit in the last + place). +Logarithms to base
+2or10will always be correctly rounded.+ See
+toPowerfor the circumstances in which this method may + return an incorrectly rounded result. +The performance of this method degrades exponentially with increasing digits.
+ + + +minus
+.minus(n [, base]) ⇒ Decimal+
+n: number|string|Decimal
+base: number
+ SeeDecimalfor further parameter details. ++ Returns a new Decimal whose value is the value of this Decimal minus
+n, rounded + toprecisionsignificant digits using rounding mode +rounding. +0.3 - 0.1 // 0.19999999999999998 x = new Decimal(0.3) x.minus(0.1) // '0.2' -x.minus(0.6, 20) // '0'modulo
.mod(n [, base]) ⇒ Decimal
n: number|string|Decimalbase: number
SeeDecimalfor further parameter details.Returns a new Decimal whose value is the value of this Decimal modulo
n, rounded toprecisionsignificant digits using rounding moderounding.The value returned, and in particular its sign, is dependent on the value of the
moduloproperty of this Decimal's constructor. If it is1(default value), the result will have the same sign as this Decimal, and it will match that of Javascript's%operator (within the limits of double precision) and BigDecimal'sremaindermethod.See
modulofor a description of the other modulo modes.+x.minus(0.6, 20) // '0'+ + + +modulo
+.mod(n [, base]) ⇒ Decimal+
+n: number|string|Decimal
+base: number
+ SeeDecimalfor further parameter details. ++ Returns a new Decimal whose value is the value of this Decimal modulo
+n, + rounded toprecisionsignificant digits using rounding + moderounding. ++ The value returned, and in particular its sign, is dependent on the value of the +
+moduloproperty of this Decimal's constructor. If it is +1(default value), the result will have the same sign as this Decimal, and it + will match that of Javascript's%operator (within the limits of double + precision) and BigDecimal'sremaindermethod. ++ See
+modulofor a description of the other modulo modes. +1 % 0.9 // 0.09999999999999998 x = new Decimal(1) x.modulo(0.9) // '0.1' @@ -246,42 +1343,181 @@ y = new Decimal(-3) Decimal.modulo = 1 x.mod(y) // '2' Decimal.modulo = 3 -x.mod(y) // '-1'naturalLogarithm
.ln() ⇒ DecimalReturns a new Decimal whose value is the natural logarithm of the value of this Decimal, rounded to
precisionsignificant digits using rounding moderounding.The natual logarithm is the inverse of the
exponentialfunction.+x.mod(y) // '-1'+ + + +naturalLogarithm
+.ln() ⇒ Decimal+ Returns a new Decimal whose value is the natural logarithm of the value of this Decimal, + rounded to
+precisionsignificant digits using rounding + moderounding. ++ The natual logarithm is the inverse of the
+exponential+ function. +x = new Decimal(10) x.naturalLogarithm() // '2.3026' y = new Decimal('1.23e+30') -y.ln() // '69.28'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. (The mathematical result of the natural logarithm function is non-terminating, unless its argument is
1).Internally, this method is dependent on a constant whose value is the natural logarithm of
10. ThisLN10variable in the source code currently has a precision of1025digits, meaning that this method can accurately calculate up to1000digits.If more than
1000digits is required then the precision ofLN10will need to be increased to25digits more than is required - though, as the time-taken by this method increases exponentially with increasing digits, it is unlikely to be viable to calculate over1000digits anyway.negated
.neg() ⇒ DecimalReturns a new Decimal whose value is the value of this Decimal negated, i.e. multiplied by
-1.The return value is not rounded.
+y.ln() // '69.28'++ 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. (The mathematical result of the + natural logarithm function is non-terminating, unless its argument is
+1). ++ Internally, this method is dependent on a constant whose value is the natural logarithm of +
+10. ThisLN10variable in the source code currently has a precision + of1025digits, meaning that this method can accurately calculate up to +1000digits. ++ If more than
+ + + +1000digits is required then the precision ofLN10+ will need to be increased to25digits more than is required - though, as the + time-taken by this method increases exponentially with increasing digits, it is unlikely to be + viable to calculate over1000digits anyway. +negated
+.neg() ⇒ Decimal+ Returns a new Decimal whose value is the value of this Decimal negated, i.e. multiplied by +
+-1. +The return value is not rounded.
+x = new Decimal(1.8) x.negated() // '-1.8' y = new Decimal(-1.3) -y.neg() // '1.3'plus
.plus(n [, base]) ⇒ Decimal
n: number|string|Decimalbase: number
SeeDecimalfor further parameter details.Returns a new Decimal whose value is the value of this Decimal plus
n, rounded toprecisionsignificant digits using rounding moderounding.+y.neg() // '1.3'+ + + +plus
+.plus(n [, base]) ⇒ Decimal+
+n: number|string|Decimal
+base: number
+ SeeDecimalfor further parameter details. ++ Returns a new Decimal whose value is the value of this Decimal plus
+n, rounded to +precisionsignificant digits using rounding mode +rounding. +0.1 + 0.2 // 0.30000000000000004 x = new Decimal(0.1) y = x.plus(0.2) // '0.3' new Decimal(0.7).plus(x).plus(y) // '1.1' -x.plus('0.1', 8) // '0.225'precision
.sd([include_zeros]) ⇒ numberReturns the number of significant digits of the value of this Decimal.
If
include_zerosistrueor1then any trailing zeros of the integer part of a number are counted as significant digits, otherwise they are not.+x.plus('0.1', 8) // '0.225'+ + + +precision
+.sd([include_zeros]) ⇒ numberReturns the number of significant digits of the value of this Decimal.
++ If
+include_zerosistrueor1then any trailing zeros + of the integer part of a number are counted as significant digits, otherwise they are not. +x = new Decimal(1.234) x.precision() // '4' y = new Decimal(987000) y.sd() // '3' -y.sd(true) // '6'round
.round() ⇒ DecimalReturns a new Decimal whose value is the value of this Decimal rounded to a whole number using rounding mode
rounding.To emulate
Math.round, setroundingto7, i.e.ROUND_HALF_CEIL.+y.sd(true) // '6'+ + + +round
+.round() ⇒ Decimal+ Returns a new Decimal whose value is the value of this Decimal rounded to a whole number using + rounding mode
+rounding. ++ To emulate
+Math.round, setroundingto +7, i.e.ROUND_HALF_CEIL. +Decimal.config({ rounding: 4 }) x = 1234.5 x.round() // '1235' Decimal.rounding = Decimal.ROUND_DOWN x.round() // '1234' -x // '1234.5'squareRoot
.sqrt() ⇒ DecimalReturns a new Decimal whose value is the square root of this Decimal, rounded to
precisionsignificant digits using rounding moderounding.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.
This method is much faster than using the
toPowermethod with an exponent of0.5.+x // '1234.5'+ + + +squareRoot
+.sqrt() ⇒ Decimal+ Returns a new Decimal whose value is the square root of this Decimal, rounded to +
+precisionsignificant digits using rounding mode +rounding. ++ 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. +
++ This method is much faster than using the
+toPowermethod with + an exponent of0.5. +x = new Decimal(16) x.squareRoot() // '4' y = new Decimal(3) y.sqrt() // '1.73205080756887729353' -y.sqrt().eq( y.pow(0.5) ) // truetimes
.times(n [, base]) ⇒ Decimal
n: number|string|Decimalbase: number
SeeDecimalfor further parameter details.Returns a new Decimal whose value is the value of this Decimal times
n, rounded toprecisionsignificant digits using rounding moderounding.+y.sqrt().eq( y.pow(0.5) ) // true+ + + +times
+.times(n [, base]) ⇒ Decimal+
+n: number|string|Decimal
+base: number
+ SeeDecimalfor further parameter details. ++ Returns a new Decimal whose value is the value of this Decimal times
+n, + rounded toprecisionsignificant digits using rounding + moderounding. +0.6 * 3 // 1.7999999999999998 x = new Decimal(0.6) y = x.times(3) // '1.8' new Decimal('7e+500').times(y) // '1.26e+501' -x.times('-a', 16) // '-6'toDecimalPlaces
.toDP([dp [, rm]]) ⇒ Decimal
dp: number: integer, 0 to 1e+9 inclusiverm: number: integer, 0 to 8 inclusive.Returns a new Decimal whose value is the value of this Decimal rounded to
dpdecimal places using rounding moderm.If
dpis omitted or isnullor undefined, the return value will have the same value as this Decimal.if
rmis omitted or isnullor undefined, rounding moderoundingis used.See Errors for the treatment of other non-integer or out of range
dpvalues.+x.times('-a', 16) // '-6'+ + + ++ toDecimalPlaces
+.toDP([dp [, rm]]) ⇒ Decimal++
+dp: number: integer, 0 to 1e+9 inclusive
+rm: number: integer, 0 to 8 inclusive. ++ Returns a new Decimal whose value is the value of this Decimal rounded to
+dp+ decimal places using rounding moderm. ++ If
+dpis omitted or isnullor undefined, the return value will + have the same value as this Decimal. ++ if
+rmis omitted or isnullor undefined, rounding mode +roundingis used. ++ See Errors for the treatment of other non-integer or out of range +
+dpvalues. +x = new Decimal(12.24567) x.toDecimalPlaces(0) // '12' x.toDecimalPlaces(1, 0) // '12.3' @@ -289,7 +1525,40 @@ x.toDecimalPlaces(1, 0) // '12.3' y = new Decimal(9876.54321) y.toDP(3) // '9876.543' y.toDP(1, 0) // '9876.6' -y.toDP(1, Decimal.ROUND_DOWN) // '9876.5'toExponential
.toExponential([dp [, rm]]) ⇒ string
dp: number: integer, 0 to 1e+9 inclusiverm: number: integer, 0 to 8 inclusiveReturns a string representing the value of this Decimal in exponential notation rounded using rounding mode
rmtodpdecimal places, i.e with one digit before the decimal point anddpdigits after it.If the value of this Decimal in exponential notation has fewer than
dpfraction digits, the return value will be appended with zeros accordingly.If
dpis omitted, or isnullor undefined, the number of digits after the decimal point defaults to the minimum number of digits necessary to represent the value exactly.If
rmis omitted or isnullor undefined, rounding moderoundingis used.See Errors for the treatment of other non-integer or out of range
decimal_placesvalues.+y.toDP(1, Decimal.ROUND_DOWN) // '9876.5'+ + + ++ 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 Decimal in exponential notation rounded + using rounding mode
+rmtodpdecimal places, i.e with one digit + before the decimal point anddpdigits after it. ++ If the value of this Decimal in exponential notation has fewer than
+dpfraction + digits, the return value will be appended with zeros accordingly. ++ If
+dpis omitted, or isnullor undefined, the number of digits + after the decimal point defaults to the minimum number of digits necessary to represent the + value exactly. ++ If
+rmis omitted or isnullor undefined, rounding mode +roundingis used. ++ See Errors for the treatment of other non-integer or out of range +
+decimal_placesvalues. +x = 45.6 y = new Decimal(x) x.toExponential() // '4.56e+1' @@ -300,7 +1569,45 @@ 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 inclusiverm: number: integer, 0 to 8 inclusiveReturns a string representing the value of this Decimal in normal (fixed-point) notation rounded to
dpdecimal places using rounding moderm.If the value of this Decimal in normal notation has fewer than
dpfraction 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 to1021, this method will always return normal notation.If
dpis omitted or isnullor undefined, then the return value will be unrounded and in normal notation. This is unlikeNumber.prototype.toFixed, which returns the value to zero decimal places, but is useful when because of the currenttoExpNegortoExpNegvalues,toStringreturns exponential notation.if
rmis omitted or isnullor undefined, rounding moderoundingis used.See Errors for the treatment of other non-integer or out of range
dpvalues.+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 Decimal in normal (fixed-point) notation + rounded to
+dpdecimal places using rounding moderm. ++ If the value of this Decimal in normal notation has fewer than
+dpfraction 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 to1021, this method will always return normal + notation. ++ If
+dpis omitted or isnullor undefined, then the return value will + be unrounded and in normal notation. This is unlikeNumber.prototype.toFixed, + which returns the value to zero decimal places, but is useful when because of the current +toExpNegor +toExpNegvalues,toString+ returns exponential notation. ++ if
+rmis omitted or isnullor undefined, rounding mode +roundingis used. ++ See Errors for the treatment of other non-integer or out of range +
+dpvalues. +x = 3.456 y = new Decimal(x) x.toFixed() // '3' @@ -310,14 +1617,77 @@ 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([sep1 [, dp [, sep2]]]) ⇒ string
sep1: string: the grouping separator of the integer part of the numbersep2: string: the grouping separator of the fraction part of the numberdp: number: integer, 0 to 8 inclusiveThis method is a placeholder and is likely to be subject to change / further development.
Returns a string representing the value of this Decimal to
dpdecimal places, (seetoFixed), but with the integer part of the number separated bysep1into groups of three digits, and the fraction part of the number separated into groups of five digits bysep2.If
sep1isnullor undefined, the integer part groupings will be separated by a comma.If
sep2isnullor undefined, the fraction part groupings will not be separated.If
dpis omitted or isnullor undefined, then the return value is not rounded to a fixed number of decimal places.A useful separator character is the non-breaking thin-space:
\u202f.+y.toFixed(5) // '3.45600'+ + + ++ toFormat
+.toFormat([sep1 [, dp [, sep2]]]) ⇒ string++
+sep1: string: the grouping separator of the integer part of the number +
+sep2: string: the grouping separator of the fraction part of the number +
+dp: number: integer, 0 to 8 inclusive ++ + This method is a placeholder and is likely to be subject to change / further development. + +
++ Returns a string representing the value of this Decimal to
+dpdecimal places, + (seetoFixed), but with the integer part of the number + separated bysep1into groups of three digits, and the fraction part of the + number separated into groups of five digits bysep2. ++ If
+sep1isnullor undefined, the integer part groupings will be + separated by a comma. ++ If
+sep2isnullor undefined, the fraction part groupings will not + be separated. ++ If
+dpis omitted or isnullor undefined, then the return value is + not rounded to a fixed number of decimal places. +A useful separator character is the non-breaking thin-space:
\u202f.+
x = new Decimal('1.23456000000000000000789e+9') x.toFormat() // '1,234,560,000.00000000000789' x.toFormat(' ') // '1 234 560 000.00000000000789' x.toFormat(',', 2) // '1,234,560,000.00' x.toFormat(' ', 2) // '1 234 560 000.00' x.toFormat(',', 12, ' ') // '1 ,234,560,000.00000 00000 08' -x.toFormat('-', 14, '-') // '1-234-560-000.00000-00000-0789'toFraction
.toFraction([max_denominator]) ⇒ [string, string]
max_denominator: number|string|Decimal:1>= integer <InfinityReturns a string array representing the value of this Decimal 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
nullor 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_denominatorvalues.+x.toFormat('-', 14, '-') // '1-234-560-000.00000-00000-0789'+ + + ++ toFraction +
+.toFraction([max_denominator]) ⇒ [string, string]++
+max_denominator: number|string|Decimal:1>= integer < +Infinity++ Returns a string array representing the value of this Decimal 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
+nullor 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_denominatorvalues. +x = new Decimal(1.75) x.toFraction() // '7, 4' @@ -327,7 +1697,13 @@ 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() ⇒ stringAs
valueOf.+pi.toFraction(1) // '3, 1'+ + + +toJSON
+.toJSON() ⇒ stringAs
+valueOf.x = new Decimal('177.7e+457') y = new Decimal(235.4325) z = new Decimal('0.0098074') @@ -339,18 +1715,62 @@ str = JSON.stringify( [x, y, z] ) // Return an array of three Decimals JSON.parse(str, function (key, val) { return key === '' ? val : new Decimal(val) -})If the
toJSONmethod was not present, the objects (Decimal instances) themselves would be serialized, rather then the string returned byvalueOf:JSON.stringify( [x, y, z] ) +})+If the
+toJSONmethod was not present, the objects (Decimal instances) themselves + would be serialized, rather then the string returned byvalueOf:JSON.stringify( [x, y, z] ) /* -"[{"s":1,"e":459,"c":[1,7,7,7]}, - {"s":1,"e":2,"c":[2,3,5,4,3,2,5]}, - {"s":1,"e":-3,"c":[9,8,0,7,4]}]" - */toNearest
.toNearest(n [, rm]) ⇒ Decimal
n: number|string|Decimalrm: number: integer, 0 to 8 inclusive
SeeDecimalfor further parameter details.Returns a new Decimal whose value is the nearest multiple of
nto the value of this Decimal.If the value of this Decimal is equidistant from two multiples of
n, the rounding moderm, orroundingifrmis omitted or isnullor undefined, determines the direction of the nearest.In this context, rounding mode
ROUND_HALF_UPis interpreted the same as rounding modeROUND_UP, and so on. I.e. the rounding is either up, down, to ceil, to floor or to even.The return value will always have the same sign as this Decimal, unless either this Decimal or
nisNaN, in which case the return value will be also beNaN.The return value is not rounded to
precision.+"[{"s":1,"e":459,"c":[17770]}, + {"s":1,"e":2,"c":[235,4325000]}, + {"s":1,"e":-3,"c":[98074]}]" + */+ + ++ toNearest
+.toNearest(n [, rm]) ⇒ Decimal++
+n: number|string|Decimal
+rm: number: integer, 0 to 8 inclusive
+ SeeDecimalfor further parameter details. ++ Returns a new Decimal whose value is the nearest multiple of
+nto the value of + this Decimal. ++ If the value of this Decimal is equidistant from two multiples of
+n, the rounding + moderm, orroundingifrmis + omitted or isnullor undefined, determines the direction of the nearest. ++ In this context, rounding mode
+ROUND_HALF_UPis + interpreted the same as rounding modeROUND_UP, and so + on. I.e. the rounding is either up, down, to ceil, to floor or to even. ++ The return value will always have the same sign as this Decimal, unless either this Decimal + or
+nisNaN, in which case the return value will be also be +NaN. +The return value is not rounded to
+precision.x = new Decimal(1.39) x.toNearest(0.25) // '1.5' y = new Decimal(0.75) // equidistant from 0.5 and 1 y.toNearest(0.5, 0) // '1' (ROUND_UP) -y.toNearest(0.5, 1) // '0.5' (ROUND_DOWN)toNumber
.toNumber() ⇒ numberReturns the value of this Decimal converted to a number primitive.
Type coercion with, for example, JavaScript's unary plus operator will also work, except that a Decimal with the value minus zero will convert to positive zero.
+y.toNearest(0.5, 1) // '0.5' (ROUND_DOWN)+ + + +toNumber
+.toNumber() ⇒ numberReturns the value of this Decimal converted to a number primitive.
++ Type coercion with, for example, JavaScript's unary plus operator will also work, except that + a Decimal with the value minus zero will convert to positive zero. +
+x = new Decimal(456.789) x.toNumber() // 456.789 +x // 456.789 @@ -360,17 +1780,105 @@ y.toNumber() // 4.598734985763409e+34 z = new Decimal(-0) 1 / +z // Infinity -1 / z.toNumber() // -InfinitytoPower
.pow(n [, base]) ⇒ Decimal
n: number|string|Decimal: integer or non-integerbase: number
SeeDecimalfor further parameter details.Returns a new Decimal whose value is the value of this Decimal raised to the power
n, rounded toprecisionsignificant digits using rounding moderounding.The performance of this method degrades exponentially with increasing digits. For non-integer exponents in particular, even when only quite a small number of significant digits is required, the performance of this method may not be adequate.
+1 / z.toNumber() // -Infinity+ + + +toPower
+.pow(n [, base]) ⇒ Decimal+
+n: number|string|Decimal: integer or non-integer
+base: number
+ SeeDecimalfor further parameter details. ++ Returns a new Decimal whose value is the value of this Decimal raised to the power +
+n, rounded toprecisionsignificant digits + using rounding moderounding. ++ The performance of this method degrades exponentially with increasing digits. For + non-integer exponents in particular, the performance of this method may not be adequate. +
+Math.pow(0.7, 2) // 0.48999999999999994 x = new Decimal(0.7) x.toPower(2) // '0.49' new Decimal(3).pow(-2) // '0.11111111111111111111' new Decimal(1217652.23).pow('98765.489305603941') -// '4.8227010515242461181e+601039'Is the pow function guaranteed to be correctly rounded?
The return value will almost always be correctly rounded, i.e. rounded as if the result was first calculated to an infinite number of correct digits before rounding. If a result is incorrectly rounded the maximum error will be
1ulp (unit in the last place).For non-integer and larger exponents this method uses the formula
xy = exp(y*ln(x))As the mathematical return values of the
expandlnfunctions are both non-terminating (excluding arguments of0or1), the Decimal return values of the functions as implemented by this library will be rounded approximations, which means that there can be no guarantee of correct rounding when they are combined in the above formula.The return value may, depending on the rounding mode, be incorrectly rounded only if the first
15rounding digits are15zeros (and there are non-zero digits following at some point) or15nines (the first rounding digit may also be5or4respectively).Therefore, assuming the first
15rounding digits are each equally likely to be any digit,0-9, the probability of an incorrectly rounded result is less than1in250,000,000,000,000.An example of incorrect rounding:
+// '4.8227010515242461181e+601039'+Is the pow function guaranteed to be correctly rounded?
++ The return value will almost always be correctly rounded, i.e. rounded as if the result + was first calculated to an infinite number of correct digits before rounding. If a result is + incorrectly rounded the maximum error will be
+1ulp (unit in the last + place). +For non-integer and larger exponents this method uses the formula
++xy = exp(y*ln(x))+ As the mathematical return values of the
+expandlnfunctions are + both non-terminating (excluding arguments of0or1), the Decimal + return values of the functions as implemented by this library will be rounded approximations, + which means that there can be no guarantee of correct rounding when they are combined in the + above formula. ++ The return value may, depending on the rounding mode, be incorrectly rounded only if the first +
+15rounding digits are15zeros (and there are non-zero digits + following at some point) or15nines (the first rounding digit may also be +5or4respectively). ++ Therefore, assuming the first
+15rounding digits are each equally likely to be + any digit,0-9, the probability of an incorrectly rounded result is less than +1in250,000,000,000,000. ++ An example of incorrect rounding: +
+Decimal.config({ precision: 20, rounding: 1 }) new Decimal(28).pow('6.166675020000903537297764507632802193308677149') -// 839756321.64088511As the exact mathematical result begins
839756321.6408851099999999999999999999999999998969466049426031167...and the rounding mode is set to
ROUND_DOWN, the correct return value should be839756321.64088510999toPrecision
.toPrecision([sd [, rm]]) ⇒ string
sd: number: integer, 1 to 1e+9 inclusiverm: number: integer, 0 to 8 inclusiveReturns a string representing the value of this Decimal rounded to
sdsignificant digits using rounding moderm.If
sdis 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
sdis omitted or isnullor undefined, then the return value is the same astoString.if
rmis omitted or isnullor undefined, rounding moderoundingis used.See Errors for the treatment of other non-integer or out of range
sdvalues.+// 839756321.64088511+As the exact mathematical result begins
+839756321.6408851099999999999999999999999999998969466049426031167...++ and the rounding mode is set to
+ROUND_DOWN, the correct + return value should be +839756321.64088510999+ + + ++ 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 Decimal rounded to
+sdsignificant + digits using rounding moderm. ++ If
+sdis 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
+sdis omitted or isnullor undefined, then the return value is + the same astoString. ++ if
+rmis omitted or isnullor undefined, rounding mode +roundingis used. ++ See Errors for the treatment of other non-integer or out of range +
+sdvalues. +x = 45.6 y = new Decimal(x) x.toPrecision() // '45.6' @@ -380,7 +1888,34 @@ 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'toSignificantDigits
.toSD([sd [, rm]]) ⇒ Decimal
sd: number: integer, 1 to 1e+9 inclusive.rm: number: integer, 0 to 8 inclusive.Returns a new Decimal whose value is the value of this Decimal rounded to
sdsignificant digits using rounding moderm.If
sdis omitted or isnullor undefined, the return value will be rounded toprecisionsignificant digits.if
rmis omitted or isnullor undefined, rounding moderoundingwill be used.See Errors for the treatment of other non-integer or out of range
sdorrmvalues.+y.toPrecision(5) // '45.600'+ + + ++ toSignificantDigits
+.toSD([sd [, rm]]) ⇒ Decimal++
+sd: number: integer, 1 to 1e+9 inclusive.
+rm: number: integer, 0 to 8 inclusive. ++ Returns a new Decimal whose value is the value of this Decimal rounded to
+sd+ significant digits using rounding moderm. ++ If
+sdis omitted or isnullor undefined, the return value will + be rounded toprecisionsignificant digits. ++ if
+rmis omitted or isnullor undefined, rounding mode +roundingwill be used. ++ See Errors for the treatment of other non-integer or out of range +
+sdorrmvalues. +Decimal.config({ precision: 5, rounding: 4 }) x = new Decimal(9876.54321) @@ -389,7 +1924,37 @@ x.toSignificantDigits(6) // '9876.54' x.toSignificantDigits(6, Decimal.ROUND_UP) // '9876.55' x.toSD(2) // '9900' x.toSD(2, 1) // '9800' -x // '9876.54321'toString
.toString([base]) ⇒ string
base: number: integer, 2 to 64 inclusiveReturns a string representing the value of this Decimal in the specified base, or base 10 if
baseis omitted or isnullor undefined.For bases above 10, values from 10 to 35 are represented by
a-z(as withNumber.prototype.toString), 36 to 61 byA-Z, and 62 and 63 by$and_respectively.If a base is specified the value is rounded to
precisionsignificant digits using rounding moderounding.If a base is not specified and this Decimal has a positive exponent that is equal to or greater than
toExpPos, or a negative exponent equal to or less thantoExpNeg, then exponential notation is returned.If
baseisnullor undefined it is ignored.See Errors for the treatment of other non-integer or out of range
basevalues.+x // '9876.54321'+ + + +toString
+.toString([base]) ⇒ string+
base: number: integer, 2 to 64 inclusive+ Returns a string representing the value of this Decimal in the specified base, or base 10 if +
+baseis omitted or isnullor undefined. ++ For bases above 10, values from 10 to 35 are represented by
+a-z(as with +Number.prototype.toString), 36 to 61 byA-Z, and 62 and 63 by +$and_respectively. ++ If a base is specified the value is rounded to
+precision+ significant digits using rounding moderounding. ++ If a base is not specified and this Decimal has a positive exponent that is equal to or + greater than
+toExpPos, or a negative exponent equal to + or less thantoExpNeg, then exponential notation is + returned. +If
+baseisnullor undefined it is ignored.+ See Errors for the treatment of other non-integer or out of range +
+basevalues. +x = new Decimal(750000) x.toString() // '750000' Decimal.config({ toExpPos: 5 }) @@ -403,16 +1968,86 @@ y.toString(32) // 'ba.s' Decimal.config({ precision: 4 }); z = new Decimal('1.23456789') z.toString() // '1.23456789' -z.toString(10) // '1.2346'truncated
.trunc() ⇒ DecimalReturns a new Decimal whose value is the value of this Decimal truncated to a whole number.
The return value is not rounded to
precision.+z.toString(10) // '1.2346'+ + + +truncated
+.trunc() ⇒ Decimal+ Returns a new Decimal whose value is the value of this Decimal truncated to a whole number. +
+The return value is not rounded to
+precision.x = new Decimal(123.456) x.truncated() // '123' y = new Decimal(-12.3) -y.trunc() // '-12'valueOf
.valueOf() ⇒ stringAs
toString, but does not accept a base argument.+y.trunc() // '-12'+ + + +valueOf
+.valueOf() ⇒ stringAs
+toString, but does not accept a base argument.x = new Decimal('1.777e+457') -x.valueOf() // '1.777e+457'Properties
A Decimal is an object with three properties:
Property Description Type Value c coefficient* number []Array of single digits e exponent number Integer, -9e15 to 9e15 inclusive s sign number -1 or 1 *significand
The value of any of the three properties may also be
null.The value of a Decimal is stored in a normalised decimal floating point format which corresponds to the value's
toExponentialform, 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.valueOf() // '1.777e+457'+ + + + + + +Properties
++ A Decimal is an object with three properties: +
++
++ +Property +Description +Type +Value ++ +c +coefficient* +number +[]Array of integers, each 0 - 1e7 ++ +e +exponent +number +Integer, -9e15 to 9e15 inclusive ++ +s +sign +number +-1 or 1 +*significand
++ The value of any of the three properties may also be
+null. ++ The properties are best considered to be read-only. +
++ From version 3 of this library, the value of a Decimal is stored in a normalised base +
+10000floating point format. While previously it was acceptable to change the + exponent of a Decimal by writing to its exponent property directly, this is no longer + recommended (as the number of digits in the first element of the coefficient array is + dependent on the exponent, so the coefficient would also need to be altered). ++ As with JavaScript numbers, the original exponent and fractional trailing zeros of a number + are not preserved. +
+x = new Decimal(0.123) // '0.123' x.toExponential() // '1.23e-1' -x.c // '1,2,3' +x.c // [ 1230000 ] x.e // -1 x.s // 1 @@ -420,39 +2055,312 @@ y = new Number(-123.4567000e+2) // '-12345.67' y.toExponential() // '-1.234567e+4' z = new Decimal('-123.4567000e+2') // '-12345.67' z.toExponential() // '-1.234567e+4' -z.c // '1,2,3,4,5,6,7' +z.c // [ 12345, 6700000 ] z.e // 4 -z.s // -1A Decimal 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 Decimal('1234.000') // '1234' -x.toExponential() // '1.234e+3' -x.c // '1,2,3,4' -x.e // 3 +z.s // -1-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,NaNand ±Infinityare stored.
c e s ±0 [0]0±1NaN nullnullnull±Infinity nullnull±1+ + +Zero, NaN and Infinity
++ The table below shows how ±
+0,NaNand + ±Infinityare stored. ++
++ ++ c +e +s ++ +±0 ++ [0]+ 0+ ±1+ +NaN ++ null+ null+ null+ +±Infinity ++ null+ null+ ±1x = new Number(-0) // 0 1 / x == -Infinity // true y = new Decimal(-0) // '0' y.c // '0' ( [0].toString() ) y.e // 0 -y.s // -1Errors
The errors that are thrown are generic
Errorobjects withnameDecimal Error.The table below shows the errors that may be thrown if
errorsistrue, and the action taken iferrorsisfalse.
Method(s) errors: true
Throw Decimal Errorerrors: false
Action on invalid argumentcomparedTo
Decimal
dividedBy
dividedToIntegerBy
equals
greaterThan
greaterThanOrEqualTo
lessThan
lessThanOrEqualTo
logarithm
minus
modulo
naturalLogarithm
plus
times
toPowernumber type has more than
15 significant digitsAccept. not a base... number Substitute NaNbase not an integer Truncate to integer.
Ignore if not a numberbase out of range Ignore not a number* Substitute NaNconfigprecisionnot an integerTruncate to integer.
Ignore if not a numberprecisionout of rangeIgnore roundingnot an integerTruncate to integer.
Ignore if not a numberroundingout of rangeIgnore toExpNegnot an integerTruncate to integer.
Ignore if not a numbertoExpNegout of rangeIgnore toExpPosnot an integerTruncate to integer.
Ignore if not a numbertoExpPosout of rangeIgnore minEnot an integerTruncate to integer.
Ignore if not a numberminEout of rangeIgnore maxEnot an integerTruncate to integer.
Ignore if not a numbermaxEout of rangeIgnore errorsnot a boolean or binary digitIgnore cryptonot a boolean or binary digitIgnore modulonot an integerTruncate to integer.
Ignore if not a numbermoduloout of rangeIgnore logarithm
naturalLogarithmLN10 out of digits Ignore precisionargument not a boolean or binary digit Ignore toDecimalPlaces
toExponential
toFixed
toPrecision
toSignificantDigitsargument not an integer Truncate to integer.
Ignore if not a numberargument out of range Ignore rounding mode not an integer Truncate to integer.
Ignore if not a numberrounding mode out of range Ignore toFractionnumber type has more than
15 significant digitsAccept. max denominator not an integer Truncate to integer.
Ignore if not a numbermax denominator out of range Ignore toNearestnumber type has more than
15 significant digitsAccept. rounding mode out of range Ignore toStringbase not an integer Truncate to integer.
Ignore if not a numberbase out of range Ignore *No error is thrown if the value is
NaNor 'NaN'.The message of a Decimal Error will also contain the name of the method from which the error originated.
To determine if an exception is a Decimal Error:
+y.s // -1+ + + +Errors
++ The errors that are thrown are generic
+Errorobjects withname+ Decimal Error. ++ The table below shows the errors that may be thrown if
+errorsis +true, and the action taken iferrorsisfalse. ++
++ +Method(s) +errors: true +
Throw Decimal Errorerrors: false +
Action on invalid argument+ ++ ++ comparedTo+
+ Decimal
+ dividedBy
+ dividedToIntegerBy
+ equals
+ greaterThan
+ greaterThanOrEqualTo
+ lessThan
+ lessThanOrEqualTo
+ logarithm
+ minus
+ modulo
+ naturalLogarithm
+ plus
+ times
+ toPower +number type has more than +
15 significant digitsAccept. ++ +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+ precisionnot an integerTruncate to integer. +
Ignore if not a number+ ++ precisionout of rangeIgnore ++ ++ roundingnot an integerTruncate to integer. +
Ignore if not a number+ ++ roundingout of rangeIgnore ++ ++ toExpNegnot an integerTruncate to integer. +
Ignore if not a number+ ++ toExpNegout of rangeIgnore ++ ++ toExpPosnot an integerTruncate to integer. +
Ignore if not a number+ ++ toExpPosout of rangeIgnore ++ ++ minEnot an integerTruncate to integer. +
Ignore if not a number+ ++ minEout of rangeIgnore ++ ++ maxEnot an integerTruncate to integer. +
Ignore if not a number+ ++ maxEout of rangeIgnore ++ ++ errorsnot a boolean or binary digitIgnore ++ ++ cryptonot a boolean or binary digitIgnore ++ ++ modulonot an integerTruncate to integer. +
Ignore if not a number+ ++ moduloout of rangeIgnore ++ ++ logarithm
naturalLogarithmLN10 out of digits +Ignore ++ ++ precisionargument not a boolean or binary digit +Ignore ++ ++ random+ cryptounavailableUse +Math.random+ ++ ++ toDecimalPlaces+
+ toExponential
+ toFixed
+ toPrecision
+ toSignificantDigits +argument not an integer +Truncate to integer. +
Ignore if not a number+ +argument out of range +Ignore ++ +rounding mode not an integer +Truncate to integer. +
Ignore if not a number+ +rounding mode out of range +Ignore ++ ++ toFractionnumber type has more than +
15 significant digitsAccept. ++ +max denominator not an integer +Truncate to integer. +
Ignore if not a number+ +max denominator out of range +Ignore ++ ++ toNearestnumber type has more than +
15 significant digitsAccept. ++ +rounding mode out of range +Ignore ++ ++ toStringbase not an integer +Truncate to integer. +
Ignore if not a number+ +base out of range +Ignore +*No error is thrown if the value is
+NaNor 'NaN'.+ The message of a Decimal Error will also contain the name of the method from which the + error originated. +
+To determine if an exception is a Decimal Error:
+try { // ... } catch (e) { if ( e instanceof Error && e.name == 'Decimal Error' ) { // ... } -}FAQ
Why are trailing fractional zeros removed from Decimals?
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.
+}+ +FAQ
+Why are trailing fractional zeros removed from Decimals?
++ 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.1400000To specify the precision of a value is to specify that the value lies within a certain range.
In the first example,
xhas a value of1.0. The trailing zero shows the precision of the value, implying that it is in the range0.95to1.05. Similarly, the precision indicated by the trailing zeros ofyindicates that the value is in the range1.09995to1.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 is2.04995to2.15005.The result given by BigDecimal of
2.1000however, indicates that the value is in the range2.09995to2.10005and therefore the precision implied by its trailing zeros may be misleading.In the second example, the true range is
4.122744to4.157256yet the BigDecimal answer of4.1400000indicates a range of4.13999995to4.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,toFixedandtoPrecisionmethods enable trailing zeros to be added if and when required.
+ 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.
+