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 quickstart -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]) ⇒ Decimal
-value0, ±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 inclusive
-value.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.
-
+ + + ++ +- - \ No newline at end of file +decimal.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' @@ -223,51 +242,60 @@ 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'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 }) ++ 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' new Decimal(1.23456789).round() // '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 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. -+ + + + + +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, @@ -280,16 +308,23 @@ Decimal.config({ crypto: false, modulo: 1 })--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 }) ++ 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) @@ -301,77 +336,95 @@ y.div(3) // 0.333333333 // D9 = Decimal.constructor({ precision: 9 }) is equivalent to: D9 = Decimal.constructor() D9.config({ precision: 9 })--
-constructoris a factory method so it is not necessary or desirable to use -newbut it will do no harm. -D = new Decimal.constructor()--It is not inefficient in terms of memory usage to use multiple Decimal constructors as -functions are shared between them. -
-exp
-.exp() ⇒ DecimalSee
-exponential.x = Decimal.exp(3) ++
+constructoris a factory method so it is not necessary or desirable to use +newbut it will do no harm. +D = new Decimal.constructor()++ It is not inefficient in terms of memory usage to use multiple Decimal constructors as + functions are shared between them. +
+ + + +exp
+.exp() ⇒ DecimalSee
+exponential.x = Decimal.exp(3) y = new Decimal(3).exp() x.equals(y) // true-ln
-.ln() ⇒ DecimalSee
-naturalLogarithm.x = Decimal.ln(4.321) + + + +ln
+.ln() ⇒ DecimalSee
+naturalLogarithm.x = Decimal.ln(4.321) y = new Decimal(4.321).ln() 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) + + + +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) // 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') + + + ++ 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') + + + ++ 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 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. -+ + + ++ 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> @@ -380,57 +433,62 @@ to a variable with a different name. Decimal // 1 y = new D(3) // '3' </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) + + + +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) // true--random
-.random([limit [, sd]]) ⇒ Decimal--
-limit: number|string|Decimal
Default value:1
-sd: number: integer, 1 to 1e+9 inclusive
-Default value:precision
-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 as -limit. --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 have -sdsignificant 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
-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. -// A value in the range [0, 1) with precision significant digits + + + ++ random
+.random([limit [, sd]]) ⇒ Decimal++
+limit: number|string|Decimal
Default value:1
+sd: 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 as +limit. ++ 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 have +sdsignificant 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
+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. +// A value in the range [0, 1) with precision significant digits Decimal.config({ precision: 10 }) Decimal.random() // '0.4117936847' @@ -446,11 +504,8 @@ Decimal.random(10) // '6' // An integer in the range (-100, 0] Decimal.random(-100) // '-82' -// An integer in the range [0, 99.99) -Decimal.random('99.99') // '47' - // An integer in the range [0, 9e9999999999) -Decimal.random('9e99999999999') // The browser will hang +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' @@ -460,450 +515,526 @@ 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) // 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 }) + + + + + +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 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 value to be returned to -
-precisionsignificant digits except -absoluteValue,ceil, -floor,negated, -round,toDecimalPlaces-andtoNearest. --A Decimal constructor will also not round to
-precisionunless a base is -specified. -Decimal.config({ precision: 5 }) + + + +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 value to be returned to +
+precisionsignificant digits except +absoluteValue,ceil, +floor,negated, +toDecimalPlacesand +toNearest. ++ 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 to -
-precisionand when rounding -round,toDecimalPlaces, -toExponential,toFixed, -toFormat, andtoPrecision. -The modes are available as enumerated properties of the constructor.
-Decimal.config({ rounding: Decimal.ROUND_UP }) + + + +rounding
++ number: integer,
+0to8inclusive
+ Default value:4(ROUND_HALF_UP) ++ The default rounding mode used when rounding to +
+precisionand when rounding +round,toDecimalPlaces, +toExponential,toFixed, +toFormat, andtoPrecision. ++ The rounding modes are available as enumerated properties of the + constructor. +
+Decimal.config({ rounding: Decimal.ROUND_UP }) Decimal.config({ rounding: 0 }) // equivalent 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 + + + +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 only -3 +new Decimal(0.001) // '0.01' e is -3 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 ++ 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 only 4 +new Decimal(99999) // '99999' e is 4 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 }) ++ 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 only -6 +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, 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 only 1 ++ 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, 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 }) ++ 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/modulomodes are available as enumerated properties of the Decimal -constructor. -Decimal.config({ modulo: Decimal.EUCLID }) + + + +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 // 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. --Decimal.crypto // false -Decimal.config({ crypto: true }) -// If crypto.getRandomValues and crypto.randomBytes are undefined -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 }) + + +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. ++Decimal.crypto // false +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 // 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.
-+ + + + + +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([sd]) ⇒ Decimal-
sd: number: integer, 1 to 1e+9 inclusive.-Returns a new Decimal whose value is the value of this Decimal rounded to
-sd-significant digits in the direction of positiveInfinity. --If
-sdis omitted or isnullor undefined, the return value is -the value of this Decimal rounded to a whole number. -The return value is not rounded to
-precision.+ + + +ceil
+.ceil([sd]) ⇒ Decimal+
sd: number: integer, 1 to 1e+9 inclusive.+ Returns a new Decimal whose value is the value of this Decimal rounded to
+sd+ significant digits in the direction of positiveInfinity. ++ If
+sdis omitted or isnullor undefined, the return value is + the value of this Decimal rounded to a whole number. +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|Decimal
-base: number
-SeeDecimalfor further parameter details. --
-- Returns - -1 -If the value of this Decimal is greater than the value of -n- --1 -If the value of this Decimal is less than the value of -n- -0 -If this Decimal and -nhave the same value- -null -If the value of either this Decimal or -nisNaN+ + + +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) // -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. -
-+ + + +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. -+ + + +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. -+ + + ++ 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.+ + + +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 @@ -912,344 +1043,401 @@ new Decimal(255).eq('ff', 16) // true y = new Decimal(NaN) 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. -+ + + +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([sd]) ⇒ Decimal-
sd: number: integer, 1 to 1e+9 inclusive.-Returns a new Decimal whose value is the value of this Decimal rounded to
-sd-significant digits in the direction of negativeInfinity. --If
-sdis omitted or isnullor undefined, the return value is -the value of this Decimal rounded to a whole number. -The return value is not rounded to
-precision.++ 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([sd]) ⇒ Decimal+
sd: number: integer, 1 to 1e+9 inclusive.+ Returns a new Decimal whose value is the value of this Decimal rounded to
+sd+ significant digits in the direction of negativeInfinity. ++ If
+sdis omitted or isnullor undefined, the return value is + the value of this Decimal rounded to a whole number. +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|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 + + + +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) // 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 + + + ++ 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) // 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. -+ + + +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() // 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. -++ 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() // false-isNaN
-.isNaN() ⇒ boolean-Returns
-trueif the value of this Decimal is NaN, otherwise returns -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() // 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. -+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 // 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. -+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() // 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.+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) // 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.+ + + ++ 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) // 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. -+ + + +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|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. -++ 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|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. 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's -remaindermethod. -See
-modulofor a description of the other modulo modes.+ + + +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. 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's +remaindermethod. +See
+modulofor a description of the other modulo modes.1 % 0.9 // 0.09999999999999998 x = new Decimal(1) x.modulo(0.9) // '0.1' y = new Decimal(33) y.mod('a', 33) // '3'-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. -+ + + +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 with value the natural logarithm of -10. This
-LN10variable in the source code currently has a precision of -1025digits, 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 over 1000 digits 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.
-++ 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|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. -+ + + +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. -+ + + +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([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. --This method differs completely from
-Math.round, which rounds to -an integer. SeetoInteger. -+ + + +round
+.round([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. ++ This method differs completely from
+Math.round, which rounds to + an integer. SeetoInteger. +Decimal.config({ precision: 5, rounding: 4 }) x = new Decimal(9876.54321) @@ -1259,67 +1447,76 @@ x.round(6, Decimal.ROUND_UP) // '9876.55' x.round(2) // '9900' x.round(2, 1) // '9800' x // '9876.54321'-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. -
--The square root is method is much faster than using the -
-toPowermethod with an exponent of0.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) ) // 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. -+ + + +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 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. -+ + + ++ 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' @@ -1327,81 +1524,88 @@ y = new Decimal(9876.54321) y.toDP(3) // '9876.543' y.toDP(1, 0) // '9876.6' y.toDP(1, 1) // '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. -+ + + ++ 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' -y.toExponential() // '4.56e+1' -x.toExponential(0) // '5e+1' -y.toExponential(0) // '5e+1' -x.toExponential(1) // '4.6e+1' -y.toExponential(1) // '4.6e+1' -y.toExponential(1, 1) // '4.5e+1' (ROUND_DOWN) -x.toExponential(3) // '4.560e+1' -y.toExponential(3) // '4.560e+1'-toFixed
-.toFixed([dp [, rm]]) ⇒ string-
-dp: number: integer, 0 to 1e+9 inclusive
-rm: number: integer, 0 to 8 inclusive --Returns a string representing the value of this 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 to 1021, this method will always return normal notation. --If
-dpis omitted or isnullor undefined, then the return value is -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.toExponential() // '4.56e+1' +y.toExponential() // '4.56e+1' +x.toExponential(0) // '5e+1' +y.toExponential(0) // '5e+1' +x.toExponential(1) // '4.6e+1' +y.toExponential(1) // '4.6e+1' +y.toExponential(1, 1) // '4.5e+1' (ROUND_DOWN) +x.toExponential(3) // '4.560e+1' +y.toExponential(3) // '4.560e+1'+ + + +toFixed
+.toFixed([dp [, rm]]) ⇒ string+
+dp: number: integer, 0 to 1e+9 inclusive
+rm: number: integer, 0 to 8 inclusive ++ Returns a string representing the value of this 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' @@ -1412,41 +1616,44 @@ 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 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.-
+ + + ++ 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' @@ -1454,28 +1661,31 @@ 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 < -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. -+ + + ++ 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' @@ -1486,18 +1696,21 @@ pi.toFraction(10000) // '355, 113' pi.toFraction(100) // '311, 99' pi.toFraction(10) // '22, 7' pi.toFraction(1) // '3, 1'-toInteger
-.toInt([rm]) ⇒ Decimal-
rm: number: integer, 0 to 8 inclusive.-Returns a new Decimal whose value is the value of this Decimal rounded to a whole number using -rounding mode
-rm, orrounding-ifrmis omitted or isnullor undefined. --See Errors for the treatment of other non-integer or out of range -
-rmvalues. -+ + + +toInteger
+.toInt([rm]) ⇒ Decimal+
rm: number: integer, 0 to 8 inclusive.+ Returns a new Decimal whose value is the value of this Decimal rounded to a whole number using + rounding mode
+rm, orrounding+ ifrmis omitted or isnullor undefined. ++ See Errors for the treatment of other non-integer or out of range +
+rmvalues. +Decimal.config({ rounding: 4 }) x = 1234.5 x.toInteger() // '1235' @@ -1508,9 +1721,12 @@ x.toInt() // '1234' x.toInteger(Decimal.ROUND_HALF_CEIL) // '1235' x.toInt(6) // '1234' x // '1234.56'-toJSON
-.toJSON() ⇒ stringAs
-valueOf.+ + + +toJSON
+.toJSON() ⇒ stringAs
+valueOf.x = new Decimal('177.7e+457') y = new Decimal(235.4325) z = new Decimal('0.0098074') @@ -1523,193 +1739,210 @@ str = JSON.stringify( [x, y, z] ) 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|Decimal
-rm: number: integer, 0 to 8 inclusive
-SeeDecimalfor further parameter details. --Returns a new Decimal whose value is the nearest multiple of the magnitude of
-n-to 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 4 (ROUND_HALF_UP) is the -same as rounding mode 0 (ROUND_UP), and so on. --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.+ + ++ 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. 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. -
-+ + + +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 +x.toNumber() // 456.789 ++x // 456.789 y = new Decimal('45987349857634085409857349856430985') -y.toNumber() // 4.598734985763409e+34 +y.toNumber() // 4.598734985763409e+34 z = new Decimal(-0) -1 / +z // Infinity -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, even when only quite a small number of significant -digits is required, the performance of this method may not be adequate. -
--Math.pow(0.7, 2) // 0.48999999999999994 +1 / +z // Infinity +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, even when only quite a small number of significant + digits is required, 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' +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 be 5 or -4 respectively). --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: -
-+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.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. -+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' -y.toPrecision() // '45.6' -x.toPrecision(1) // '5e+1' -y.toPrecision(1) // '5e+1' -y.toPrecision(2, 0) // '4.6e+1' (ROUND_UP) -y.toPrecision(2, 1) // '4.5e+1' (ROUND_DOWN) -x.toPrecision(5) // '45.600' -y.toPrecision(5) // '45.600'-toString
-.toString([base]) ⇒ string-
base: number: integer, 2 to 64 inclusive-Returns a string representing the value of this Decimal in the specified base, or base 10 if -
-baseis omitted. --For bases above 10, values from 10 to 35 are represented by
-a-z(as with -Number.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.toPrecision() // '45.6' +y.toPrecision() // '45.6' +x.toPrecision(1) // '5e+1' +y.toPrecision(1) // '5e+1' +y.toPrecision(2, 0) // '4.6e+1' (ROUND_UP) +y.toPrecision(2, 1) // '4.5e+1' (ROUND_DOWN) +x.toPrecision(5) // '45.600' +y.toPrecision(5) // '45.600'+ + + +toString
+.toString([base]) ⇒ string+
base: number: integer, 2 to 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 }) @@ -1724,71 +1957,83 @@ Decimal.config({ precision: 4 }); z = new Decimal('1.23456789') z.toString() // '1.23456789' z.toString(10) // '1.2346'-truncated
-.trunc([sd]) ⇒ Decimal-Returns a new Decimal whose value is the value of this Decimal truncated to to
-sd-significant digits. --If
-sdis omitted or isnullor undefined, the return value is -the value of this Decimal truncated to a whole number. -The return value is not rounded to
-precision.+ + + +truncated
+.trunc([sd]) ⇒ Decimal+ Returns a new Decimal whose value is the value of this Decimal truncated to to
+sd+ significant digits. ++ If
+sdis omitted or isnullor undefined, the return 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.+ + + +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. -
-+ + + + + + +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 = new Decimal(0.123) // '0.123' x.toExponential() // '1.23e-1' x.c // '1,2,3' @@ -1802,12 +2047,14 @@ z.toExponential() // '-1.234567e+4' z.c // '1,2,3,4,5,6,7' z.e // 4 z.s // -1--A 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: -+ + ++ A 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' @@ -1815,268 +2062,274 @@ 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,NaNand -±Infinityare 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 +-+ If changing the coefficient array directly, which is not recommended, be + careful to avoid leading or trailing zeros (unless zero itself is being + represented). +
-y = new Decimal(-0) // '0' -y.c // '0' ( [0].toString() ) -y.e // 0 -y.s // -1Errors
--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- -- --ceil-
-floor
-truncated -argument not an integer -Truncate to integer. -
Ignore if not a number- -argument out of range -Ignore -- -- --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- -- configobject expected -Ignore -- -- 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 digitIgnore -- -- --round-
-toDecimalPlaces
-toExponential
-toFixed
-toPrecision -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 -- -- toIntegerrounding mode 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:
-+ + +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+ ±1+x = new Number(-0) // 0 +1 / x == -Infinity // true + +y = new Decimal(-0) // '0' +y.c // '0' ( [0].toString() ) +y.e // 0 +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+ ++ ++ ceil+
+ floor
+ truncated +argument not an integer +Truncate to integer. +
Ignore if not a number+ +argument out of range +Ignore ++ ++ ++ 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+ ++ configobject expected +Ignore ++ ++ 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 digitIgnore ++ ++ ++ round+
+ toDecimalPlaces
+ toExponential
+ toFixed
+ toPrecision +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 ++ ++ toIntegerrounding mode 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) { @@ -2084,14 +2337,15 @@ try { // ... } }-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 @@ -2099,41 +2353,41 @@ 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,
-xhas a value of1.0. The trailing zero shows -the precision of the value, implying that it is in the range0.95to -1.05. Similarly, the precision indicated by the trailing zeros ofy-indicates 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 is -2.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.13999995-to4.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,toFixedand -toPrecisionmethods enable trailing zeros to be added if and when required.
-