v10.4.3

Remove toStringTag declaration for type compatibility

.travis.yml

@@ -1,6 +1,10 @@
 language: node_js
 node_js:
   - "node"
+  - "18"
+  - "17"
+  - "16"
+  - "15"
   - "14"
   - "13"
   - "12"

CHANGELOG.md

@@ -1,3 +1,39 @@
+#### 10.4.3
+* 04/12/2022
+* #211 Remove `toStringTag` declaration for type compatibility.
+
+#### 10.4.2
+* 12/10/2022
+* #209 Correct return type.
+
+#### 10.4.1
+* 16/09/2022
+* #205 Add './decimal' subpath to *package.json* `exports`.
+
+#### 10.4.0
+* 14/08/2022
+* #201 Add `exports` field to *package.json*.
+* #203 Preserve license comment after bundling.
+* #198 Use type predicate on `isDecimal`.
+
+#### 10.3.1
+* 25/06/2021
+* Remove minified versions. Refresh *README*.
+
+#### 10.3.0
+* 22/06/2021
+* Support underscores as separators.
+* #101 Add `Decimal.clamp` method.
+* #161 Fix Decimal instances deemed plain objects.
+* #100 Add `Decimal.sum` method.
+* #146 `Symbol.for` to `Symbol['for']` for IE8.
+* #132 Fix possible infinite loop when `minE` is very low.
+* #180 Accept Decimals of different origin.
+* Update Typescript definitions.
+* Update minification examples in *README*.
+* Add minified versions for both *decimal.js* and *decimal.mjs*.
+* Add *files* field to *package.json*, and remove build script.
+
 #### 10.2.1
 * 28/09/2020
 * Correct `sqrt` initial estimate.

LICENCE.md

@@ -1,6 +1,6 @@
 The MIT Licence.
 
-Copyright (c) 2020 Michael Mclaughlin
+Copyright (c) 2022 Michael Mclaughlin
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

README.md

@@ -18,7 +18,8 @@ An arbitrary-precision Decimal type for JavaScript.
   - Faster, smaller, and perhaps easier to use than JavaScript versions of Java's BigDecimal
   - No dependencies
   - Wide platform compatibility: uses JavaScript 1.5 (ECMAScript 3) features only
