docs(subset): Improve documentation of indices (#2446)

Incorporates (and supersedes) #2326 and the discussion therein. Resolves #2325. Co-authored-by: Jos de Jong <[email protected]>
josdejong · Mar 1, 2022 · dd1d08a · dd1d08a
1 parent cbcc425
commit dd1d08a
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 11 deletions.
diff --git a/src/expression/embeddedDocs/function/matrix/subset.js b/src/expression/embeddedDocs/function/matrix/subset.js
@@ -7,17 +7,25 @@ export const subsetDocs = {
     'subset(value, [index])',
     'subset(value, [index], replacement)'
   ],
-  description: 'Get or set a subset of a matrix or string. ' +
-      'Indexes are one-based. ' +
-      'Both the ranges lower-bound and upper-bound are included.',
+  description: 'Get or set a subset of the entries of a matrix or ' +
+      'characters of a string. ' +
+      'Indexes are one-based. There should be one index specification for ' +
+      'each dimension of the target. Each specification can be a single ' +
+      'index, a list of indices, or a range in colon notation `l:u`. ' +
+      'In a range, both the lower bound l and upper bound u are included; ' +
+      'and if a bound is omitted it defaults to the most extreme valid value. ' +
+      'The cartesian product of the indices specified in each dimension ' +
+      'determines the target of the operation.',
   examples: [
     'd = [1, 2; 3, 4]',
     'e = []',
     'e[1, 1:2] = [5, 6]',
     'e[2, :] = [7, 8]',
     'f = d * e',
     'f[2, 1]',
-    'f[:, 1]'
+    'f[:, 1]',
+    'f[[1,2], [1,3]] = [9, 10; 11, 12]',
+    'f'
   ],
   seealso: [
     'concat', 'det', 'diag', 'identity', 'inv', 'ones', 'range', 'size', 'squeeze', 'trace', 'transpose', 'zeros'

diff --git a/src/function/matrix/subset.js b/src/function/matrix/subset.js
@@ -25,16 +25,26 @@ export const createSubset = /* #__PURE__ */ factory(name, dependencies, ({ typed
    *
    *     // replace a subset
    *     const e = []
-   *     const f = math.subset(e, math.index(0, [0, 2]), [5, 6])  // f = [[5, 6]]
+   *     const f = math.subset(e, math.index(0, [0, 2]), [5, 6])  // f = [[5, 6]] and e = [[5, 0, 6]]
    *     const g = math.subset(f, math.index(1, 1), 7, 0)         // g = [[5, 6], [0, 7]]
    *
+   *     // 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]]
+   *
    * See also:
    *
    *     size, resize, squeeze, index
    *
    * @param {Array | Matrix | string} matrix  An array, matrix, or string
-   * @param {Index} index                     An index containing ranges for each
-   *                                          dimension
+   * @param {Index} index
+   *    For each dimension of the target, specifies an index or a list of
+   *    indices to fetch or set. `subset` uses the cartesian product of
+   *    the indices specified in each dimension.
    * @param {*} [replacement]                 An array, matrix, or scalar.
    *                                          If provided, the subset is replaced with replacement.
    *                                          If not provided, the subset is returned
@@ -91,7 +101,7 @@ export const createSubset = /* #__PURE__ */ factory(name, dependencies, ({ typed
 /**
  * Retrieve a subset of a string
  * @param {string} str            string from which to get a substring
- * @param {Index} index           An index containing ranges for each dimension
+ * @param {Index} index           An index or list of indices (character positions)
  * @returns {string} substring
  * @private
  */
@@ -122,7 +132,7 @@ function _getSubstring (str, index) {
 /**
  * Replace a substring in a string
  * @param {string} str            string to be replaced
- * @param {Index} index           An index containing ranges for each dimension
+ * @param {Index} index           An index or list of indices (character positions)
  * @param {string} replacement    Replacement string
  * @param {string} [defaultValue] Default value to be uses when resizing
  *                                the string. is ' ' by default

diff --git a/types/index.d.ts b/types/index.d.ts
@@ -1723,7 +1723,7 @@ declare namespace math {
     /**
      * Get or set a subset of a matrix or string.
      * @param value An array, matrix, or string
-     * @param index An index containing ranges for each dimension
+     * @param index For each dimension, an index or list of indices to get or set.
      * @param replacement An array, matrix, or scalar. If provided, the
      * subset is replaced with replacement. If not provided, the subset is
      * returned
@@ -4319,7 +4319,7 @@ declare namespace math {
 
     /**
      * Get or set a subset of a matrix or string.
-     * @param index An index containing ranges for each dimension
+     * @param index For each dimension, an index or list of indices to get or set
      * @param replacement An array, matrix, or scalar. If provided, the
      * subset is replaced with replacement. If not provided, the subset is
      * returned