Merge branch 'develop' into broadcasting-functions

dvd101x · web-flow · commit 5e13b308ba41 · 2026-01-08T21:31:58.000-06:00
diff --git a/AUTHORS b/AUTHORS
@@ -282,5 +282,7 @@ Richard Taylor <richard.taylor@claconnect.com>
 NilsDietrich <61544566+NilsDietrich@users.noreply.github.com>
 anslem chibuike <144047596+AnslemHack@users.noreply.github.com>
 Ayomide Bamigbade <iamtryve@gmail.com>
+Dheemanth07 <dheemanth1007@gmail.com>
+Anadian <willanad@yandex.com>
 
 # Generated by tools/update-authors.js
diff --git a/HISTORY.md b/HISTORY.md
@@ -2,6 +2,9 @@
 
 # unreleased changes since 15.1.0
 
+- Fix: #3631 Handle bigints in `compareNatural` (#3632). Thanks @Dheemanth07.
+- Docs: Correct several arithmetic and relational documentation examples
+  and add History (#3630). Thanks @Anadian.
 - Fix: #3578 interpret empty true-expr of conditional as error (#3581).
   Thanks @gwhitney.
 - Fix: #3597 added nullish type definitions (#3601). Thanks @Ayo1984.
diff --git a/NOTICE b/NOTICE
@@ -1,7 +1,7 @@
 math.js
 https://github.com/josdejong/mathjs
 
-Copyright (C) 2013-2025 Jos de Jong <wjosdejong@gmail.com>
+Copyright (C) 2013-2026 Jos de Jong <wjosdejong@gmail.com>
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@ Math.js is an extensive math library for JavaScript and Node.js. It features a f
 [![Version](https://img.shields.io/npm/v/mathjs.svg)](https://www.npmjs.com/package/mathjs)
 [![Downloads](https://img.shields.io/npm/dm/mathjs.svg)](https://www.npmjs.com/package/mathjs)
 [![Build Status](https://github.com/josdejong/mathjs/workflows/Node.js%20CI/badge.svg)](https://github.com/josdejong/mathjs/actions)
-[![Maintenance](https://img.shields.io/maintenance/yes/2025.svg)](https://github.com/josdejong/mathjs/graphs/commit-activity)
+[![Maintenance](https://img.shields.io/maintenance/yes/2026.svg)](https://github.com/josdejong/mathjs/graphs/commit-activity)
 [![License](https://img.shields.io/github/license/josdejong/mathjs.svg)](https://github.com/josdejong/mathjs/blob/master/LICENSE)
 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fjosdejong%2Fmathjs.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fjosdejong%2Fmathjs?ref=badge_shield)
 [![Codecov](https://codecov.io/gh/josdejong/mathjs/branch/develop/graph/badge.svg)](https://codecov.io/gh/josdejong/mathjs)
@@ -202,7 +202,7 @@ Thanks, GitHub Actions and LambdaTest for the generous free hosting of this open
 mathjs is published under the Apache 2.0 license:
 
 ```
-Copyright (C) 2013-2025 Jos de Jong <wjosdejong@gmail.com>
+Copyright (C) 2013-2026 Jos de Jong <wjosdejong@gmail.com>
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
diff --git a/bin/cli.js b/bin/cli.js
@@ -30,7 +30,7 @@
  *     cat script.txt | mathjs > results.txt  Run input stream, output to file
  *
  * @license
- * Copyright (C) 2013-2025 Jos de Jong <wjosdejong@gmail.com>
+ * Copyright (C) 2013-2026 Jos de Jong <wjosdejong@gmail.com>
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
  * use this file except in compliance with the License. You may obtain a copy
diff --git a/src/function/arithmetic/add.js b/src/function/arithmetic/add.js
@@ -45,14 +45,21 @@ export const createAdd = /* #__PURE__ */ factory(
      *
      *    const c = math.unit('5 cm')
      *    const d = math.unit('2.1 mm')
-     *    math.add(c, d)               // returns Unit 52.1 mm
+     *    math.add(c, d)               // returns Unit 5.21 cm
      *
      *    math.add("2.3", "4")         // returns number 6.3
      *
      * See also:
      *
      *    subtract, sum
      *
+     * History:
+     *
+     *     v13     Handle bigint arguments
+     *     v11.6   Support matrix broadcasting
+     *     v3.8    Allow more than two arguments
+     *     v0.0.2  Created
+     *
      * @param  {number | BigNumber | bigint | Fraction | Complex | Unit | Array | Matrix} x First value to add
      * @param  {number | BigNumber | bigint | Fraction | Complex | Unit | Array | Matrix} y Second value to add
      * @return {number | BigNumber | bigint | Fraction | Complex | Unit | Array | Matrix} Sum of `x` and `y`
diff --git a/src/function/arithmetic/cbrt.js b/src/function/arithmetic/cbrt.js
@@ -36,17 +36,18 @@ export const createCbrt = /* #__PURE__ */ factory(name, dependencies, ({ config,
    *    math.map([27, 64, 125], x => math.cbrt(x))       // returns [3, 4, 5]
    *
    *    const x = math.complex('8i')
-   *    math.cbrt(x)                   // returns Complex 1.7320508075689 + i
-   *    math.cbrt(x, true)             // returns Matrix [
-   *                                    //    1.7320508075689 + i
-   *                                    //   -1.7320508075689 + i
-   *                                    //   -2i
-   *                                    // ]
+   *    math.cbrt(x)                   // returns 1.7320508075689 + i ...
+   *    math.cbrt(x, true)
+   *    // Complex Matrix ["1.7320508075689+i", "-1.7320508075689+i", "-2i"]
    *
    * See also:
    *
    *    square, sqrt, cube
    *
+   * History:
+   *
+   *    v2.3  Created
+   *
    * @param {number | BigNumber | Complex | Unit} x
    *            Value for which to calculate the cubic root.
    * @param {boolean} [allRoots]  Optional, false by default. Only applicable
diff --git a/src/function/arithmetic/ceil.js b/src/function/arithmetic/ceil.js
@@ -86,13 +86,13 @@ export const createCeil = /* #__PURE__ */ factory(name, dependencies, ({ typed,
    *    math.ceil(-4.782, 2)         // returns number -4.78
    *
    *    const c = math.complex(3.24, -2.71)
-   *    math.ceil(c)                 // returns Complex 4 - 2i
+   *    math.ceil(c)                 // returns Complex 4 - 2i ...
    *    math.ceil(c, 1)              // returns Complex 3.3 - 2.7i
    *
    *    const unit = math.unit('3.241 cm')
    *    const cm = math.unit('cm')
    *    const mm = math.unit('mm')
-   *    math.ceil(unit, 1, cm)      // returns Unit 3.3 cm
+   *    math.ceil(unit, 1, cm)      // returns Unit 3.3 cm ...
    *    math.ceil(unit, 1, mm)      // returns Unit 32.5 mm
    *
    *    math.ceil([3.2, 3.8, -4.7])  // returns Array [4, 4, -4]
@@ -102,6 +102,14 @@ export const createCeil = /* #__PURE__ */ factory(name, dependencies, ({ typed,
    *
    *    floor, fix, round
    *
+   * History:
+   *
+   *     v14    Handle Units
+   *     v7.4   Allow second "precision" argument
+   *     v5.7   Support tolerance for round-off errors
+   *     v2     Handle Fractions
+   *     v0.1   Created
+   *
    * @param  {number | BigNumber | Fraction | Complex | Unit | Array | Matrix} x  Value to be rounded
    * @param  {number | BigNumber | Array} [n=0]                            Number of decimals
    * @param  {Unit} [valuelessUnit]                                        A valueless unit
diff --git a/src/function/arithmetic/exp.js b/src/function/arithmetic/exp.js
@@ -22,16 +22,18 @@ export const createExp = /* #__PURE__ */ factory(name, dependencies, ({ typed })
    *    math.log(math.exp(2))        // returns number 2
    *
    *    math.map([1, 2, 3], math.exp)
-   *    // returns Array [
-   *    //   2.718281828459045,
-   *    //   7.3890560989306495,
-   *    //   20.085536923187668
-   *    // ]
+   *    // returns [2.718281828459045, 7.3890560989306495, 20.085536923187668]
    *
    * See also:
    *
    *    expm1, expm, log, pow
    *
+   * History:
+   *
+   *    v11     Don't apply elementwise, avoid confusion with matrix exponential
+   *    v0.20   Handle BigNumbers
+   *    v0.0.2  Created
+   *
    * @param {number | BigNumber | Complex} x  A number to exponentiate
    * @return {number | BigNumber | Complex} Exponential of `x`
    */
diff --git a/src/function/arithmetic/expm1.js b/src/function/arithmetic/expm1.js
@@ -25,16 +25,17 @@ export const createExpm1 = /* #__PURE__ */ factory(name, dependencies, ({ typed,
    *    math.log(math.expm1(2) + 1)        // returns number 2
    *
    *    math.map([1, 2, 3], math.expm1)
-   *    // returns Array [
-   *    //   1.718281828459045,
-   *    //   6.3890560989306495,
-   *    //   19.085536923187668
-   *    // ]
+   *    // returns [1.718281828459045, 6.3890560989306495, 19.085536923187668]
    *
    * See also:
    *
    *    exp, expm, log, pow
    *
+   * History:
+   *
+   *    v11    Don't apply elementwise, avoids confusion with matrix exponential
+   *    v4.2   Created
+   *
    * @param {number | BigNumber | Complex} x  The number to exponentiate
    * @return {number | BigNumber | Complex} Exponential of `x`, minus one
    */
diff --git a/src/function/arithmetic/fix.js b/src/function/arithmetic/fix.js
@@ -49,13 +49,13 @@ export const createFix = /* #__PURE__ */ factory(name, dependencies, ({ typed, C
    *    math.fix(-4.17, 1)               // returns number -4.1
    *
    *    const c = math.complex(3.22, -2.78)
-   *    math.fix(c)                  // returns Complex 3 - 2i
+   *    math.fix(c)                  // returns Complex 3 - 2i ...
    *    math.fix(c, 1)               // returns Complex 3.2 -2.7i
    *
    *    const unit = math.unit('3.241 cm')
    *    const cm = math.unit('cm')
    *    const mm = math.unit('mm')
-   *    math.fix(unit, 1, cm)      // returns Unit 3.2 cm
+   *    math.fix(unit, 1, cm)      // returns Unit 3.2 cm ...
    *    math.fix(unit, 1, mm)      // returns Unit 32.4 mm
    *
    *    math.fix([3.2, 3.8, -4.7])      // returns Array [3, 3, -4]
@@ -65,6 +65,14 @@ export const createFix = /* #__PURE__ */ factory(name, dependencies, ({ typed, C
    *
    *    ceil, floor, round
    *
+   * History:
+   *
+   *     v14    Handle Units
+   *     v7.4   Allow second "precision" argument
+   *     v5.7   Support tolerance for round-off errors
+   *     v2     Handle Fractions
+   *     v0.1   Created
+   *
    * @param  {number | BigNumber | Fraction | Complex | Unit | Array | Matrix} x  Value to be rounded
    * @param  {number | BigNumber | Array} [n=0]                            Number of decimals
    * @param  {Unit} [valuelessUnit]                                        A valueless unit
diff --git a/src/function/arithmetic/floor.js b/src/function/arithmetic/floor.js
@@ -92,13 +92,13 @@ export const createFloor = /* #__PURE__ */ factory(name, dependencies, ({ typed,
    *    math.floor(-4.782, 2)         // returns number -4.79
    *
    *    const c = math.complex(3.24, -2.71)
-   *    math.floor(c)                 // returns Complex 3 - 3i
+   *    math.floor(c)                 // returns Complex 3 - 3i ...
    *    math.floor(c, 1)              // returns Complex 3.2 -2.8i
    *
    *    const unit = math.unit('3.241 cm')
    *    const cm = math.unit('cm')
    *    const mm = math.unit('mm')
-   *    math.floor(unit, 1, cm)      // returns Unit 3.2 cm
+   *    math.floor(unit, 1, cm)      // returns Unit 3.2 cm ...
    *    math.floor(unit, 1, mm)      // returns Unit 32.4 mm
    *
    *    math.floor([3.2, 3.8, -4.7])       // returns Array [3, 3, -5]
@@ -112,6 +112,14 @@ export const createFloor = /* #__PURE__ */ factory(name, dependencies, ({ typed,
    *
    *    ceil, fix, round
    *
+   * History:
+   *
+   *     v14    Handle Units
+   *     v7.4   Allow second "precision" argument
+   *     v5.7   Support tolerance for round-off errors
+   *     v2     Handle Fractions
+   *     v0.1   Created
+   *
    * @param  {number | BigNumber | Fraction | Complex | Unit | Array | Matrix} x  Value to be rounded
    * @param  {number | BigNumber | Array} [n=0]                            Number of decimals
    * @param  {Unit} [valuelessUnit]                                        A valueless unit
diff --git a/src/function/arithmetic/mod.js b/src/function/arithmetic/mod.js
@@ -51,14 +51,20 @@ export const createMod = /* #__PURE__ */ factory(name, dependencies, ({ typed, c
    *    function isOdd(x) {
    *      return math.mod(x, 2) != 0
    *    }
-   *
-   *    isOdd(2)                      // returns false
+   *    isOdd(2)                      // returns false...
    *    isOdd(3)                      // returns true
    *
    * See also:
    *
    *    divide
    *
+   * History:
+   *
+   *    v13    Handle bigints
+   *    v11.6  Support matrix broadcasting
+   *    v2     Handle Fractions
+   *    v0.2   Created
+   *
    * @param  {number | BigNumber | bigint | Fraction | Array | Matrix} x Dividend
    * @param  {number | BigNumber | bigint | Fraction | Array | Matrix} y Divisor
    * @return {number | BigNumber | bigint | Fraction | Array | Matrix} Returns the remainder of `x` divided by `y`.
diff --git a/src/function/arithmetic/nthRoot.js b/src/function/arithmetic/nthRoot.js
@@ -38,14 +38,20 @@ export const createNthRoot = /* #__PURE__ */ factory(name, dependencies, ({ type
    *
    * Examples:
    *
-   *     math.nthRoot(9, 2)    // returns 3 (since 3^2 == 9)
-   *     math.sqrt(9)          // returns 3 (since 3^2 == 9)
-   *     math.nthRoot(64, 3)   // returns 4 (since 4^3 == 64)
+   *     math.nthRoot(9, 2)    // returns 3
+   *     math.sqrt(9)          // returns 3
+   *     math.nthRoot(64, 3)   // returns 4
    *
    * See also:
    *
    *     sqrt, pow
    *
+   * History:
+   *
+   *     v11.6  Support matrix broadcasting
+   *     v2     Handle Complex
+   *     v1.1   Created
+   *
    * @param {number | BigNumber | Array | Matrix | Complex} a
    *              Value for which to calculate the nth root
    * @param {number | BigNumber} [root=2]    The root.
diff --git a/src/function/arithmetic/nthRoots.js b/src/function/arithmetic/nthRoots.js
@@ -76,22 +76,19 @@ export const createNthRoots = /* #__PURE__ */ factory(name, dependencies, ({ typ
    *
    * Examples:
    *
-   *    math.nthRoots(1)
-   *    // returns [
-   *    //   {re: 1, im: 0},
-   *    //   {re: -1, im: 0}
-   *    // ]
+   *    math.nthRoots(1) // returns [ {re: 1, im: 0}, {re: -1, im: 0} ]
+   *
    *    math.nthRoots(1, 3)
-   *    // returns [
-   *    //   { re: 1, im: 0 },
-   *    //   { re: -0.4999999999999998, im: 0.8660254037844387 },
-   *    //   { re: -0.5000000000000004, im: -0.8660254037844385 }
-   *    // ]
+   *    // Complex [1, "-0.5+0.866025403784439i", "-0.5-0.866025403784439i"]
    *
    * See also:
    *
    *    nthRoot, pow, sqrt
    *
+   * History:
+   *
+   *    v1.1   Created
+   *
    * @param {number | BigNumber | Fraction | Complex} x Number to be rounded
    * @param {number} [root=2] Optional root, default value is 2
    * @return {number | BigNumber | Fraction | Complex} Returns the nth roots
diff --git a/src/function/relational/compareNatural.js b/src/function/relational/compareNatural.js
@@ -53,7 +53,7 @@ export const createCompareNatural = /* #__PURE__ */ factory(name, dependencies,
    *    math.compareNatural('Answer: 10', 'Answer: 2') // returns 1
    *    math.compareText('Answer: 10', 'Answer: 2')    // returns -1
    *    math.compare('Answer: 10', 'Answer: 2')
-   *        // Error: Cannot convert "Answer: 10" to a number
+   *    // Error: Cannot convert "Answer: 10" to a number
    *
    *    const a = math.unit('5 cm')
    *    const b = math.unit('40 mm')
@@ -74,6 +74,12 @@ export const createCompareNatural = /* #__PURE__ */ factory(name, dependencies,
    *
    *    compare, compareText
    *
+   * History:
+   *
+   *     v15.2   Handle bigints
+   *     v3.14   Created
+   *
+   *
    * @param  {*} x First value to compare
    * @param  {*} y Second value to compare
    * @return {number} Returns the result of the comparison:
@@ -87,8 +93,8 @@ export const createCompareNatural = /* #__PURE__ */ factory(name, dependencies,
     let c
 
     // numeric types
-    if ((typeX === 'number' || typeX === 'BigNumber' || typeX === 'Fraction') &&
-        (typeY === 'number' || typeY === 'BigNumber' || typeY === 'Fraction')) {
+    if ((typeX === 'number' || typeX === 'BigNumber' || typeX === 'Fraction' || typeX === 'bigint') &&
+        (typeY === 'number' || typeY === 'BigNumber' || typeY === 'Fraction' || typeY === 'bigint')) {
       c = compare(x, y)
       if (c.toString() !== '0') {
         // c can be number, BigNumber, or Fraction
diff --git a/src/function/relational/deepEqual.js b/src/function/relational/deepEqual.js
@@ -21,16 +21,21 @@ export const createDeepEqual = /* #__PURE__ */ factory(name, dependencies, ({ ty
    *
    *    math.deepEqual(2, 4)   // returns false
    *
-   *    a = [2, 5, 1]
-   *    b = [2, 7, 1]
+   *    const a = [2, 5, 1]
+   *    const b = [2, 7, 1]
    *
-   *    math.deepEqual(a, b)   // returns false
+   *    math.deepEqual(a, b)   // returns false...
    *    math.equal(a, b)       // returns [true, false, true]
    *
    * See also:
    *
    *    equal, unequal
    *
+   * History:
+   *
+   *    v2     Handle Fractions
+   *    v0.2   Created
+   *
    * @param  {number | BigNumber | Fraction | Complex | Unit | Array | Matrix} x First matrix to compare
    * @param  {number | BigNumber | Fraction | Complex | Unit | Array | Matrix} y Second matrix to compare
    * @return {number | BigNumber | Fraction | Complex | Unit | Array | Matrix}
diff --git a/src/function/relational/equal.js b/src/function/relational/equal.js
diff --git a/src/function/relational/unequal.js b/src/function/relational/unequal.js
diff --git a/src/function/utils/isFinite.js b/src/function/utils/isFinite.js
diff --git a/src/header.js b/src/header.js
diff --git a/test/node-tests/doc.test.js b/test/node-tests/doc.test.js
diff --git a/test/unit-tests/function/relational/compareNatural.test.js b/test/unit-tests/function/relational/compareNatural.test.js

Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,7 @@`
`30`	`30`	`* cat script.txt \| mathjs > results.txt Run input stream, output to file`
`31`	`31`	`*`
`32`	`32`	`* @license`
`33`		`- * Copyright (C) 2013-2025 Jos de Jong <wjosdejong@gmail.com>`
	`33`	`+ * Copyright (C) 2013-2026 Jos de Jong <wjosdejong@gmail.com>`
`34`	`34`	`*`
`35`	`35`	`* Licensed under the Apache License, Version 2.0 (the "License"); you may not`
`36`	`36`	`* use this file except in compliance with the License. You may obtain a copy`
Original file line number	Diff line number	Diff line change
`@@ -45,14 +45,21 @@ export const createAdd = /* #__PURE__ */ factory(`
`45`	`45`	`*`
`46`	`46`	`* const c = math.unit('5 cm')`
`47`	`47`	`* const d = math.unit('2.1 mm')`
`48`		`- * math.add(c, d) // returns Unit 52.1 mm`
	`48`	`+ * math.add(c, d) // returns Unit 5.21 cm`
`49`	`49`	`*`
`50`	`50`	`* math.add("2.3", "4") // returns number 6.3`
`51`	`51`	`*`
`52`	`52`	`* See also:`
`53`	`53`	`*`
`54`	`54`	`* subtract, sum`
`55`	`55`	`*`
	`56`	`+ * History:`
	`57`	`+ *`
	`58`	`+ * v13 Handle bigint arguments`
	`59`	`+ * v11.6 Support matrix broadcasting`
	`60`	`+ * v3.8 Allow more than two arguments`
	`61`	`+ * v0.0.2 Created`
	`62`	`+ *`
`56`	`63`	`* @param {number \| BigNumber \| bigint \| Fraction \| Complex \| Unit \| Array \| Matrix} x First value to add`
`57`	`64`	`* @param {number \| BigNumber \| bigint \| Fraction \| Complex \| Unit \| Array \| Matrix} y Second value to add`
`58`	`65`	* @return {number \| BigNumber \| bigint \| Fraction \| Complex \| Unit \| Array \| Matrix} Sum of `x` and `y`
Original file line number	Diff line number	Diff line change
`@@ -22,16 +22,18 @@ export const createExp = /* #__PURE__ */ factory(name, dependencies, ({ typed })`
`22`	`22`	`* math.log(math.exp(2)) // returns number 2`
`23`	`23`	`*`
`24`	`24`	`* math.map([1, 2, 3], math.exp)`
`25`		`- * // returns Array [`
`26`		`- * // 2.718281828459045,`
`27`		`- * // 7.3890560989306495,`
`28`		`- * // 20.085536923187668`
`29`		`- * // ]`
	`25`	`+ * // returns [2.718281828459045, 7.3890560989306495, 20.085536923187668]`
`30`	`26`	`*`
`31`	`27`	`* See also:`
`32`	`28`	`*`
`33`	`29`	`* expm1, expm, log, pow`
`34`	`30`	`*`
	`31`	`+ * History:`
	`32`	`+ *`
	`33`	`+ * v11 Don't apply elementwise, avoid confusion with matrix exponential`
	`34`	`+ * v0.20 Handle BigNumbers`
	`35`	`+ * v0.0.2 Created`
	`36`	`+ *`
`35`	`37`	`* @param {number \| BigNumber \| Complex} x A number to exponentiate`
`36`	`38`	* @return {number \| BigNumber \| Complex} Exponential of `x`
`37`	`39`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -25,16 +25,17 @@ export const createExpm1 = /* #__PURE__ */ factory(name, dependencies, ({ typed,`
`25`	`25`	`* math.log(math.expm1(2) + 1) // returns number 2`
`26`	`26`	`*`
`27`	`27`	`* math.map([1, 2, 3], math.expm1)`
`28`		`- * // returns Array [`
`29`		`- * // 1.718281828459045,`
`30`		`- * // 6.3890560989306495,`
`31`		`- * // 19.085536923187668`
`32`		`- * // ]`
	`28`	`+ * // returns [1.718281828459045, 6.3890560989306495, 19.085536923187668]`
`33`	`29`	`*`
`34`	`30`	`* See also:`
`35`	`31`	`*`
`36`	`32`	`* exp, expm, log, pow`
`37`	`33`	`*`
	`34`	`+ * History:`
	`35`	`+ *`
	`36`	`+ * v11 Don't apply elementwise, avoids confusion with matrix exponential`
	`37`	`+ * v4.2 Created`
	`38`	`+ *`
`38`	`39`	`* @param {number \| BigNumber \| Complex} x The number to exponentiate`
`39`	`40`	* @return {number \| BigNumber \| Complex} Exponential of `x`, minus one
`40`	`41`	`*/`