fix: Type declarations for rounding functions (#2539)

This is a sequel to #2531. Uniformizes the signatures of ceil, fix, floor,
  and round, and updates the TypeScript declarations to match. Adds the
  optional "number of places" argument to the chain versions of ceil, fix,
  and floor. Adds TypeScript tests for all rounding functions.

  Also corrects the TypeScript declaration for `bignumber()` and introduces
  a couple more common abbreviations for TypeScript types.

  Fixes the number-only implementations of floor, ceil, fix, and nthRoot
  to match the full implementation behavior on numbers, and tests this for
  floor.

  Includes some minor documentation updates and additional unit tests for
  the rounding functions.

  Reverts inclusion in AUTHORS of incorrect email for one contributor,
  that occurred in #2531.

  Resolves #2526.
  Resolves #2529.

Author: gwhitney

AUTHORS

@@ -179,7 +179,6 @@ Alfonso Valenciana <[email protected]>
 David <[email protected]>
 Glen Whitney <[email protected]>
 Divya Yeruva <[email protected]>
-Yeruva <[email protected]>
 Eternal-Rise <[email protected]>
 yifanwww <[email protected]>
 NattapongSiri <[email protected]>

docs/datatypes/matrices.md

@@ -342,6 +342,23 @@ const m1 = math.matrix([[0, 1], [0, 0]], 'sparse')
 const m2 = math.identity(1000, 1000, 'sparse')
 ```
 
+You can also coerce an array or matrix into sparse storage format with the
+`sparse` function.
+```js
+const md = math.matrix([[0, 1], [0,0]])  // dense
+const ms = math.sparse(md)               // sparse
+```
+
+Caution: `sparse` called on a JavaScript array of _n_ plain numbers produces
+a matrix with one column and _n_ rows -- in contrast to `matrix`, which
+produces a 1-dimensional matrix object with _n_ entries, i.e., a vector
+(_not_ a 1 by _n_ "row vector" nor an _n_ by 1 "column vector", but just a plain
+vector of length _n_).
+```js
+const mv = math.matrix([0, 0, 1])  // Has size [3]
+const mc = math.sparse([0, 0, 1])  // A "column vector," has size [3, 1]
+```
+
 ## API
 
 All relevant functions in math.js support Matrices and Arrays. Functions like `math.add` and `math.subtract`, `math.sqrt` handle matrices element wise. There is a set of functions specifically for creating or manipulating matrices, such as:

src/factoriesNumber.js

@@ -20,7 +20,6 @@ import {
   bitOrNumber,
   bitXorNumber,
   cbrtNumber,
-  ceilNumber,
   combinationsNumber,
   coshNumber,
   cosNumber,
@@ -32,8 +31,6 @@ import {
   divideNumber,
   expm1Number,
   expNumber,
-  fixNumber,
-  floorNumber,
   gammaNumber,
   gcdNumber,
   isIntegerNumber,
@@ -52,10 +49,12 @@ import {
   multiplyNumber,
   normNumber,
   notNumber,
+  nthRootNumber,
   orNumber,
   powNumber,
   rightArithShiftNumber,
   rightLogShiftNumber,
+  roundNumber,
   sechNumber,
   secNumber,
   signNumber,
@@ -102,28 +101,30 @@ export const createUnaryPlus = /* #__PURE__ */ createNumberFactory('unaryPlus',
 export const createAbs = /* #__PURE__ */ createNumberFactory('abs', absNumber)
 export const createAddScalar = /* #__PURE__ */ createNumberFactory('addScalar', addNumber)
 export const createCbrt = /* #__PURE__ */ createNumberFactory('cbrt', cbrtNumber)
-export const createCeil = /* #__PURE__ */ createNumberFactory('ceil', ceilNumber)
+export { createCeilNumber as createCeil } from './function/arithmetic/ceil.js'
 export const createCube = /* #__PURE__ */ createNumberFactory('cube', cubeNumber)
 export const createExp = /* #__PURE__ */ createNumberFactory('exp', expNumber)
 export const createExpm1 = /* #__PURE__ */ createNumberFactory('expm1', expm1Number)
-export const createFix = /* #__PURE__ */ createNumberFactory('fix', fixNumber)
-export const createFloor = /* #__PURE__ */ createNumberFactory('floor', floorNumber)
+export { createFixNumber as createFix } from './function/arithmetic/fix.js'
+export { createFloorNumber as createFloor } from './function/arithmetic/floor.js'
 export const createGcd = /* #__PURE__ */ createNumberFactory('gcd', gcdNumber)
 export const createLcm = /* #__PURE__ */ createNumberFactory('lcm', lcmNumber)
 export const createLog10 = /* #__PURE__ */ createNumberFactory('log10', log10Number)
 export const createLog2 = /* #__PURE__ */ createNumberFactory('log2', log2Number)
 export const createMod = /* #__PURE__ */ createNumberFactory('mod', modNumber)
 export const createMultiplyScalar = /* #__PURE__ */ createNumberFactory('multiplyScalar', multiplyNumber)
 export const createMultiply = /* #__PURE__ */ createNumberFactory('multiply', multiplyNumber)
-export { createNthRootNumber as createNthRoot } from './function/arithmetic/nthRoot.js'
+export const createNthRoot = /* #__PURE__ */
+  createNumberOptionalSecondArgFactory('nthRoot', nthRootNumber)
 export const createSign = /* #__PURE__ */ createNumberFactory('sign', signNumber)
 export const createSqrt = /* #__PURE__ */ createNumberFactory('sqrt', sqrtNumber)
 export const createSquare = /* #__PURE__ */ createNumberFactory('square', squareNumber)
 export const createSubtract = /* #__PURE__ */ createNumberFactory('subtract', subtractNumber)
 export const createXgcd = /* #__PURE__ */ createNumberFactory('xgcd', xgcdNumber)
 export const createDivideScalar = /* #__PURE__ */ createNumberFactory('divideScalar', divideNumber)
 export const createPow = /* #__PURE__ */ createNumberFactory('pow', powNumber)
-export { createRoundNumber as createRound } from './function/arithmetic/round.js'
+export const createRound = /* #__PURE__ */
+  createNumberOptionalSecondArgFactory('round', roundNumber)
 export const createLog = /* #__PURE__ */
   createNumberOptionalSecondArgFactory('log', logNumber)
 export const createLog1p = /* #__PURE__ */ createNumberFactory('log1p', log1pNumber)

src/function/arithmetic/ceil.js

@@ -3,17 +3,44 @@ import { factory } from '../../utils/factory.js'
 import { deepMap } from '../../utils/collection.js'
 import { nearlyEqual } from '../../utils/number.js'
 import { nearlyEqual as bigNearlyEqual } from '../../utils/bignumber/nearlyEqual.js'
-import { ceilNumber } from '../../plain/number/index.js'
 import { createAlgorithm11 } from '../../type/matrix/utils/algorithm11.js'
+import { createAlgorithm12 } from '../../type/matrix/utils/algorithm12.js'
 import { createAlgorithm14 } from '../../type/matrix/utils/algorithm14.js'
 
 const name = 'ceil'
-const dependencies = ['typed', 'config', 'round', 'matrix', 'equalScalar']
+const dependencies = ['typed', 'config', 'round', 'matrix', 'equalScalar', 'zeros', 'DenseMatrix']
 
-export const createCeil = /* #__PURE__ */ factory(name, dependencies, ({ typed, config, round, matrix, equalScalar }) => {
+export const createCeilNumber = /* #__PURE__ */ factory(
+  name, ['typed', 'config', 'round'], ({ typed, config, round }) => {
+    return typed(name, {
+      number: function (x) {
+        if (nearlyEqual(x, round(x), config.epsilon)) {
+          return round(x)
+        } else {
+          return Math.ceil(x)
+        }
+      },
+
+      'number, number': function (x, n) {
+        if (nearlyEqual(x, round(x, n), config.epsilon)) {
+          return round(x, n)
+        } else {
+          let [number, exponent] = `${x}e`.split('e')
+          const result = Math.ceil(Number(`${number}e${Number(exponent) + n}`));
+          [number, exponent] = `${result}e`.split('e')
+          return Number(`${number}e${Number(exponent) - n}`)
+        }
+      }
+    })
+  }
+)
+
+export const createCeil = /* #__PURE__ */ factory(name, dependencies, ({ typed, config, round, matrix, equalScalar, zeros, DenseMatrix }) => {
   const algorithm11 = createAlgorithm11({ typed, equalScalar })
+  const algorithm12 = createAlgorithm12({ typed, DenseMatrix })
   const algorithm14 = createAlgorithm14({ typed })
 
+  const ceilNumber = createCeilNumber({ typed, config, round })
   /**
    * Round a value towards plus infinity
    * If `x` is complex, both real and imaginary part are rounded towards plus infinity.
@@ -52,24 +79,8 @@ export const createCeil = /* #__PURE__ */ factory(name, dependencies, ({ typed,
    * @return {number | BigNumber | Fraction | Complex | Array | Matrix} Rounded value
    */
   return typed('ceil', {
-    number: function (x) {
-      if (nearlyEqual(x, round(x), config.epsilon)) {
-        return round(x)
-      } else {
-        return ceilNumber(x)
-      }
-    },
-
-    'number, number': function (x, n) {
-      if (nearlyEqual(x, round(x, n), config.epsilon)) {
-        return round(x, n)
-      } else {
-        let [number, exponent] = `${x}e`.split('e')
-        const result = Math.ceil(Number(`${number}e${Number(exponent) + n}`));
-        [number, exponent] = `${result}e`.split('e')
-        return Number(`${number}e${Number(exponent) - n}`)
-      }
-    },
+    number: ceilNumber.signatures.number,
+    'number,number': ceilNumber.signatures['number,number'],
 
     Complex: function (x) {
       return x.ceil()
@@ -79,6 +90,10 @@ export const createCeil = /* #__PURE__ */ factory(name, dependencies, ({ typed,
       return x.ceil(n)
     },
 
+    'Complex, BigNumber': function (x, n) {
+      return x.ceil(n.toNumber())
+    },
+
     BigNumber: function (x) {
       if (bigNearlyEqual(x, round(x), config.epsilon)) {
         return round(x)
@@ -103,12 +118,16 @@ export const createCeil = /* #__PURE__ */ factory(name, dependencies, ({ typed,
       return x.ceil(n)
     },
 
+    'Fraction, BigNumber': function (x, n) {
+      return x.ceil(n.toNumber())
+    },
+
     'Array | Matrix': function (x) {
       // deep map collection, skip zeros since ceil(0) = 0
       return deepMap(x, this, true)
     },
 
-    'Array | Matrix, number': function (x, n) {
+    'Array, number | BigNumber': function (x, n) {
       // deep map collection, skip zeros since ceil(0) = 0
       return deepMap(x, i => this(i, n), true)
     },
@@ -121,9 +140,17 @@ export const createCeil = /* #__PURE__ */ factory(name, dependencies, ({ typed,
       return algorithm14(x, y, this, false)
     },
 
-    'number | Complex | BigNumber, Array': function (x, y) {
+    'number | Complex | Fraction | BigNumber, Array': function (x, y) {
       // use matrix implementation
       return algorithm14(matrix(y), x, this, true).valueOf()
+    },
+
+    'number | Complex | Fraction | BigNumber, Matrix': function (x, y) {
+      if (equalScalar(x, 0)) return zeros(y.size(), y.storage())
+      if (y.storage() === 'dense') {
+        return algorithm14(y, x, this, true)
+      }
+      return algorithm12(y, x, this, true)
     }
   })
 })

src/function/arithmetic/fix.js

@@ -1,19 +1,38 @@
 import { factory } from '../../utils/factory.js'
 import { deepMap } from '../../utils/collection.js'
+import { createAlgorithm12 } from '../../type/matrix/utils/algorithm12.js'
 import { createAlgorithm14 } from '../../type/matrix/utils/algorithm14.js'
 
 const name = 'fix'
-const dependencies = ['typed', 'Complex', 'matrix', 'ceil', 'floor']
+const dependencies = ['typed', 'Complex', 'matrix', 'ceil', 'floor', 'equalScalar', 'zeros', 'DenseMatrix']
 
-export const createFix = /* #__PURE__ */ factory(name, dependencies, ({ typed, Complex, matrix, ceil, floor }) => {
+export const createFixNumber = /* #__PURE__ */ factory(
+  name, ['typed', 'ceil', 'floor'], ({ typed, ceil, floor }) => {
+    return typed(name, {
+      number: function (x) {
+        return (x > 0) ? floor(x) : ceil(x)
+      },
+
+      'number, number': function (x, n) {
+        return (x > 0) ? floor(x, n) : ceil(x, n)
+      }
+    })
+  }
+)
+
+export const createFix = /* #__PURE__ */ factory(name, dependencies, ({ typed, Complex, matrix, ceil, floor, equalScalar, zeros, DenseMatrix }) => {
+  const algorithm12 = createAlgorithm12({ typed, DenseMatrix })
   const algorithm14 = createAlgorithm14({ typed })
+
+  const fixNumber = createFixNumber({ typed, ceil, floor })
   /**
    * Round a value towards zero.
    * For matrices, the function is evaluated element wise.
    *
    * Syntax:
    *
    *    math.fix(x)
+   *    math.fix(x,n)
    *
    * Examples:
    *
@@ -43,13 +62,8 @@ export const createFix = /* #__PURE__ */ factory(name, dependencies, ({ typed, C
    * @return {number | BigNumber | Fraction | Complex | Array | Matrix}     Rounded value
    */
   return typed('fix', {
-    number: function (x) {
-      return (x > 0) ? floor(x) : ceil(x)
-    },
-
-    'number, number | BigNumber': function (x, n) {
-      return (x > 0) ? floor(x, n) : ceil(x, n)
-    },
+    number: fixNumber.signatures.number,
+    'number, number | BigNumber': fixNumber.signatures['number,number'],
 
     Complex: function (x) {
       return new Complex(
@@ -58,7 +72,15 @@ export const createFix = /* #__PURE__ */ factory(name, dependencies, ({ typed, C
       )
     },
 
-    'Complex, number | BigNumber': function (x, n) {
+    'Complex, number': function (x, n) {
+      return new Complex(
+        (x.re > 0) ? floor(x.re, n) : ceil(x.re, n),
+        (x.im > 0) ? floor(x.im, n) : ceil(x.im, n)
+      )
+    },
+
+    'Complex, BigNumber': function (x, bn) {
+      const n = bn.toNumber()
       return new Complex(
         (x.re > 0) ? floor(x.re, n) : ceil(x.re, n),
         (x.im > 0) ? floor(x.im, n) : ceil(x.im, n)
@@ -78,7 +100,7 @@ export const createFix = /* #__PURE__ */ factory(name, dependencies, ({ typed, C
     },
 
     'Fraction, number | BigNumber': function (x, n) {
-      return x.s < 0 ? x.ceil(n) : x.floor(n)
+      return x.s < 0 ? ceil(x, n) : floor(x, n)
     },
 
     'Array | Matrix': function (x) {
@@ -91,9 +113,17 @@ export const createFix = /* #__PURE__ */ factory(name, dependencies, ({ typed, C
       return deepMap(x, i => this(i, n), true)
     },
 
-    'number | Complex | BigNumber, Array': function (x, y) {
+    'number | Complex | Fraction | BigNumber, Array': function (x, y) {
       // use matrix implementation
       return algorithm14(matrix(y), x, this, true).valueOf()
+    },
+
+    'number | Complex | Fraction | BigNumber, Matrix': function (x, y) {
+      if (equalScalar(x, 0)) return zeros(y.size(), y.storage())
+      if (y.storage() === 'dense') {
+        return algorithm14(y, x, this, true)
+      }
+      return algorithm12(y, x, this, true)
     }
   })
 })