feat: Allow single number or an Array of index specifications in subset()

  * A single number is now interpreted as the entire "layer" at that position;
    adds `layer` method to Matrix for efficient support of this convention.
  * An array is just passed to index
  * A string form of a Range is now allowed in the index; the lower and upper
    limits may be elided, allowing `':'` as a wildcard for an entire dimension.
  * Also removes unnecessary dependence of set functions on Index.
  * Now passes all doc example testing for `subset`

Author: gwhitney

src/expression/transform/subset.transform.js

@@ -1,20 +1,19 @@
 import { factory } from '../../utils/factory.js'
 import { errorTransform } from './utils/errorTransform.js'
-import { createSubset } from '../../function/matrix/subset.js'
+import { createSubset, dependencies } from '../../function/matrix/subset.js'
 
 const name = 'subset'
-const dependencies = ['typed', 'matrix', 'zeros', 'add']
 
-export const createSubsetTransform = /* #__PURE__ */ factory(name, dependencies, ({ typed, matrix, zeros, add }) => {
-  const subset = createSubset({ typed, matrix, zeros, add })
+export const createSubsetTransform = /* #__PURE__ */ factory(name, dependencies, provided => {
+  const subset = createSubset(provided)
 
   /**
    * Attach a transform function to math.subset
    * Adds a property transform containing the transform function.
    *
    * This transform creates a range which includes the end value
    */
-  return typed('subset', {
+  return provided.typed('subset', {
     '...any': function (args) {
       try {
         return subset.apply(null, args)

src/function/matrix/subset.js

@@ -6,12 +6,35 @@ import { DimensionError } from '../../error/DimensionError.js'
 import { factory } from '../../utils/factory.js'
 
 const name = 'subset'
-const dependencies = ['typed', 'matrix', 'zeros', 'add']
+export const dependencies = ['typed', 'matrix', 'zeros', 'add', 'index', 'size']
 
-export const createSubset = /* #__PURE__ */ factory(name, dependencies, ({ typed, matrix, zeros, add }) => {
+export const createSubset = /* #__PURE__ */ factory(name, dependencies, ({ typed, matrix, zeros, add, index, size }) => {
   /**
    * Get or set a subset of a matrix or string.
    *
+   * The second argument should be a specification of the desired subset of
+   * the first argument. Therefore, the second argument is typically an Index
+   * object produced by the `index` function, which see (in short, for each
+   * dimension of the matrix, the Index specifies one position or a list or
+   * range of positions to include in the subset).
+   *
+   * For convenience, the second argument may be simply a number n, in which
+   * case the subset is the entire section of one dimension lower than the
+   * given matrix, at position n. In other words, it corresponds to the
+   * entry of a vector at position n, or the row of a 2D matrix at position
+   * n, etc.
+   *
+   * Furthermore, it can also be an array of appropriate arguments to the
+   * `index` function, in which case it will be passed to the `index` function
+   * for you. Beware, though: in the case of a 1d vector v,
+   * `math.subset(v, [2, 3])` will not therefore return the elements at
+   * positions 2 and 3, because passing those arguments to `index` would
+   * attempt to index the first dimension of v by and its nonexistent second
+   * dimension by 3. You can call `math.subset(v, [[2, 3]])` to obtain the
+   * elements at positions 2 and 3, because now the inner `[2, 3]` will be
+   * interpreted as the list of positions with which to index into the first
+   * dimension.
+   *
    * Syntax:
    *     math.subset(value, index)                                // retrieve a subset
    *     math.subset(value, index, replacement [, defaultValue])  // replace a subset
@@ -20,23 +43,29 @@ export const createSubset = /* #__PURE__ */ factory(name, dependencies, ({ typed
    *
    *     // get a subset
    *     const d = [[1, 2], [3, 4]]
-   *     math.subset(d, math.index(1, 0))             // returns 3
-   *     math.subset(d, math.index([0, 1], [1]))        // returns [[2], [4]]
-   *     math.subset(d, math.index([false, true], [0])) // returns [[3]]
+   *     math.subset(d, math.index(1, 0))               // returns 3 ...
+   *     math.subset(d, [1, 0])                         // returns 3 ...
+   *     math.subset(d, math.index([0, 1], [1]))        // Array [[2], [4]] ...
+   *     math.subset(d, [[0, 1], [1]])                  // Array [[2], [4]] ...
+   *     math.subset(d, math.index([false, true], [0])) // Array [[3]] ...
+   *     math.subset(d, [[false, true], 0])             // Array [3] ...
+   *     math.subset(d, 1)                              // Array [3, 4]
    *
    *     // replace a subset
    *     const e = []
-   *     const f = math.subset(e, math.index(0, [0, 2]), [5, 6])  // f = [[5, 0, 6]]
-   *     const g = math.subset(f, math.index(1, 1), 7, 0)         // g = [[5, 0, 6], [0, 7, 0]]
-   *     math.subset(g, math.index([false, true], 1), 8)          // returns [[5, 0, 6], [0, 8, 0]]
+   *     const f = math.subset(e, math.index(0, [0, 2]), [5, 6])
+   *     f                                                 // Array [[5, 0, 6]] ...
+   *     const g = math.subset(f, math.index(1, 1), 7, 0)
+   *     g                                                 // Array [[5, 0, 6], [0, 7, 0]] ...
+   *     math.subset(g, math.index([false, true], 1), 8)   // Array [[5, 0, 6], [0, 8, 0]]
    *
    *     // get submatrix using ranges
    *     const M = [
    *       [1, 2, 3],
    *       [4, 5, 6],
    *       [7, 8, 9]
    *     ]
-   *     math.subset(M, math.index(math.range(0,2), math.range(0,3))) // [[1, 2, 3], [4, 5, 6]]
+   *     math.subset(M, math.index(math.range(0,2), math.range(0,3))) // Array [[1, 2, 3], [4, 5, 6]]
    *
    * See also:
    *
@@ -75,6 +104,23 @@ export const createSubset = /* #__PURE__ */ factory(name, dependencies, ({ typed
 
     'string, Index': _getSubstring,
 
+    // Allow single number index to get layer:
+    'Matrix, number': function (M, position) {
+      return M.layer(position)
+    },
+
+    'Array, number': function (A, position) {
+      return A[position]
+    },
+
+    'string, number': function (s, position) {
+      return s.charAt(position)
+    },
+
+    // Otherwise pass second array argument to index function for convenience
+    'Matrix | Array | Object | string, Array': typed.referToSelf(
+      self => (v, i) => self(v, index(...i))),
+
     // set subset
     'Matrix, Index, any, any': function (value, index, replacement, defaultValue) {
       if (isEmptyIndex(index)) { return value }
@@ -89,19 +135,31 @@ export const createSubset = /* #__PURE__ */ factory(name, dependencies, ({ typed
       }
     }),
 
-    'Array, Index, any': typed.referTo('Matrix, Index, any, any', function (subsetRef) {
-      return function (value, index, replacement) {
-        return subsetRef(matrix(value), index, replacement, undefined).valueOf()
-      }
-    }),
-
-    'Matrix, Index, any': typed.referTo('Matrix, Index, any, any', function (subsetRef) {
-      return function (value, index, replacement) { return subsetRef(value, index, replacement, undefined) }
-    }),
-
     'string, Index, string': _setSubstring,
     'string, Index, string, string': _setSubstring,
-    'Object, Index, any': _setObjectProperty
+    'Object, Index, any': _setObjectProperty,
+
+    // fourth argument defaults to undefined:
+    'Matrix | Array, Index | Array | number, any': typed.referToSelf(
+      self => (v, pos, rep) => self(v, pos, rep, undefined)
+    ),
+
+    // Allow 2nd index to be a number:
+    'Matrix | Array | Object | string, number, any, any': typed.referToSelf(
+      self => (v, pos, rep, def) => {
+        const ix = [pos]
+        let wildcards = size(v).length
+        while (--wildcards > 0) ix.push(':')
+        return self(v, index(...ix), rep, def)
+      }),
+
+    'string, number, string': typed.referTo(
+      'string, Index, string', sis => (s, n, rep) => sis(s, index(n), rep)),
+
+    // Or allow 2nd argument to be an array of arguments to index
+    'Matrix | Array | Object | string, Array, any, any': typed.referToSelf(
+      self => (v, ixes, rep, def) => self(v, index(...ixes), rep, def)
+    )
   })
 
   /**

src/function/set/setCartesian.js

@@ -2,9 +2,9 @@ import { flatten } from '../../utils/array.js'
 import { factory } from '../../utils/factory.js'
 
 const name = 'setCartesian'
-const dependencies = ['typed', 'size', 'subset', 'compareNatural', 'Index', 'DenseMatrix']
+const dependencies = ['typed', 'size', 'subset', 'compareNatural']
 
-export const createSetCartesian = /* #__PURE__ */ factory(name, dependencies, ({ typed, size, subset, compareNatural, Index, DenseMatrix }) => {
+export const createSetCartesian = /* #__PURE__ */ factory(name, dependencies, ({ typed, size, subset, compareNatural }) => {
   /**
    * Create the cartesian product of two (multi)sets.
    * Multi-dimension arrays will be converted to single-dimension arrays
@@ -30,10 +30,10 @@ export const createSetCartesian = /* #__PURE__ */ factory(name, dependencies, ({
   return typed(name, {
     'Array | Matrix, Array | Matrix': function (a1, a2) {
       let result = []
-
-      if (subset(size(a1), new Index(0)) !== 0 && subset(size(a2), new Index(0)) !== 0) { // if any of them is empty, return empty
-        const b1 = flatten(Array.isArray(a1) ? a1 : a1.toArray()).sort(compareNatural)
-        const b2 = flatten(Array.isArray(a2) ? a2 : a2.toArray()).sort(compareNatural)
+      // if either is empty, return empty
+      if (size(a1)[0] !== 0 && size(a2)[0] !== 0) {
+        const b1 = flatten(a1.valueOf()).sort(compareNatural)
+        const b2 = flatten(a2.valueOf()).sort(compareNatural)
         result = []
         for (let i = 0; i < b1.length; i++) {
           for (let j = 0; j < b2.length; j++) {
@@ -42,11 +42,11 @@ export const createSetCartesian = /* #__PURE__ */ factory(name, dependencies, ({
         }
       }
       // return an array, if both inputs were arrays
-      if (Array.isArray(a1) && Array.isArray(a2)) {
-        return result
+      if (Array.isArray(a1)) {
+        if (Array.isArray(a2)) return result
+        return a2.create(result)
       }
-      // return a matrix otherwise
-      return new DenseMatrix(result)
+      return a1.create(result)
     }
   })
 })

src/function/set/setDifference.js

@@ -2,9 +2,9 @@ import { flatten, generalize, identify } from '../../utils/array.js'
 import { factory } from '../../utils/factory.js'
 
 const name = 'setDifference'
-const dependencies = ['typed', 'size', 'subset', 'compareNatural', 'Index', 'DenseMatrix']
+const dependencies = ['typed', 'size', 'subset', 'compareNatural']
 
-export const createSetDifference = /* #__PURE__ */ factory(name, dependencies, ({ typed, size, subset, compareNatural, Index, DenseMatrix }) => {
+export const createSetDifference = /* #__PURE__ */ factory(name, dependencies, ({ typed, size, subset, compareNatural }) => {
   /**
    * Create the difference of two (multi)sets: every element of set1, that is not the element of set2.
    * Multi-dimension arrays will be converted to single-dimension arrays before the operation.
@@ -28,15 +28,14 @@ export const createSetDifference = /* #__PURE__ */ factory(name, dependencies, (
    */
   return typed(name, {
     'Array | Matrix, Array | Matrix': function (a1, a2) {
-      let result
-      if (subset(size(a1), new Index(0)) === 0) { // empty-anything=empty
-        result = []
-      } else if (subset(size(a2), new Index(0)) === 0) { // anything-empty=anything
-        return flatten(a1.toArray())
-      } else {
-        const b1 = identify(flatten(Array.isArray(a1) ? a1 : a1.toArray()).sort(compareNatural))
-        const b2 = identify(flatten(Array.isArray(a2) ? a2 : a2.toArray()).sort(compareNatural))
-        result = []
+      let result = []
+      // empty - anything = empty
+      if (size(a1)[0] !== 0) {
+        if (size(a2)[0] === 0) { // anything - empty = anything
+          return flatten(a1.valueOf())
+        }
+        const b1 = identify(flatten(a1.valueOf()).sort(compareNatural))
+        const b2 = identify(flatten(a2.valueOf()).sort(compareNatural))
         let inb2
         for (let i = 0; i < b1.length; i++) {
           inb2 = false
@@ -51,12 +50,13 @@ export const createSetDifference = /* #__PURE__ */ factory(name, dependencies, (
           }
         }
       }
+      result = generalize(result) // remove the identifiers
       // return an array, if both inputs were arrays
-      if (Array.isArray(a1) && Array.isArray(a2)) {
-        return generalize(result)
+      if (Array.isArray(a1)) {
+        if (Array.isArray(a2)) return result
+        return a2.create(result)
       }
-      // return a matrix otherwise
-      return new DenseMatrix(generalize(result))
+      return a1.create(result)
     }
   })
 })

src/function/set/setDistinct.js

@@ -4,7 +4,7 @@ import { factory } from '../../utils/factory.js'
 const name = 'setDistinct'
 const dependencies = ['typed', 'size', 'subset', 'compareNatural', 'Index', 'DenseMatrix']
 
-export const createSetDistinct = /* #__PURE__ */ factory(name, dependencies, ({ typed, size, subset, compareNatural, Index, DenseMatrix }) => {
+export const createSetDistinct = /* #__PURE__ */ factory(name, dependencies, ({ typed, size, subset, compareNatural }) => {
   /**
    * Collect the distinct elements of a multiset.
    * A multi-dimension array will be converted to a single-dimension array before the operation.
@@ -22,16 +22,14 @@ export const createSetDistinct = /* #__PURE__ */ factory(name, dependencies, ({
    *    setMultiplicity
    *
    * @param {Array | Matrix}    a  A multiset
-   * @return {Array | Matrix}    A set containing the distinc elements of the multiset
+   * @return {Array | Matrix}    A set containing the distinct elements of the multiset
    */
   return typed(name, {
     'Array | Matrix': function (a) {
-      let result
-      if (subset(size(a), new Index(0)) === 0) { // if empty, return empty
-        result = []
-      } else {
-        const b = flatten(Array.isArray(a) ? a : a.toArray()).sort(compareNatural)
-        result = []
+      const result = []
+      // if empty, return empty
+      if (size(a)[0] !== 0) {
+        const b = flatten(a.valueOf()).sort(compareNatural)
         result.push(b[0])
         for (let i = 1; i < b.length; i++) {
           if (compareNatural(b[i], b[i - 1]) !== 0) {
@@ -44,7 +42,7 @@ export const createSetDistinct = /* #__PURE__ */ factory(name, dependencies, ({
         return result
       }
       // return a matrix otherwise
-      return new DenseMatrix(result)
+      return a.create(result)
     }
   })
 })

src/function/set/setIntersect.js

@@ -2,9 +2,9 @@ import { flatten, generalize, identify } from '../../utils/array.js'
 import { factory } from '../../utils/factory.js'
 
 const name = 'setIntersect'
-const dependencies = ['typed', 'size', 'subset', 'compareNatural', 'Index', 'DenseMatrix']
+const dependencies = ['typed', 'size', 'subset', 'compareNatural']
 
-export const createSetIntersect = /* #__PURE__ */ factory(name, dependencies, ({ typed, size, subset, compareNatural, Index, DenseMatrix }) => {
+export const createSetIntersect = /* #__PURE__ */ factory(name, dependencies, ({ typed, size, subset, compareNatural }) => {
   /**
    * Create the intersection of two (multi)sets.
    * Multi-dimension arrays will be converted to single-dimension arrays before the operation.
@@ -28,13 +28,11 @@ export const createSetIntersect = /* #__PURE__ */ factory(name, dependencies, ({
    */
   return typed(name, {
     'Array | Matrix, Array | Matrix': function (a1, a2) {
-      let result
-      if (subset(size(a1), new Index(0)) === 0 || subset(size(a2), new Index(0)) === 0) { // of any of them is empty, return empty
-        result = []
-      } else {
-        const b1 = identify(flatten(Array.isArray(a1) ? a1 : a1.toArray()).sort(compareNatural))
-        const b2 = identify(flatten(Array.isArray(a2) ? a2 : a2.toArray()).sort(compareNatural))
-        result = []
+      let result = []
+      // if both are nonempty, we must compute the intersection
+      if (size(a1)[0] !== 0 && size(a2)[0] !== 0) {
+        const b1 = identify(flatten(a1.valueOf()).sort(compareNatural))
+        const b2 = identify(flatten(a2.valueOf()).sort(compareNatural))
         for (let i = 0; i < b1.length; i++) {
           for (let j = 0; j < b2.length; j++) {
             if (compareNatural(b1[i].value, b2[j].value) === 0 && b1[i].identifier === b2[j].identifier) { // the identifier is always a decimal int
@@ -44,12 +42,13 @@ export const createSetIntersect = /* #__PURE__ */ factory(name, dependencies, ({
           }
         }
       }
+      result = generalize(result) // remove the identifiers
       // return an array, if both inputs were arrays
-      if (Array.isArray(a1) && Array.isArray(a2)) {
-        return generalize(result)
+      if (Array.isArray(a1)) {
+        if (Array.isArray(a2)) return result
+        return a2.create(result)
       }
-      // return a matrix otherwise
-      return new DenseMatrix(generalize(result))
+      return a1.create(result)
     }
   })
 })

src/function/set/setIsSubset.js

@@ -2,9 +2,9 @@ import { flatten, identify } from '../../utils/array.js'
 import { factory } from '../../utils/factory.js'
 
 const name = 'setIsSubset'
-const dependencies = ['typed', 'size', 'subset', 'compareNatural', 'Index']
+const dependencies = ['typed', 'size', 'subset', 'compareNatural']
 
-export const createSetIsSubset = /* #__PURE__ */ factory(name, dependencies, ({ typed, size, subset, compareNatural, Index }) => {
+export const createSetIsSubset = /* #__PURE__ */ factory(name, dependencies, ({ typed, size, subset, compareNatural }) => {
   /**
    * Check whether a (multi)set is a subset of another (multi)set. (Every element of set1 is the element of set2.)
    * Multi-dimension arrays will be converted to single-dimension arrays before the operation.
@@ -28,9 +28,10 @@ export const createSetIsSubset = /* #__PURE__ */ factory(name, dependencies, ({
    */
   return typed(name, {
     'Array | Matrix, Array | Matrix': function (a1, a2) {
-      if (subset(size(a1), new Index(0)) === 0) { // empty is a subset of anything
+      if (size(a1)[0] === 0) { // empty is a subset of anything
         return true
-      } else if (subset(size(a2), new Index(0)) === 0) { // anything is not a subset of empty
+      }
+      if (size(a2)[0] === 0) { // anything nonempty is not a subset of empty
         return false
       }
       const b1 = identify(flatten(Array.isArray(a1) ? a1 : a1.toArray()).sort(compareNatural))