-  - Comprehensive [documentation](http://mikemcl.github.io/decimal.js/) and test set
+  - Comprehensive [documentation](https://mikemcl.github.io/decimal.js/) and test set
+  - Used under the hood by [math.js](https://github.com/josdejong/mathjs)
   - Includes a TypeScript declaration file: *decimal.d.ts*
 
 ![API](https://raw.githubusercontent.com/MikeMcl/decimal.js/gh-pages/API.png)
@@ -32,7 +33,8 @@ This library also adds the trigonometric functions, among others, and supports n
 which makes it a significantly larger library than *bignumber.js* and the even smaller
 [big.js](https://github.com/MikeMcl/big.js/).
 
-For a lighter version of this library without the trigonometric functions see [decimal.js-light](https://github.com/MikeMcl/decimal.js-light/).
+For a lighter version of this library without the trigonometric functions see
+[decimal.js-light](https://github.com/MikeMcl/decimal.js-light/).
 
 ## Load
 
@@ -42,48 +44,32 @@ Browser:
 
 ```html
 <script src='path/to/decimal.js'></script>
-```
 
-```html
 <script type="module">
-import Decimal from './path/to/decimal.mjs';
-...
+  import Decimal from './path/to/decimal.mjs';
+  ...
 </script>
 ```
 
-[Node.js](http://nodejs.org):
+[Node.js](https://nodejs.org):
 
 ```bash
-$ npm install decimal.js
+npm install decimal.js
 ```
-
 ```js
-var Decimal = require('decimal.js');
-```
+const Decimal = require('decimal.js');
 
-ES module:
+import Decimal from 'decimal.js';
 
-```js
-//import Decimal from 'decimal.js';
 import {Decimal} from 'decimal.js';
 ```
 
-AMD loader libraries such as [requireJS](http://requirejs.org/):
-
-```js
-require(['decimal'], function(Decimal) {
-    // Use Decimal here in local scope. No global Decimal.
-});
-```
-
 ## Use
 
-*In all examples below, `var`, semicolons and `toString` calls are not shown.
+*In all examples below, semicolons and `toString` calls are not shown.
 If a commented-out value is in quotes it means `toString` has been called on the preceding expression.*
 
-The library exports a single function object, `Decimal`, the constructor of Decimal instances.
-
-It accepts a value of type number, string or Decimal.
+The library exports a single constructor function, `Decimal`, which expects a single argument that is a number, string or Decimal instance.
 
 ```js
 x = new Decimal(123.4567)
@@ -92,7 +78,29 @@ z = new Decimal(x)
 x.equals(y) && y.equals(z) && x.equals(z)        // true
 ```
 
-A value can also be in binary, hexadecimal or octal if the appropriate prefix is included.
+If using values with more than a few digits, it is recommended to pass strings rather than numbers to avoid a potential loss of precision.
+
+```js
+// Precision loss from using numeric literals with more than 15 significant digits.
+new Decimal(1.0000000000000001)         // '1'
+new Decimal(88259496234518.57)          // '88259496234518.56'
+new Decimal(99999999999999999999)       // '100000000000000000000'
+
+// Precision loss from using numeric literals outside the range of Number values.
+new Decimal(2e+308)                     // 'Infinity'
+new Decimal(1e-324)                     // '0'
+
+// Precision loss from the unexpected result of arithmetic with Number values.
+new Decimal(0.7 + 0.1)                  // '0.7999999999999999'
+```
+
+As with JavaScript numbers, strings can contain underscores as separators to improve readability.
+
+```js
+x = new Decimal('2_147_483_647')
+```
+
+String values in binary, hexadecimal or octal notation are also accepted if the appropriate prefix is included.
 
 ```js
 x = new Decimal('0xff.f')            // '255.9375'
@@ -101,15 +109,13 @@ z = x.plus(y)                        // '427.9375'
 
 z.toBinary()                         // '0b110101011.1111'
 z.toBinary(13)                       // '0b1.101010111111p+8'
-```
 
-Using binary exponential notation to create a Decimal with the value of `Number.MAX_VALUE`:
-
-```js
+// Using binary exponential notation to create a Decimal with the value of `Number.MAX_VALUE`.
 x = new Decimal('0b1.1111111111111111111111111111111111111111111111111111p+1023')
+// '1.7976931348623157081e+308'
 ```
 
-A Decimal is immutable in the sense that it is not changed by its methods.
+Decimal instances are immutable in the sense that they are not changed by their methods.
 
 ```js
 0.3 - 0.1                     // 0.19999999999999998
@@ -128,27 +134,28 @@ x.times('1.23456780123456789e+9').plus(9876.5432321).dividedBy('4444562598.11177
 Many method names have a shorter alias.
 
 ```js
-x.squareRoot().dividedBy(y).toPower(3).equals(x.sqrt().div(y).pow(3))         // true
-x.cmp(y.mod(z).neg()) == 1 && x.comparedTo(y.modulo(z).negated()) == 1        // true
+x.squareRoot().dividedBy(y).toPower(3).equals(x.sqrt().div(y).pow(3))     // true
+x.comparedTo(y.modulo(z).negated() === x.cmp(y.mod(z).neg())              // true
 ```
 
-Like JavaScript's Number type, there are `toExponential`, `toFixed` and `toPrecision` methods,
+Most of the methods of JavaScript's `Number.prototype` and `Math` objects are replicated.
 
 ```js
 x = new Decimal(255.5)
-x.toExponential(5)              // '2.55500e+2'
-x.toFixed(5)                    // '255.50000'
-x.toPrecision(5)                // '255.50'
-```
+x.toExponential(5)                       // '2.55500e+2'
+x.toFixed(5)                             // '255.50000'
+x.toPrecision(5)                         // '255.50'
 
-and almost all of the methods of JavaScript's Math object are also replicated.
-
-```js
 Decimal.sqrt('6.98372465832e+9823')      // '8.3568682281821340204e+4911'
 Decimal.pow(2, 0.0979843)                // '1.0702770511687781839'
+
+// Using `toFixed()` to avoid exponential notation:
+x = new Decimal('0.0000001')
+x.toString()                             // '1e-7'
+x.toFixed()                              // '0.0000001'
 ```
 
-There are `isNaN` and `isFinite` methods, as `NaN` and `Infinity` are valid `Decimal` values,
+And there are `isNaN` and `isFinite` methods, as `NaN` and `Infinity` are valid `Decimal` values.
 
 ```js
 x = new Decimal(NaN)                                           // 'NaN'
@@ -156,7 +163,7 @@ y = new Decimal(Infinity)                                      // 'Infinity'
 x.isNaN() && !y.isNaN() && !x.isFinite() && !y.isFinite()      // true
 ```
 
-and a `toFraction` method with an optional *maximum denominator* argument
+There is also a `toFraction` method with an optional *maximum denominator* argument.
 
 ```js
 z = new Decimal(355)
@@ -165,27 +172,27 @@ pi.toFraction()              // [ '7853982301', '2500000000' ]
 pi.toFraction(1000)          // [ '355', '113' ]
 ```
 
-All calculations are rounded according to the number of significant digits and rounding mode
-specified by the `precision` and `rounding` properties of the Decimal constructor.
+All calculations are rounded according to the number of significant digits and rounding mode specified
+by the `precision` and `rounding` properties of the Decimal constructor.
 
-For advanced usage, multiple Decimal constructors can be created, each with their own independent configuration which
-applies to all Decimal numbers created from it.
+For advanced usage, multiple Decimal constructors can be created, each with their own independent
+configuration which applies to all Decimal numbers created from it.
 
 ```js
 // Set the precision and rounding of the default Decimal constructor
 Decimal.set({ precision: 5, rounding: 4 })
 
 // Create another Decimal constructor, optionally passing in a configuration object
-Decimal9 = Decimal.clone({ precision: 9, rounding: 1 })
+Dec = Decimal.clone({ precision: 9, rounding: 1 })
 
 x = new Decimal(5)
-y = new Decimal9(5)
+y = new Dec(5)
 
 x.div(3)                           // '1.6667'
 y.div(3)                           // '1.66666666'
 ```
 
-The value of a Decimal is stored in a floating point format in terms of its digits, exponent and sign.
+The value of a Decimal is stored in a floating point format in terms of its digits, exponent and sign, but these properties should be considered read-only.
 
 ```js
 x = new Decimal(-12345.67);
@@ -198,47 +205,42 @@ For further information see the [API](http://mikemcl.github.io/decimal.js/) refe
 
 ## Test
 
-The library can be tested using Node.js or a browser.
-
-The *test* directory contains the file *test.js* which runs all the tests when executed by Node,
-and the file *test.html* which runs all the tests when opened in a browser.
-
-To run all the tests, from a command-line at the root directory using npm
+To run the tests using Node.js from the root directory:
 
 ```bash
-$ npm test
+npm test
 ```
 
-or at the *test* directory using Node
+Each separate test module can also be executed individually, for example:
 
 ```bash
-$ node test
+node test/modules/toFraction
 ```
 
-Each separate test module can also be executed individually, for example, at the *test/modules* directory
+To run the tests in a browser, open *test/test.html*.
 
-```bash
-$ node toFraction
-```
+## Minify
 
-## Build
+Two minification examples:
 
-For Node, if [uglify-js](https://github.com/mishoo/UglifyJS2) is installed
+Using [uglify-js](https://github.com/mishoo/UglifyJS) to minify the *decimal.js* file:
 
 ```bash
 npm install uglify-js -g
+uglifyjs decimal.js --source-map url=decimal.min.js.map -c -m -o decimal.min.js
 ```
 
-then
+Using [terser](https://github.com/terser/terser) to minify the ES module version, *decimal.mjs*:
 
 ```bash
-npm run build
+npm install terser -g
+terser decimal.mjs --source-map url=decimal.min.mjs.map -c -m --toplevel -o decimal.min.mjs
 ```
 
-will create *decimal.min.js*, and a source map will also be added to the *doc* directory.
+```js
+import Decimal from './decimal.min.mjs';
+```
 
 ## Licence
 
-MIT.
-
-See *LICENCE.md*
+[The MIT Licence (Expat).](LICENCE.md)

decimal.d.ts

@@ -56,7 +56,6 @@ export declare class Decimal {
   readonly d: number[];
   readonly e: number;
   readonly s: number;
-  private readonly name: string;
 
   constructor(n: Decimal.Value);
 
@@ -64,6 +63,9 @@ export declare class Decimal {
   abs(): Decimal;
 
   ceil(): Decimal;
+  
+  clampedTo(min: Decimal.Value, max: Decimal.Value): Decimal;
+  clamp(min: Decimal.Value, max: Decimal.Value): Decimal;
 
   comparedTo(n: Decimal.Value): number;
   cmp(n: Decimal.Value): number;
@@ -239,6 +241,7 @@ export declare class Decimal {
   static atan2(y: Decimal.Value, x: Decimal.Value): Decimal;
   static cbrt(n: Decimal.Value): Decimal;
   static ceil(n: Decimal.Value): Decimal;
+  static clamp(n: Decimal.Value, min: Decimal.Value, max: Decimal.Value): Decimal;
   static clone(object?: Decimal.Config): Decimal.Constructor;
   static config(object: Decimal.Config): Decimal.Constructor;
   static cos(n: Decimal.Value): Decimal;
@@ -247,7 +250,7 @@ export declare class Decimal {
   static exp(n: Decimal.Value): Decimal;
   static floor(n: Decimal.Value): Decimal;
   static hypot(...n: Decimal.Value[]): Decimal;
-  static isDecimal(object: any): boolean
+  static isDecimal(object: any): object is Decimal;
   static ln(n: Decimal.Value): Decimal;
   static log(n: Decimal.Value, base?: Decimal.Value): Decimal;
   static log2(n: Decimal.Value): Decimal;
@@ -261,11 +264,12 @@ export declare class Decimal {
   static random(significantDigits?: number): Decimal;
   static round(n: Decimal.Value): Decimal;
   static set(object: Decimal.Config): Decimal.Constructor;
-  static sign(n: Decimal.Value): Decimal;
+  static sign(n: Decimal.Value): number;
   static sin(n: Decimal.Value): Decimal;
   static sinh(n: Decimal.Value): Decimal;
   static sqrt(n: Decimal.Value): Decimal;
   static sub(x: Decimal.Value, y: Decimal.Value): Decimal;
+  static sum(...n: Decimal.Value[]): Decimal;
   static tan(n: Decimal.Value): Decimal;
   static tanh(n: Decimal.Value): Decimal;
   static trunc(n: Decimal.Value): Decimal;

decimal.global.d.ts

@@ -77,7 +77,6 @@ export declare class Decimal {
   readonly d: number[];
   readonly e: number;
   readonly s: number;
-  private readonly name: string;
 
   constructor(n: DecimalValue);
 
@@ -85,6 +84,9 @@ export declare class Decimal {
   abs(): Decimal;
 
   ceil(): Decimal;
+  
+  clampedTo(min: Decimal.Value, max: Decimal.Value): Decimal;
+  clamp(min: Decimal.Value, max: Decimal.Value): Decimal;
 
   comparedTo(n: DecimalValue): number;
   cmp(n: DecimalValue): number;
@@ -260,6 +262,7 @@ export declare class Decimal {
   static atan2(y: DecimalValue, x: DecimalValue): Decimal;
   static cbrt(n: DecimalValue): Decimal;
   static ceil(n: DecimalValue): Decimal;
+  static clamp(n: Decimal.Value, min: Decimal.Value, max: Decimal.Value): Decimal;
   static clone(object?: DecimalConfig): DecimalConstructor;
   static config(object: DecimalConfig): DecimalConstructor;
   static cos(n: DecimalValue): Decimal;
@@ -268,7 +271,7 @@ export declare class Decimal {
   static exp(n: DecimalValue): Decimal;
   static floor(n: DecimalValue): Decimal;
   static hypot(...n: DecimalValue[]): Decimal;
-  static isDecimal(object: any): boolean
+  static isDecimal(object: any): object is Decimal;
   static ln(n: DecimalValue): Decimal;
   static log(n: DecimalValue, base?: DecimalValue): Decimal;
   static log2(n: DecimalValue): Decimal;
@@ -282,11 +285,12 @@ export declare class Decimal {
   static random(significantDigits?: number): Decimal;
   static round(n: DecimalValue): Decimal;
   static set(object: DecimalConfig): DecimalConstructor;
-  static sign(n: DecimalValue): Decimal;
+  static sign(n: DecimalValue): number;
   static sin(n: DecimalValue): Decimal;
   static sinh(n: DecimalValue): Decimal;
   static sqrt(n: DecimalValue): Decimal;
   static sub(x: DecimalValue, y: DecimalValue): Decimal;
+  static sum(...n: Decimal.Value[]): Decimal;
   static tan(n: DecimalValue): Decimal;
   static tanh(n: DecimalValue): Decimal;
   static trunc(n: DecimalValue): Decimal;

decimal.js

@@ -2,11 +2,11 @@
   'use strict';
 
 
-  /*
-   *  decimal.js v10.2.1
+  /*!
+   *  decimal.js v10.4.3
    *  An arbitrary-precision Decimal type for JavaScript.
    *  https://github.com/MikeMcl/decimal.js
-   *  Copyright (c) 2020 Michael Mclaughlin <M8ch88l@gmail.com>
+   *  Copyright (c) 2022 Michael Mclaughlin <M8ch88l@gmail.com>
    *  MIT Licence
    */
 
@@ -105,6 +105,7 @@
     invalidArgument = decimalError + 'Invalid argument: ',
     precisionLimitExceeded = decimalError + 'Precision limit exceeded',
     cryptoUnavailable = decimalError + 'crypto unavailable',
+    tag = '[object Decimal]',
 
     mathfloor = Math.floor,
     mathpow = Math.pow,
@@ -122,7 +123,7 @@
     PI_PRECISION = PI.length - 1,
 
     // Decimal.prototype object
-    P = { name: '[object Decimal]' };
+    P = { toStringTag: tag };
 
 
   // Decimal prototype methods
@@ -131,6 +132,7 @@
   /*
    *  absoluteValue             abs
    *  ceil
+   *  clampedTo                 clamp
    *  comparedTo                cmp
    *  cosine                    cos
    *  cubeRoot                  cbrt
@@ -212,6 +214,27 @@
   };
 
 
+  /*
+   * Return a new Decimal whose value is the value of this Decimal clamped to the range
+   * delineated by `min` and `max`.
+   *
+   * min {number|string|Decimal}
+   * max {number|string|Decimal}
+   *
+   */
+  P.clampedTo = P.clamp = function (min, max) {
+    var k,
+      x = this,
+      Ctor = x.constructor;
+    min = new Ctor(min);
+    max = new Ctor(max);
+    if (!min.s || !max.s) return new Ctor(NaN);
+    if (min.gt(max)) throw Error(invalidArgument + max);
+    k = x.cmp(min);
+    return k < 0 ? min : x.cmp(max) > 0 ? max : new Ctor(x);
+  };
+
+
   /*
    * Return
    *   1    if the value of this Decimal is greater than the value of `y`,
@@ -2445,18 +2468,6 @@
   };
 
 
-  /*
-  // Add aliases to match BigDecimal method names.
-  // P.add = P.plus;
-  P.subtract = P.minus;
-  P.multiply = P.times;
-  P.divide = P.div;
-  P.remainder = P.mod;
-  P.compareTo = P.cmp;
-  P.negate = P.neg;
-   */
-
-
   // Helper functions for Decimal.prototype (P) and/or Decimal methods, and their callers.
 
 
@@ -2628,13 +2639,15 @@
    *
    */
   function cosine(Ctor, x) {
-    var k, y,
-      len = x.d.length;
+    var k, len, y;
+
+    if (x.isZero()) return x;
 
     // Argument reduction: cos(4x) = 8*(cos^4(x) - cos^2(x)) + 1
     // i.e. cos(x) = 8*(cos^4(x/4) - cos^2(x/4)) + 1
 
     // Estimate the optimum number of times to use the argument reduction.
+    len = x.d.length;
     if (len < 32) {
       k = Math.ceil(len / 3);
       y = (1 / tinyPow(4, k)).toString();
@@ -3586,7 +3599,10 @@
   function parseOther(x, str) {
     var base, Ctor, divisor, i, isFloat, len, p, xd, xe;
 
-    if (str === 'Infinity' || str === 'NaN') {
+    if (str.indexOf('_') > -1) {
+      str = str.replace(/(\d)_(?=\d)/g, '$1');
+      if (isDecimal.test(str)) return parseDecimal(x, str);
+    } else if (str === 'Infinity' || str === 'NaN') {
       if (!+str) x.s = NaN;
       x.e = NaN;
       x.d = null;
@@ -3664,7 +3680,9 @@
     var k,
       len = x.d.length;
 
-    if (len < 3) return taylorSeries(Ctor, 2, x, x);
+    if (len < 3) {
+      return x.isZero() ? x : taylorSeries(Ctor, 2, x, x);
+    }
 
     // Argument reduction: sin(5x) = 16*sin^5(x) - 20*sin^3(x) + 5*sin(x)
     // i.e. sin(x) = 16*sin^5(x/5) - 20*sin^3(x/5) + 5*sin(x/5)
@@ -3930,6 +3948,7 @@
    *  atan2
    *  cbrt
    *  ceil
+   *  clamp
    *  clone
    *  config
    *  cos
@@ -3955,6 +3974,7 @@
    *  sinh
    *  sqrt
    *  sub
+   *  sum
    *  tan
    *  tanh
    *  trunc
@@ -4148,6 +4168,19 @@
   }
 
 
+  /*
+   * Return a new Decimal whose value is `x` clamped to the range delineated by `min` and `max`.
+   *
+   * x {number|string|Decimal}
+   * min {number|string|Decimal}
+   * max {number|string|Decimal}
+   *
+   */
+  function clamp(x, min, max) {
+    return new this(x).clamp(min, max);
+  }
+
+
   /*
    * Configure global settings for a Decimal constructor.
    *
@@ -4261,7 +4294,7 @@
       x.constructor = Decimal;
 
       // Duplicate.
-      if (v instanceof Decimal) {
+      if (isDecimalInstance(v)) {
         x.s = v.s;
 
         if (external) {
@@ -4381,6 +4414,7 @@
     Decimal.atan2 = atan2;
     Decimal.cbrt = cbrt;          // ES6
     Decimal.ceil = ceil;
+    Decimal.clamp = clamp;
     Decimal.cos = cos;
     Decimal.cosh = cosh;          // ES6
     Decimal.div = div;
@@ -4403,6 +4437,7 @@
     Decimal.sinh = sinh;          // ES6
     Decimal.sqrt = sqrt;
     Decimal.sub = sub;
+    Decimal.sum = sum;
     Decimal.tan = tan;
     Decimal.tanh = tanh;          // ES6
     Decimal.trunc = trunc;        // ES6
@@ -4497,7 +4532,7 @@
    *
    */
   function isDecimalInstance(obj) {
-    return obj instanceof Decimal || obj && obj.name === '[object Decimal]' || false;
+    return obj instanceof Decimal || obj && obj.toStringTag === tag || false;
   }
 
 
@@ -4797,6 +4832,28 @@
   }
 
 
+  /*
+   * Return a new Decimal whose value is the sum of the arguments, rounded to `precision`
+   * significant digits using rounding mode `rounding`.
+   *
+   * Only the result is rounded, not the intermediate calculations.
+   *
+   * arguments {number|string|Decimal}
+   *
+   */
+  function sum() {
+    var i = 0,
+      args = arguments,
+      x = new this(args[i]);
+
+    external = false;
+    for (; x.s && ++i < args.length;) x = x.plus(args[i]);
+    external = true;
+
+    return finalise(x, this.precision, this.rounding);
+  }
+
+
   /*
    * Return a new Decimal whose value is the tangent of `x`, rounded to `precision` significant
    * digits using rounding mode `rounding`.
@@ -4834,7 +4891,7 @@
 
   // Create and configure initial Decimal constructor.
   Decimal = clone(DEFAULTS);
-
+  Decimal.prototype.constructor = Decimal;
   Decimal['default'] = Decimal.Decimal = Decimal;
 
   // Create the internal constants from their string values.
@@ -4854,7 +4911,7 @@
   // Node and other environments that support module.exports.
   } else if (typeof module != 'undefined' && module.exports) {
     if (typeof Symbol == 'function' && typeof Symbol.iterator == 'symbol') {
-      P[Symbol.for('nodejs.util.inspect.custom')] = P.toString;
+      P[Symbol['for']('nodejs.util.inspect.custom')] = P.toString;
       P[Symbol.toStringTag] = 'Decimal';
     }
 

decimal.mjs

@@ -1,8 +1,8 @@
-/*
- *  decimal.js v10.2.1
+/*!
+ *  decimal.js v10.4.3
  *  An arbitrary-precision Decimal type for JavaScript.
  *  https://github.com/MikeMcl/decimal.js
- *  Copyright (c) 2020 Michael Mclaughlin <M8ch88l@gmail.com>
+ *  Copyright (c) 2022 Michael Mclaughlin <M8ch88l@gmail.com>
  *  MIT Licence
  */
 
@@ -101,6 +101,7 @@ var EXP_LIMIT = 9e15,                      // 0 to 9e15
   invalidArgument = decimalError + 'Invalid argument: ',
   precisionLimitExceeded = decimalError + 'Precision limit exceeded',
   cryptoUnavailable = decimalError + 'crypto unavailable',
+  tag = '[object Decimal]',
 
   mathfloor = Math.floor,
   mathpow = Math.pow,
@@ -118,7 +119,7 @@ var EXP_LIMIT = 9e15,                      // 0 to 9e15
   PI_PRECISION = PI.length - 1,
 
   // Decimal.prototype object
-  P = { name: '[object Decimal]' };
+  P = { toStringTag: tag };
 
 
 // Decimal prototype methods
@@ -127,6 +128,7 @@ var EXP_LIMIT = 9e15,                      // 0 to 9e15
 /*
  *  absoluteValue             abs
  *  ceil
+ *  clampedTo                 clamp
  *  comparedTo                cmp
  *  cosine                    cos
  *  cubeRoot                  cbrt
@@ -208,6 +210,27 @@ P.ceil = function () {
 };
 
 
+/*
+ * Return a new Decimal whose value is the value of this Decimal clamped to the range
+ * delineated by `min` and `max`.
+ *
+ * min {number|string|Decimal}
+ * max {number|string|Decimal}
+ *
+ */
+P.clampedTo = P.clamp = function (min, max) {
+  var k,
+    x = this,
+    Ctor = x.constructor;
+  min = new Ctor(min);
+  max = new Ctor(max);
+  if (!min.s || !max.s) return new Ctor(NaN);
+  if (min.gt(max)) throw Error(invalidArgument + max);
+  k = x.cmp(min);
+  return k < 0 ? min : x.cmp(max) > 0 ? max : new Ctor(x);
+};
+
+
 /*
  * Return
  *   1    if the value of this Decimal is greater than the value of `y`,
@@ -2441,18 +2464,6 @@ P.valueOf = P.toJSON = function () {
 };
 
 
-/*
-// Add aliases to match BigDecimal method names.
-// P.add = P.plus;
-P.subtract = P.minus;
-P.multiply = P.times;
-P.divide = P.div;
-P.remainder = P.mod;
-P.compareTo = P.cmp;
-P.negate = P.neg;
- */
-
-
 // Helper functions for Decimal.prototype (P) and/or Decimal methods, and their callers.
 
 
@@ -2624,13 +2635,15 @@ function convertBase(str, baseIn, baseOut) {
  *
  */
 function cosine(Ctor, x) {
-  var k, y,
-    len = x.d.length;
+  var k, len, y;
+
+  if (x.isZero()) return x;
 
   // Argument reduction: cos(4x) = 8*(cos^4(x) - cos^2(x)) + 1
   // i.e. cos(x) = 8*(cos^4(x/4) - cos^2(x/4)) + 1
 
   // Estimate the optimum number of times to use the argument reduction.
+  len = x.d.length;
   if (len < 32) {
     k = Math.ceil(len / 3);
     y = (1 / tinyPow(4, k)).toString();
@@ -3582,7 +3595,10 @@ function parseDecimal(x, str) {
 function parseOther(x, str) {
   var base, Ctor, divisor, i, isFloat, len, p, xd, xe;
 
-  if (str === 'Infinity' || str === 'NaN') {
+  if (str.indexOf('_') > -1) {
+    str = str.replace(/(\d)_(?=\d)/g, '$1');
+    if (isDecimal.test(str)) return parseDecimal(x, str);
+  } else if (str === 'Infinity' || str === 'NaN') {
     if (!+str) x.s = NaN;
     x.e = NaN;
     x.d = null;
@@ -3660,7 +3676,9 @@ function sine(Ctor, x) {
   var k,
     len = x.d.length;
 
-  if (len < 3) return taylorSeries(Ctor, 2, x, x);
+  if (len < 3) {
+    return x.isZero() ? x : taylorSeries(Ctor, 2, x, x);
+  }
 
   // Argument reduction: sin(5x) = 16*sin^5(x) - 20*sin^3(x) + 5*sin(x)
   // i.e. sin(x) = 16*sin^5(x/5) - 20*sin^3(x/5) + 5*sin(x/5)
@@ -3926,6 +3944,7 @@ function truncate(arr, len) {
  *  atan2
  *  cbrt
  *  ceil
+ *  clamp
  *  clone
  *  config
  *  cos
@@ -3951,6 +3970,7 @@ function truncate(arr, len) {
  *  sinh
  *  sqrt
  *  sub
+ *  sum
  *  tan
  *  tanh
  *  trunc
@@ -4144,6 +4164,19 @@ function ceil(x) {
 }
 
 
+/*
+ * Return a new Decimal whose value is `x` clamped to the range delineated by `min` and `max`.
+ *
+ * x {number|string|Decimal}
+ * min {number|string|Decimal}
+ * max {number|string|Decimal}
+ *
+ */
+function clamp(x, min, max) {
+  return new this(x).clamp(min, max);
+}
+
+
 /*
  * Configure global settings for a Decimal constructor.
  *
@@ -4257,7 +4290,7 @@ function clone(obj) {
     x.constructor = Decimal;
 
     // Duplicate.
-    if (v instanceof Decimal) {
+    if (isDecimalInstance(v)) {
       x.s = v.s;
 
       if (external) {
@@ -4377,6 +4410,7 @@ function clone(obj) {
   Decimal.atan2 = atan2;
   Decimal.cbrt = cbrt;          // ES6
   Decimal.ceil = ceil;
+  Decimal.clamp = clamp;
   Decimal.cos = cos;
   Decimal.cosh = cosh;          // ES6
   Decimal.div = div;
@@ -4399,6 +4433,7 @@ function clone(obj) {
   Decimal.sinh = sinh;          // ES6
   Decimal.sqrt = sqrt;
   Decimal.sub = sub;
+  Decimal.sum = sum;
   Decimal.tan = tan;
   Decimal.tanh = tanh;          // ES6
   Decimal.trunc = trunc;        // ES6
@@ -4493,7 +4528,7 @@ function hypot() {
  *
  */
 function isDecimalInstance(obj) {
-  return obj instanceof Decimal || obj && obj.name === '[object Decimal]' || false;
+  return obj instanceof Decimal || obj && obj.toStringTag === tag || false;
 }
 
 
@@ -4793,6 +4828,28 @@ function sub(x, y) {
 }
 
 
+/*
+ * Return a new Decimal whose value is the sum of the arguments, rounded to `precision`
+ * significant digits using rounding mode `rounding`.
+ *
+ * Only the result is rounded, not the intermediate calculations.
+ *
+ * arguments {number|string|Decimal}
+ *
+ */
+function sum() {
+  var i = 0,
+    args = arguments,
+    x = new this(args[i]);
+
+  external = false;
+  for (; x.s && ++i < args.length;) x = x.plus(args[i]);
+  external = true;
+
+  return finalise(x, this.precision, this.rounding);
+}
+
+
 /*
  * Return a new Decimal whose value is the tangent of `x`, rounded to `precision` significant
  * digits using rounding mode `rounding`.
@@ -4832,7 +4889,7 @@ P[Symbol.for('nodejs.util.inspect.custom')] = P.toString;
 P[Symbol.toStringTag] = 'Decimal';
 
 // Create and configure initial Decimal constructor.
-export var Decimal = clone(DEFAULTS);
+export var Decimal = P.constructor = clone(DEFAULTS);
 
 // Create the internal constants from their string values.
 LN10 = new Decimal(LN10);

doc/API.html

@@ -76,6 +76,7 @@ li span{float:right;margin-right:10px;color:#c0c0c0}
       <li><a href="#Datan2"     >atan2</a></li>
       <li><a href="#Dcbrt"      >cbrt</a></li>
       <li><a href="#Dceil"      >ceil</a></li>
+      <li><a href="#Dclamp"     >clamp</a></li>
       <li><a href="#Dclone"     >clone</a></li>
       <li><a href="#Dcos"       >cos</a></li>
       <li><a href="#Dcosh"      >cosh</a></li>
@@ -102,6 +103,7 @@ li span{float:right;margin-right:10px;color:#c0c0c0}
       <li><a href="#Dsinh"      >sinh</a></li>
       <li><a href="#Dsqrt"      >sqrt</a></li>
       <li><a href="#Dsub"       >sub</a></li>
+      <li><a href="#Dsum"       >sum</a></li>
       <li><a href="#Dtan"       >tan</a></li>
       <li><a href="#Dtanh"      >tanh</a></li>
       <li><a href="#Dtrunc"     >trunc</a></li>
@@ -137,6 +139,7 @@ li span{float:right;margin-right:10px;color:#c0c0c0}
       <li><a href="#abs"          >absoluteValue           </a><span>abs</span>     </li>
       <li><a href="#ceil"         >ceil                    </a>                     </li>
       <li><a href="#cmp"          >comparedTo              </a><span>cmp</span>     </li>
+      <li><a href="#clamp"        >clampedTo               </a><span>clamp</span>   </li>
       <li><a href="#cos"          >cosine                  </a><span>cos</span>     </li>
       <li><a href="#cbrt"         >cubeRoot                </a><span>cbrt</span>    </li>
       <li><a href="#dp"           >decimalPlaces           </a><span>dp</span>      </li>
@@ -298,6 +301,7 @@ new Decimal('0xff.8')                    // '255.5'
 
 new Decimal(0.046875)                    // '0.046875'
 new Decimal('0.046875000000')            // '0.046875'
+new Decimal('0.046_875_000_000')         // '0.046875'
 
 new Decimal(4.6875e-2)                   // '0.046875'
 new Decimal('468.75e-4')                 // '0.046875'
@@ -436,6 +440,16 @@ a.equals(b)                    // true</pre>
 
 
 
+    <h5 id="Dclamp">clamp<code class='inset'>.clamp(min, max) <i>&rArr; Decimal</i></code></h5>
+    <p>
+      <code>min</code>: <i>number|string|Decimal</i><br />
+      <code>max</code>: <i>number|string|Decimal</i>
+    </p>
+    <p>See <code><a href='#clamp'>clampedTo</a></code>.</p>
+    <pre>Decimal.clamp(10.1, 0, 10)     // '10'</pre>
+
+
+
     <h5 id="Dclone">
       clone
       <code class='inset'>.clone([object]) <i>&rArr; Decimal constructor</i></code>
@@ -601,7 +615,7 @@ a.equals(b)                    // true</pre>
 
 
     <h5 id="Dmax">
-      max<code class='inset'>.max([x [, y, ...]]) <i>&rArr; Decimal</i></code>
+      max<code class='inset'>.max(x [, y, ...]) <i>&rArr; Decimal</i></code>
     </h5>
     <p>
       <code>x</code>: <i>number|string|Decimal</i><br />
@@ -613,7 +627,7 @@ a.equals(b)                    // true</pre>
 
 
     <h5 id="Dmin">
-      min<code class='inset'>.min([x [, y, ...]]) <i>&rArr; Decimal</i></code>
+      min<code class='inset'>.min(x [, y, ...]) <i>&rArr; Decimal</i></code>
     </h5>
     <p>
       <code>x</code>: <i>number|string|Decimal</i><br />
@@ -833,7 +847,7 @@ a.equals(b)                    // true</pre>
 
 
 
-      <h5 id="Dsub">sub<code class='inset'>.sub(x, y) <i>&rArr; Decimal</i></code></h5>
+    <h5 id="Dsub">sub<code class='inset'>.sub(x, y) <i>&rArr; Decimal</i></code></h5>
     <p>
       <code>x</code>: <i>number|string|Decimal</i><br />
       <code>y</code>: <i>number|string|Decimal</i>
@@ -845,7 +859,26 @@ a.equals(b)                    // true</pre>
 
 
 
-     <h5 id="Dtan">tan<code class='inset'>.tan(x) <i>&rArr; Decimal</i></code></h5>
+    <h5 id="Dsum">sum<code class='inset'>.sum(x [, y, ...]) <i>&rArr; Decimal</i></code></h5>
+    <p>
+      <code>x</code>: <i>number|string|Decimal</i><br />
+      <code>y</code>: <i>number|string|Decimal</i>
+    </p>
+    <p>
+      Returns a new Decimal whose value is the sum of the <code>arguments</code>,
+      rounded to <a href='#precision'><code>precision</code></a> significant digits using
+      rounding mode <a href='#rounding'><code>rounding</code></a>.<br />
+      Only the result is rounded, not the intermediate summations.
+    </p>
+    <pre>
+x = 5
+y = '16'
+z = new Decimal(-11)
+Decimal.sum(x, y, z)           // '10'</pre>
+
+
+
+    <h5 id="Dtan">tan<code class='inset'>.tan(x) <i>&rArr; Decimal</i></code></h5>
     <p><code>x</code>: <i>number|string|Decimal</i></p>
     <p>See <code><a href='#tan'>tangent</a></code>.</p>
     <pre>a = Decimal.tan(x)
@@ -910,8 +943,11 @@ Decimal.precision = 0
       All functions which return a Decimal will round the return value to <code>precision</code>
       significant digits except <a href='#decimal'><code>Decimal</code></a>,
       <a href='#abs'><code>absoluteValue</code></a>,
-      <a href='#ceil'><code>ceil</code></a>, <a href='#floor'><code>floor</code></a>,
-      <a href='#neg'><code>negated</code></a>, <a href='#round'><code>round</code></a>,
+      <a href='#ceil'><code>ceil</code></a>,
+      <a href='#clamp'><code>clampedTo</code></a>,
+      <a href='#floor'><code>floor</code></a>,
+      <a href='#neg'><code>negated</code></a>,
+      <a href='#round'><code>round</code></a>,
       <a href='#toDP'><code>toDecimalPlaces</code></a>,
       <a href='#toNearest'><code>toNearest</code></a> and
       <a href='#trunc'><code>truncated</code></a>.
@@ -973,7 +1009,7 @@ new Decimal('1e-500')              // '1e-500'
 new Decimal('9.9e-501')            // '0'
 
 Decimal.set({ minE: -3 })
-new Decimal(0.001)                 // '0.01'       e is -3
+new Decimal(0.001)                 // '0.001'       e is -3
 new Decimal(0.0001)                // '0'          e is -4</pre>
     <p>
       The smallest possible magnitude of a non-zero Decimal is <code>1e-9000000000000000</code>
@@ -1244,6 +1280,28 @@ y.ceil()                      // '-1'</pre>
 
 
 
+    <h5 id="clamp">clampedTo<code class='inset'>.clamp(min, max) <i>&rArr; Decimal</i></code></h5>
+    <p>
+      <code>min</code>: <i>number|string|Decimal</i><br />
+      <code>max</code>: <i>number|string|Decimal</i>
+    </p>
+    <p>
+      Returns a new Decimal whose value is the value of this Decimal clamped to the range
+      delineated by <code>min</code> and <code>max</code>.
+    </p>
+    <p>
+      The return value is not affected by the value of the
+      <a href='#precision'><code>precision</code></a> setting.
+    </p>
+    <pre>
+x = new Decimal(5)
+min = new Decimal(100)
+max = new Decimal(Infinity)
+x.clampedTo(min, max)         // '100'
+x.clamp(-10, -0.1)            // '-0.1'</pre>
+
+
+
     <h5 id="cmp">comparedTo<code class='inset'>.cmp(x) <i>&rArr; number</i></code></h5>
     <p><code>x</code>: <i>number|string|Decimal</i></p>
     <table>
@@ -1613,10 +1671,6 @@ x = new Decimal(1)
 x.isFinite()                             // true
 y = new Decimal(Infinity)
 y.isFinite()                             // false</pre>
-    <p>
-      Note: The native method <code>isFinite()</code> can be used if
-      <code>n &lt;= Number.MAX_VALUE</code>.
-    </p>
 
 
 
@@ -1643,7 +1697,6 @@ x = new Decimal(NaN)
 x.isNaN()                                // true
 y = new Decimal('Infinity')
 y.isNaN()                                // false</pre>
-    <p>Note: The native method <code>isNaN()</code> can also be used.</p>
 
 
 
@@ -1657,18 +1710,17 @@ x = new Decimal(-0)
 x.isNegative()                           // true
 y = new Decimal(2)
 y.isNeg                                  // false</pre>
-    <p>Note: <code>n &lt; 0</code> can be used if <code>n &lt;= -Number.MIN_VALUE</code>.</p>
-
-    <p>Also note that signed zeroes are implemented, following the IEEE Standard
-      for Floating-Point Arithmetic (IEEE 754).</p>
-
+    <p>Note that zero is signed.</p>
     <pre>
-Decimal(0).valueOf()                 // '0'
-Decimal(0).isNegative()              // false
-Decimal(0).negated().valueOf()       // '-0'
-Decimal(0).negated().isNegative()    // true
+new Decimal(0).valueOf()                 // '0'
+new Decimal(0).isNegative()              // false
+new Decimal(0).negated().valueOf()       // '-0'
+new Decimal(0).negated().isNegative()    // true
+new Decimal(-0).isNegative()             // true
     </pre>
 
+
+
      <h5 id="isPos">isPositive<code class='inset'>.isPos() <i>&rArr; boolean</i></code></h5>
     <p>
       Returns <code>true</code> if the value of this Decimal is positive, otherwise returns
@@ -1679,7 +1731,6 @@ x = new Decimal(0)
 x.isPositive()                           // true
 y = new Decimal(-2)
 y.isPos                                  // false</pre>
-    <p>Note: <code>n &lt; 0</code> can be used if <code>n &lt;= -Number.MIN_VALUE</code>.</p>
 
 
 
@@ -1693,7 +1744,6 @@ x = new Decimal(-0)
 x.isZero() && x.isNeg()                  // true
 y = new Decimal(Infinity)
 y.isZero()                               // false</pre>
-    <p>Note: <code>n == 0</code> can be used if <code>n &gt;= Number.MIN_VALUE</code>.</p>
 
 
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "decimal.js",
   "description": "An arbitrary-precision Decimal type for JavaScript.",
-  "version": "10.2.1",
+  "version": "10.4.3",
   "keywords": [
     "arbitrary",
     "precision",
@@ -23,14 +23,33 @@
   "main": "decimal",
   "module": "decimal.mjs",
   "browser": "decimal.js",
+  "exports": {
+    ".": {
+      "types": "./decimal.d.ts",
+      "import": "./decimal.mjs",
+      "require": "./decimal.js"
+    },
+    "./decimal.mjs": "./decimal.mjs",
+    "./decimal.js": "./decimal.js",
+    "./package.json": "./package.json",
+    "./decimal": {
+      "types": "./decimal.d.ts",
+      "import": "./decimal.mjs",
+      "require": "./decimal.js"
+    }
+  },
   "author": {
     "name": "Michael Mclaughlin",
     "email": "M8ch88l@gmail.com"
   },
   "license": "MIT",
   "scripts": {
-    "test": "node ./test/test.js",
-    "build": "uglifyjs decimal.js --source-map url=decimal.min.js.map -c -m -o decimal.min.js"
+    "test": "node ./test/test.js"
   },
-  "types": "decimal.d.ts"
+  "types": "decimal.d.ts",
+  "files": [
+    "decimal.js",
+    "decimal.mjs",
+    "decimal.d.ts"
+  ]
 }

test/modules/clamp.js

@@ -0,0 +1,45 @@
+if (typeof T === 'undefined') require('../setup');
+
+T('clamp', function () {
+
+  function t(x, min, max, expected) {
+    //T.assertEqual(expected, new Decimal(x).clampedTo(min, max).valueOf());
+    T.assertEqual(expected, new Decimal(x).clamp(min, max).valueOf());
+    //T.assertEqual(expected, Decimal.clamp(x, min, max).valueOf());
+  }
+
+  t('-0', '0', '0', '-0');
+  t('-0', '-0', '0', '-0');
+  t('-0', '0', '-0', '-0');
+  t('-0', '-0', '-0', '-0');
+  
+  t('0', '0', '0', '0');
+  t('0', '-0', '0', '0');
+  t('0', '0', '-0', '0');
+  t('0', '-0', '-0', '0');
+  
+  t(0, 0, 1, '0');
+  t(-1, 0, 1, '0');
+  t(-2, 0, 1, '0');
+  t(1, 0, 1, '1');
+  t(2, 0, 1, '1');
+  
+  t(1, 1, 1, '1');
+  t(-1, 1, 1, '1');
+  t(-1, -1, 1, '-1');
+  t(2, 1, 2, '2');
+  t(3, 1, 2, '2');
+  t(1, 0, 1, '1');
+  t(2, 0, 1, '1');
+  
+  t(Infinity, 0, 1, '1');
+  t(0, -Infinity, 0, '0');
+  t(-Infinity, 0, 1, '0');
+  t(-Infinity, -Infinity, Infinity, '-Infinity');
+  t(Infinity, -Infinity, Infinity, 'Infinity');
+  t(0, 1, Infinity, '1');
+  
+  t(0, NaN, 1, 'NaN');
+  t(0, 0, NaN, 'NaN');
+  t(NaN, 0, 1, 'NaN');
+});

test/modules/sum.js

@@ -0,0 +1,64 @@
+if (typeof T === 'undefined') require('../setup');
+
+T('sum', function () {
+  var expected;
+
+  function t() {
+    T.assertEqualDecimal(expected, Decimal.sum.apply(Decimal, arguments));
+  }
+
+  expected = new Decimal(0);
+
+  t('0');
+  t('0', new Decimal(0));
+  t(1, 0, '-1');
+  t(0, new Decimal('-10'), 0, 0, 0, 0, 0, 10);
+  t(11, -11);
+  t(1, '2', new Decimal(3), new Decimal('4'), -10);
+  t(new Decimal(-10), '9', new Decimal(0.01), 0.99);
+  
+  expected = new Decimal(10);
+
+  t('10');
+  t('0', new Decimal('10'));
+  t(10, 0);
+  t(0, 0, 0, 0, 0, 0, 10);
+  t(11, -1);
+  t(1, '2', new Decimal(3), new Decimal('4'));
+  t('9', new Decimal(0.01), 0.99);
+
+  expected = new Decimal(600);
+
+  t(100, 200, 300);
+  t('100', '200', '300');
+  t(new Decimal(100), new Decimal(200), new Decimal(300));
+  t(100, '200', new Decimal(300));
+  t(99.9, 200.05, 300.05);
+
+  expected = new Decimal(NaN);
+
+  t(NaN);
+  t('1', NaN);
+  t(100, 200, NaN);
+  t(NaN, 0, '9', new Decimal(0), 11, Infinity);
+  t(0, new Decimal('-Infinity'), '9', new Decimal(NaN), 11);
+  t(4, '-Infinity', 0, '9', new Decimal(0), Infinity, 2);
+
+  expected = new Decimal(Infinity);
+
+  t(Infinity);
+  t(1, '1e10000000000000000000000000000000000000000', '4');
+  t(100, 200, 'Infinity');
+  t(0, new Decimal('Infinity'), '9', new Decimal(0), 11);
+  t(0, '9', new Decimal(0), 11, Infinity);
+  t(4, new Decimal(Infinity), 0, '9', new Decimal(0), Infinity, 2);
+
+  expected = new Decimal(-Infinity);
+
+  t(-Infinity);
+  t(1, '-1e10000000000000000000000000000000000000000', '4');
+  t(100, 200, '-Infinity');
+  t(0, new Decimal('-Infinity'), '9', new Decimal(0), 11);
+  t(0, '9', new Decimal(0), 11, -Infinity);
+  t(4, new Decimal(-Infinity), 0, '9', new Decimal(0), -Infinity, 2);
+});

test/test.html

@@ -28,6 +28,7 @@
     'atanh',
     'cbrt',
     'ceil',
+    'clamp',
     'clone',
     'cmp',
     'config',
@@ -59,6 +60,7 @@
     'sin',
     'sinh',
     'sqrt',
+    'sum',
     'tan',
     'tanh',
     'times',

test/test.js

@@ -15,6 +15,7 @@ console.log('\n Testing decimal.js\n');
   'atanh',
   'cbrt',
   'ceil',
+  'clamp',
   'clone',
   'cmp',
   'config',
@@ -46,6 +47,7 @@ console.log('\n Testing decimal.js\n');
   'sin',
   'sinh',
   'sqrt',
+  'sum',
   'tan',
   'tanh',
   'times',