Merge remote-tracking branch 'origin/develop' into develop

josdejong · josdejong · commit 04e6e2d7a949 · 2025-12-17T15:03:33.000+01:00
diff --git a/README.md b/README.md
@@ -133,7 +133,7 @@ At the lowest level, mathjs has immutable factory functions which create immutab
 A common case is to implement a new function. This involves the following steps:
 
 - Implement the function in the right category, for example `./src/function/arithmetic/myNewFunction.js`, where you can replace `arithmetic` with the proper category, and `myNewFunction` with the name of the new function. Add the new function to the index files `./src/factoriesAny.js` and possibly `./src/factoriesNumber.js`.
-- Write documentation on the function in the source code comment of `myNewFunction.js`. This documentation is used to auto generate documentation on the website.
+- Write documentation on the function in the source code comment of `myNewFunction.js`. This documentation is used to auto generate documentation on the website. It should include a History section with one line, indicating the upcoming version number in which the function will be created.
 - Write embedded documentation for the new function in `./src/expression/embeddedDocs/function/arithmetic/myNewFunction.js`. Add the new documentation to the index file `./src/expression/embeddedDocs/embeddedDocs.js`.
 - Write unit tests for the function in `./test/unit-tests/function/arithmetic/myNewFunction.test.js`.
 - Write the necessary TypeScript definitions for the new function in `./types/index.d.ts`, and write tests for it in `./test/typescript-tests/testTypes.ts`. This is described in [./types/EXPLANATION.md](./types/EXPLANATION.md) -- make sure to read that page, as Typescript definitions must be added in _multiple_ places in the code.
diff --git a/src/core/function/import.js b/src/core/function/import.js
@@ -56,6 +56,13 @@ export function importFactory (typed, load, math, importedFactories) {
    *
    *    math.fibonacci(7) // returns 13
    *
+   * History:
+   *
+   *    v0.2   Created
+   *    v0.7   Changed second parameter to an options object
+   *    v2     Dropped support for direct import of a module by name
+   *    v14.2  Add facility for specifying the former name of an import
+   *
    * @param {Object | Array} functions  Object with functions to be imported.
    * @param {Object} [options]          Import options.
    */
diff --git a/src/expression/parse.js b/src/expression/parse.js
@@ -80,6 +80,23 @@ export const createParse = /* #__PURE__ */ factory(name, dependencies, ({
    *
    *     evaluate, compile
    *
+   * History:
+   *
+   *     v0.9   Created
+   *     v0.13  Switched to one-based indices
+   *     v0.14  Added `[1,2;3,4]` notation for matrices
+   *     v0.18  Dropped the `function` keyword
+   *     v0.20  Added ternary conditional
+   *     v0.27  Allow multi-line expressions; allow functions that receive
+   *            unevaluated parameters (`rawArgs`)
+   *     v3     Add object notation; allow assignments internal to other
+   *            expressions
+   *     v7.3   Supported binary, octal, and hexadecimal notation
+   *     v9.5   Support for calculations with percentages
+   *     v12.4  Allow trailing commas in matrices
+   *     v14.8  Add nullish coalescing operator
+   *     v15.1  Add optional chaining operator
+   *
    * @param {string | string[] | Matrix} expr          Expression to be parsed
    * @param {{nodes: Object<string, Node>}} [options]  Available options:
    *                                                   - `nodes` a set of custom nodes
diff --git a/src/function/algebra/polynomialRoot.js b/src/function/algebra/polynomialRoot.js
@@ -61,6 +61,10 @@ export const createPolynomialRoot = /* #__PURE__ */ factory(name, dependencies,
    * See also:
    *     cbrt, sqrt
    *
+   * History:
+   *
+   *     v11.4  Created
+   *
    * @param {... number | Complex} coeffs
    *     The coefficients of the polynomial, starting with with the constant coefficent, followed
    *     by the linear coefficient and subsequent coefficients of increasing powers.
diff --git a/src/function/arithmetic/log.js b/src/function/arithmetic/log.js
@@ -34,6 +34,19 @@ export const createLog = /* #__PURE__ */ factory(name, dependencies, ({ typed, t
    *
    *    exp, log2, log10, log1p
    *
+   * History:
+   *
+   *    v0.0.2  Created
+   *    v0.2    Add optional base argument
+   *    v0.3    Handle Array input
+   *    v0.5    Handle Matrix input
+   *    v0.16   Handle BigNumber input
+   *    v0.21   Support negative BigNumbers
+   *    v11     Drop Array/Matrix support in favor of explicit map of
+   *            the scalar log function, to avoid confusion with the log
+   *            of a matrix
+   *    v14     Allow value and base to be Fractions, when the log is rational
+   *
    * @param {number | BigNumber | Fraction | Complex} x
    *            Value for which to calculate the logarithm.
    * @param {number | BigNumber | Fraction | Complex} [base=e]
diff --git a/src/function/matrix/map.js b/src/function/matrix/map.js
@@ -41,6 +41,12 @@ export const createMap = /* #__PURE__ */ factory(name, dependencies, ({ typed })
    *    // It can also be called with 2N + 1 arguments: for N arrays
    *    //    callback(value1, value2, index, BroadcastedArray1, BroadcastedArray2)
    *
+   * History:
+   *
+   *    v0.13  Created
+   *    v1.1   Clone the indices on each callback in case callback mutates
+   *    v13.1  Support multiple inputs to the callback
+   *
    * See also:
    *
    *    filter, forEach, sort
diff --git a/src/function/relational/compare.js b/src/function/relational/compare.js
@@ -58,6 +58,12 @@ export const createCompare = /* #__PURE__ */ factory(name, dependencies, ({ type
    *
    *    equal, unequal, smaller, smallerEq, larger, largerEq, compareNatural, compareText
    *
+   * History:
+   *
+   *    v0.19  Created
+   *    v4     Changed to compare strings by numerical value
+   *    v13    Change to use separate relative and absolute tolerances
+   *
    * @param  {number | BigNumber | bigint | Fraction | Unit | string | Array | Matrix} x First value to compare
    * @param  {number | BigNumber | bigint | Fraction | Unit | string | Array | Matrix} y Second value to compare
    * @return {number | BigNumber | bigint | Fraction | Array | Matrix} Returns the result of the comparison:
diff --git a/src/function/string/format.js b/src/function/string/format.js
@@ -119,6 +119,15 @@ export const createFormat = /* #__PURE__ */ factory(name, dependencies, ({ typed
    *
    *    print
    *
+   * History:
+   *
+   *    v0.4     Created
+   *    v0.7     Round to a consistent number of digits (rather than decimals)
+   *    v0.15    Added multiple number notations and configurable precision
+   *    v3       Added support for JSON objects
+   *    v9       Added binary, hexadecimal, and octal notations
+   *    v10.4.2  Add `truncate` option
+   *
    * @param {*} value                               Value to be stringified
    * @param {Object | Function | number} [options]  Formatting options
    * @return {string} The formatted value
diff --git a/src/function/utils/numeric.js b/src/function/utils/numeric.js
@@ -47,6 +47,12 @@ export const createNumeric = /* #__PURE__ */ factory(name, dependencies, ({ numb
    *
    *    number, fraction, bignumber, bigint, string, format
    *
+   * History:
+   *
+   *    v6       Created
+   *    v13      Added `bigint` support
+   *    v14.2.1  Prefer mathjs `bigint()` to built-in `BigInt()`
+   *
    * @param {string | number | BigNumber | bigint | Fraction } value
    *              A numeric value or a string containing a numeric value
    * @param {string} outputType
diff --git a/src/type/bigint.js b/src/type/bigint.js
@@ -24,6 +24,11 @@ export const createBigint = /* #__PURE__ */ factory(name, dependencies, ({ typed
    *
    *    number, bignumber, boolean, complex, index, matrix, string, unit
    *
+   * History:
+   *
+   *    v13      Created
+   *    v14.2.1  Added conversion options
+   *
    * @param {string | number | BigNumber | bigint | Fraction | boolean | Array | Matrix | null} [value]  Value to be converted
    * @return {bigint | Array | Matrix} The created bigint
    */
diff --git a/src/type/boolean.js b/src/type/boolean.js
@@ -29,6 +29,12 @@ export const createBoolean = /* #__PURE__ */ factory(name, dependencies, ({ type
    *
    *    bignumber, complex, index, matrix, string, unit
    *
+   * History:
+   *
+   *    v0.11    Created
+   *    v0.16    Added conversion from BigNumber
+   *    v14.2.1  Added conversion from bigint
+   *
    * @param {string | number | boolean | Array | Matrix | null} value  A value of any type
    * @return {boolean | Array | Matrix} The boolean value
    */
diff --git a/src/type/complex/function/complex.js b/src/type/complex/function/complex.js
@@ -39,6 +39,12 @@ export const createComplex = /* #__PURE__ */ factory(name, dependencies, ({ type
    *
    *    bignumber, boolean, index, matrix, number, string, unit
    *
+   * History:
+   *
+   *    v0.5   Created
+   *    v0.16  Added conversion from BigNumber
+   *    v6     Added conversion from Fraction
+   *
    * @param {* | Array | Matrix} [args]
    *            Arguments specifying the real and imaginary part of the complex number
    * @return {Complex | Array | Matrix} Returns a complex value
diff --git a/src/type/fraction/function/fraction.js b/src/type/fraction/function/fraction.js
@@ -37,6 +37,14 @@ export const createFraction = /* #__PURE__ */ factory(name, dependencies, ({ typ
    *
    *    bignumber, number, string, unit
    *
+   * History:
+   *
+   *    v2     Created
+   *    v3     Added conversion from BigNumber
+   *    v11.8  Added conversion from Unit
+   *    v13    Added conversion from bigint
+   *    v14    Move to bigint-based fraction.js@5; construct from two bigints
+   *
    * @param {number | string | Fraction | BigNumber | bigint | Unit | Array | Matrix} [args]
    *            Arguments specifying the value, or numerator and denominator of
    *            the fraction
diff --git a/src/type/matrix/function/index.js b/src/type/matrix/function/index.js
@@ -37,6 +37,14 @@ export const createIndex = /* #__PURE__ */ factory(name, dependencies, ({ typed,
    *
    *    bignumber, boolean, complex, matrix, number, string, unit
    *
+   * History:
+   *
+   *    v?      Created
+   *    v2      Dropped support for `[start, end, step]` arguments in favor
+   *            of lists of arbitrary values; added support for Range
+   *            objects.
+   *    v11.10  Added support for arrays of booleans as indices.
+   *
    * @param {...*} ranges   Zero or more ranges or numbers.
    * @return {Index}        Returns the created index
    */
diff --git a/src/type/matrix/function/matrix.js b/src/type/matrix/function/matrix.js
@@ -31,6 +31,12 @@ export const createMatrix = /* #__PURE__ */ factory(name, dependencies, ({ typed
    *
    *    bignumber, boolean, complex, index, number, string, unit, sparse
    *
+   * History:
+   *
+   *    v0.5  Created
+   *    v1.5  Support dense or sparse Matrix types; allow construction
+   *          from string, Array, or another Matrix.
+   *
    * @param {Array | Matrix} [data]    A multi dimensional array
    * @param {string} [format]          The Matrix storage format, either `'dense'` or `'sparse'`
    * @param {string} [datatype]        Type of the values
diff --git a/src/type/matrix/function/sparse.js b/src/type/matrix/function/sparse.js
@@ -33,6 +33,10 @@ export const createSparse = /* #__PURE__ */ factory(name, dependencies, ({ typed
    *
    *    bignumber, boolean, complex, index, number, string, unit, matrix
    *
+   * History:
+   *
+   *    v1.5  Created
+   *
    * @param {Array | Matrix} [data]    A two dimensional array
    *
    * @return {Matrix} The created matrix
diff --git a/src/type/string.js b/src/type/string.js
@@ -28,6 +28,10 @@ export const createString = /* #__PURE__ */ factory(name, dependencies, ({ typed
    *
    *    bignumber, boolean, complex, index, matrix, number, unit
    *
+   * History:
+   *
+   *    v0.9  Created
+   *
    * @param {* | Array | Matrix | null} [value]  A value to convert to a string
    * @return {string | Array | Matrix} The created string
    */
diff --git a/src/type/unit/function/unit.js b/src/type/unit/function/unit.js
@@ -29,6 +29,14 @@ export const createUnitFunction = /* #__PURE__ */ factory(name, dependencies, ({
    *
    *    bignumber, boolean, complex, index, matrix, number, string, createUnit
    *
+   * History:
+   *
+   *    v0.5   Created
+   *    v0.16  Support conversion from BigNumber
+   *    v2.5   Support BigNumber and Fraction values in units
+   *    v2.6   Support Complex values in units
+   *    v11.1  Allow the type of unit to be specifed by a unit (not just string)
+   *
    * @param {* | Array | Matrix} args   A number and unit.
    * @return {Unit | Array | Matrix}    The created unit
    */
diff --git a/test/node-tests/doc.test.js b/test/node-tests/doc.test.js
@@ -354,24 +354,75 @@ const knownUndocumented = new Set([
   'wienDisplacement'
 ])
 
+// Functions yet to obtain individual History listings:
+const knownNoHistory = new Set([
+  'config', 'typed', 'derivative', 'leafCount', 'lsolve', 'lsolveAll', 'lup',
+  'lusolve', 'lyap', 'qr', 'rationalize', 'resolve', 'schur', 'simplify',
+  'simplifyConstant', 'simplifyCore', 'slu', 'sylvester', 'symbolicEqual',
+  'usolve', 'usolveAll', 'abs', 'add', 'cbrt', 'ceil', 'cube', 'divide',
+  'dotDivide', 'dotMultiply', 'dotPow', 'exp', 'expm', 'expm1', 'fix', 'floor',
+  'gcd', 'hypot', 'invmod', 'lcm', 'log10', 'log1p', 'log2', 'mod', 'multiply',
+  'norm', 'nthRoot', 'nthRoots', 'pow', 'round', 'sign', 'sqrt', 'sqrtm',
+  'square', 'subtract', 'unaryMinus', 'unaryPlus', 'xgcd', 'bitAnd', 'bitNot',
+  'bitOr', 'bitXor', 'leftShift', 'rightArithShift', 'rightLogShift',
+  'bellNumbers', 'catalan', 'composition', 'stirlingS2', 'arg', 'conj', 'im',
+  're', 'compile', 'evaluate', 'help', 'parser', 'distance', 'intersect',
+  'and', 'not', 'nullish', 'or', 'xor', 'column', 'concat', 'count', 'cross',
+  'ctranspose', 'det', 'diag', 'diff', 'dot', 'eigs', 'fft', 'filter',
+  'flatten', 'forEach', 'getMatrixDataType', 'identity', 'ifft', 'inv', 'kron',
+  'mapSlices', 'matrixFromColumns', 'matrixFromFunction', 'matrixFromRows',
+  'ones', 'partitionSelect', 'pinv', 'range', 'reshape', 'resize', 'rotate',
+  'rotationMatrix', 'row', 'size', 'sort', 'squeeze', 'subset', 'trace',
+  'transpose', 'zeros', 'solveODE', 'bernoulli', 'combinations',
+  'combinationsWithRep', 'factorial', 'gamma', 'kldivergence', 'lgamma',
+  'multinomial', 'permutations', 'pickRandom', 'random', 'randomInt',
+  'compareNatural', 'compareText', 'deepEqual', 'equal', 'equalText', 'larger',
+  'largerEq', 'smaller', 'smallerEq', 'unequal', 'setCartesian',
+  'setDifference', 'setDistinct', 'setIntersect', 'setIsSubset',
+  'setMultiplicity', 'setPowerset', 'setSize', 'setSymDifference', 'setUnion',
+  'freqz', 'zpk2tf', 'erf', 'zeta', 'corr', 'cumsum', 'mad', 'max', 'mean',
+  'median', 'min', 'mode', 'prod', 'quantileSeq', 'std', 'sum', 'variance',
+  'acos', 'acosh', 'acot', 'acoth', 'acsc', 'acsch', 'asec', 'asech', 'asin',
+  'asinh', 'atan', 'atan2', 'atanh', 'cos', 'cosh', 'cot', 'coth', 'csc',
+  'csch', 'sec', 'sech', 'sin', 'sinh', 'tan', 'tanh', 'to', 'toBest', 'bin',
+  'clone', 'hasNumericValue', 'hex', 'isBounded', 'isFinite', 'isInteger',
+  'isNaN', 'isNegative', 'isNumeric', 'isPositive', 'isPrime', 'isZero',
+  'oct', 'print', 'typeOf', 'bignumber', 'chain', 'number', 'splitUnit'
+])
+
 describe('Testing examples from (jsdoc) comments', function () {
   const allNames = Object.keys(math)
   const srcPath = path.resolve(__dirname, '../../src') + '/'
   const allDocs = collectDocs(allNames, srcPath)
 
+  const ignoreInternals = name => name.substr(0, 1) === '_' ||
+        name.substr(-12) === 'Dependencies' ||
+        name.substr(0, 6) === 'create'
+
   it("should cover all names (but doesn't yet)", function () {
     const documented = new Set(Object.keys(allDocs))
     const badUndocumented = allNames.filter(name => {
       return !(documented.has(name) ||
                OKundocumented.has(name) ||
                knownUndocumented.has(name) ||
-               name.substr(0, 1) === '_' ||
-               name.substr(-12) === 'Dependencies' ||
-               name.substr(0, 6) === 'create'
+               ignoreInternals(name)
       )
     })
     assert.deepEqual(badUndocumented, [])
   })
+
+  it("should have history for all functions (but doesn't yet)", function () {
+    const badNoHistory = Object.keys(allDocs).filter(name => {
+      if (ignoreInternals(name)) return false
+      const doc = allDocs[name]
+      const history = doc.doc?.history
+      if (knownNoHistory.has(name)) return false
+      if (history && Object.keys(history).length) return false
+      return true
+    })
+    assert.deepEqual(badNoHistory, [])
+  })
+
   const byCategory = {}
   for (const fun of Object.values(allDocs)) {
     if (!(fun.category in byCategory)) {
diff --git a/tools/docgenerator.js b/tools/docgenerator.js
@@ -191,6 +191,29 @@ export function generateDoc (name, code) {
     return false
   }
 
+  function parseHistory () {
+    if (/^history/i.test(line)) {
+      next()
+      skipEmptyLines()
+
+      while (exists() && !empty()) {
+        let [_all, indent, version, entry] = line.match(/^(\s*)(\S*)\s+(.*)$/)
+        const moreIndent = indent + ' '
+        next()
+        while (exists() && !empty() && line.startsWith(moreIndent)) {
+          entry += ' ' + line.trim()
+          next()
+        }
+        doc.history[version] = entry
+      }
+
+      skipEmptyLines()
+
+      return true
+    }
+    return false
+  }
+
   function parseExamples () {
     if (/^example/i.test(line)) {
       next()
@@ -338,6 +361,7 @@ export function generateDoc (name, code) {
     description: '',
     syntax: [],
     where: [],
+    history: {},
     examples: [],
     seeAlso: [],
     parameters: [],
@@ -354,6 +378,7 @@ export function generateDoc (name, code) {
 
     const handled = parseSyntax() ||
         parseWhere() ||
+        parseHistory() ||
         parseExamples() ||
         parseSeeAlso() ||
         parseParameters() ||
@@ -518,6 +543,15 @@ export function generateMarkdown (doc, functions) {
         '\n'
   }
 
+  if (Object.keys(doc.history).length > 0) {
+    text += '## History\n\n' +
+      'Version | Comment\n' +
+      '------- | -------\n'
+    for (const version in doc.history) {
+      text += `${version} | ${doc.history[version]}\n`
+    }
+  }
+
   return text
 }
 

Original file line number	Diff line number	Diff line change
`@@ -56,6 +56,13 @@ export function importFactory (typed, load, math, importedFactories) {`
`56`	`56`	`*`
`57`	`57`	`* math.fibonacci(7) // returns 13`
`58`	`58`	`*`
	`59`	`+ * History:`
	`60`	`+ *`
	`61`	`+ * v0.2 Created`
	`62`	`+ * v0.7 Changed second parameter to an options object`
	`63`	`+ * v2 Dropped support for direct import of a module by name`
	`64`	`+ * v14.2 Add facility for specifying the former name of an import`
	`65`	`+ *`
`59`	`66`	`* @param {Object \| Array} functions Object with functions to be imported.`
`60`	`67`	`* @param {Object} [options] Import options.`
`61`	`68`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -41,6 +41,12 @@ export const createMap = /* #__PURE__ */ factory(name, dependencies, ({ typed })`
`41`	`41`	`* // It can also be called with 2N + 1 arguments: for N arrays`
`42`	`42`	`* // callback(value1, value2, index, BroadcastedArray1, BroadcastedArray2)`
`43`	`43`	`*`
	`44`	`+ * History:`
	`45`	`+ *`
	`46`	`+ * v0.13 Created`
	`47`	`+ * v1.1 Clone the indices on each callback in case callback mutates`
	`48`	`+ * v13.1 Support multiple inputs to the callback`
	`49`	`+ *`
`44`	`50`	`* See also:`
`45`	`51`	`*`
`46`	`52`	`* filter, forEach, sort`
Original file line number	Diff line number	Diff line change
`@@ -58,6 +58,12 @@ export const createCompare = /* #__PURE__ */ factory(name, dependencies, ({ type`
`58`	`58`	`*`
`59`	`59`	`* equal, unequal, smaller, smallerEq, larger, largerEq, compareNatural, compareText`
`60`	`60`	`*`
	`61`	`+ * History:`
	`62`	`+ *`
	`63`	`+ * v0.19 Created`
	`64`	`+ * v4 Changed to compare strings by numerical value`
	`65`	`+ * v13 Change to use separate relative and absolute tolerances`
	`66`	`+ *`
`61`	`67`	`* @param {number \| BigNumber \| bigint \| Fraction \| Unit \| string \| Array \| Matrix} x First value to compare`
`62`	`68`	`* @param {number \| BigNumber \| bigint \| Fraction \| Unit \| string \| Array \| Matrix} y Second value to compare`
`63`	`69`	`* @return {number \| BigNumber \| bigint \| Fraction \| Array \| Matrix} Returns the result of the comparison:`
Original file line number	Diff line number	Diff line change
`@@ -47,6 +47,12 @@ export const createNumeric = /* #__PURE__ */ factory(name, dependencies, ({ numb`
`47`	`47`	`*`
`48`	`48`	`* number, fraction, bignumber, bigint, string, format`
`49`	`49`	`*`
	`50`	`+ * History:`
	`51`	`+ *`
	`52`	`+ * v6 Created`
	`53`	+ * v13 Added `bigint` support
	`54`	+ * v14.2.1 Prefer mathjs `bigint()` to built-in `BigInt()`
	`55`	`+ *`
`50`	`56`	`* @param {string \| number \| BigNumber \| bigint \| Fraction } value`
`51`	`57`	`* A numeric value or a string containing a numeric value`
`52`	`58`	`* @param {string} outputType`
Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,11 @@ export const createBigint = /* #__PURE__ */ factory(name, dependencies, ({ typed`
`24`	`24`	`*`
`25`	`25`	`* number, bignumber, boolean, complex, index, matrix, string, unit`
`26`	`26`	`*`
	`27`	`+ * History:`
	`28`	`+ *`
	`29`	`+ * v13 Created`
	`30`	`+ * v14.2.1 Added conversion options`
	`31`	`+ *`
`27`	`32`	`* @param {string \| number \| BigNumber \| bigint \| Fraction \| boolean \| Array \| Matrix \| null} [value] Value to be converted`
`28`	`33`	`* @return {bigint \| Array \| Matrix} The created bigint`
`29`	`34`	`*/`