refactor: docs & examples

Author: headlessNode

lib/node_modules/@stdlib/blas/ext/base/slast-index-of-row/README.md

@@ -22,16 +22,12 @@ limitations under the License.
 
 > Return the index of the last row in a single-precision floating-point input matrix which has the same elements as a provided search vector.
 
-<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
-
 <section class="intro">
 
 </section>
 
 <!-- /.intro -->
 
-<!-- Package usage documentation. -->
-
 <section class="usage">
 
 ## Usage
@@ -50,17 +46,16 @@ var Uint8Array = require( '@stdlib/array/uint8' );
 
 /*
     A = [
-        [ 1.0, 3.0 ],
-        [ 2.0, 4.0 ],
-        [ 2.0, 4.0 ],
-        [ 0.0, 0.0 ]
+        [ 1.0, 2.0 ],
+        [ 3.0, 4.0 ],
+        [ 3.0, 4.0 ]
     ]
 */
-var A = new Float32Array( [ 1.0, 2.0, 2.0, 0.0, 3.0, 4.0, 4.0, 0.0 ] );
+var A = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 3.0, 4.0 ] );
 
-var x = new Float32Array( [ 2.0, 4.0 ] );
-var workspace = new Uint8Array( 4 );
-var out = slastIndexOfRow( 'column-major', 4, 2, A, 4, x, 1, workspace, 1 );
+var x = new Float32Array( [ 3.0, 4.0 ] );
+var workspace = new Uint8Array( 3 );
+var out = slastIndexOfRow( 'row-major', 3, 2, A, 2, x, 1, workspace, 1 );
 // returns 2
 ```
 
@@ -70,11 +65,11 @@ The function has the following parameters:
 -   **M**: number of rows in `A`.
 -   **N**: number of columns in `A`.
 -   **A**: input matrix stored as a [`Float32Array`][mdn-float32array].
--   **LDA**: stride of the first dimension of `A` (a.k.a., leading dimension of the matrix `A`).
+-   **LDA**: stride length for the first dimension of `A` (a.k.a., leading dimension of the matrix `A`).
 -   **x**: search vector stored as a [`Float32Array`][mdn-float32array].
--   **strideX**: stride length of `x`.
--   **workspace**: workspace array stored as a [`Uint8Array`][mdn-uint8array] for tracking row match candidates. This parameter is ignored if the function is provided an input matrix stored in row-major order.
--   **strideW**: stride length of `workspace`.
+-   **strideX**: stride length for `x`.
+-   **workspace**: workspace array stored as a [`Uint8Array`][mdn-uint8array] for tracking row match candidates. This parameter is ignored if the input matrix is stored in row-major order.
+-   **strideW**: stride length for `workspace`.
 
 When an input matrix is stored in row-major order, the workspace parameter is ignored, and, thus, one may provide an empty workspace array.
 
@@ -86,15 +81,14 @@ var Uint8Array = require( '@stdlib/array/uint8' );
     A = [
         [ 1.0, 2.0 ],
         [ 3.0, 4.0 ],
-        [ 3.0, 4.0 ],
-        [ 0.0, 0.0 ]
+        [ 3.0, 4.0 ]
     ]
 */
-var A = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 3.0, 4.0, 0.0, 0.0 ] );
+var A = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 3.0, 4.0 ] );
 
 var x = new Float32Array( [ 3.0, 4.0 ] );
 var workspace = new Uint8Array( 0 );
-var out = slastIndexOfRow( 'row-major', 4, 2, A, 2, x, 1, workspace, 1 );
+var out = slastIndexOfRow( 'row-major', 3, 2, A, 2, x, 1, workspace, 1 );
 // returns 2
 ```
 
@@ -106,17 +100,16 @@ var Uint8Array = require( '@stdlib/array/uint8' );
 
 /*
     A = [
-        [ 1.0, 3.0 ],
-        [ 2.0, 4.0 ],
-        [ 2.0, 4.0 ],
-        [ 0.0, 0.0 ]
+        [ 1.0, 2.0 ],
+        [ 3.0, 4.0 ],
+        [ 3.0, 4.0 ]
     ]
 */
-var A = new Float32Array( [ 1.0, 2.0, 2.0, 0.0, 3.0, 4.0, 4.0, 0.0 ] );
+var A = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 3.0, 4.0 ] );
 
 var x = new Float32Array( [ -3.0, -4.0 ] );
-var workspace = new Uint8Array( 4 );
-var out = slastIndexOfRow( 'column-major', 4, 2, A, 4, x, 1, workspace, 1 );
+var workspace = new Uint8Array( 3 );
+var out = slastIndexOfRow( 'row-major', 3, 2, A, 2, x, 1, workspace, 1 );
 // returns -1
 ```
 
@@ -129,16 +122,16 @@ var Float32Array = require( '@stdlib/array/float32' );
 var Uint8Array = require( '@stdlib/array/uint8' );
 
 // Initial arrays:
-var A0 = new Float32Array( [ 0.0, 1.0, 2.0, 3.0, 4.0, 3.0, 4.0, 0.0, 0.0 ] );
-var x0 = new Float32Array( [ 0.0, 3.0, 4.0 ] );
+var A0 = new Float32Array( [ 9999.0, 1.0, 2.0, 3.0, 4.0, 0.0, 0.0 ] );
+var x0 = new Float32Array( [ 9999.0, 3.0, 4.0 ] );
 
 // Create offset views:
 var A1 = new Float32Array( A0.buffer, A0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
 var x1 = new Float32Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
 
-var workspace = new Uint8Array( 0 );
-var out = slastIndexOfRow( 'row-major', 4, 2, A1, 2, x1, 1, workspace, 1 );
-// returns 2
+var workspace = new Uint8Array( 3 );
+var out = slastIndexOfRow( 'row-major', 3, 2, A1, 2, x1, 1, workspace, 1 );
+// returns 1
 ```
 
 <!-- lint disable maximum-heading-length -->
@@ -155,17 +148,16 @@ var Uint8Array = require( '@stdlib/array/uint8' );
 
 /*
     A = [
-        [ 1.0, 3.0 ],
-        [ 2.0, 4.0 ],
-        [ 2.0, 4.0 ],
-        [ 0.0, 0.0 ]
+        [ 1.0, 2.0 ],
+        [ 3.0, 4.0 ],
+        [ 3.0, 4.0 ]
     ]
 */
-var A = new Float32Array( [ 1.0, 2.0, 2.0, 0.0, 3.0, 4.0, 4.0, 0.0 ] );
+var A = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 3.0, 4.0 ] );
 
-var x = new Float32Array( [ 2.0, 4.0 ] );
-var workspace = new Uint8Array( 4 );
-var out = slastIndexOfRow.ndarray( 4, 2, A, 1, 4, 0, x, 1, 0, workspace, 1, 0 );
+var x = new Float32Array( [ 3.0, 4.0 ] );
+var workspace = new Uint8Array( 3 );
+var out = slastIndexOfRow.ndarray( 3, 2, A, 2, 1, 0, x, 1, 0, workspace, 1, 0 );
 // returns 2
 ```
 
@@ -174,14 +166,14 @@ The function has the following parameters:
 -   **M**: number of rows in `A`.
 -   **N**: number of columns in `A`.
 -   **A**: input matrix stored as a [`Float32Array`][mdn-float32array].
--   **strideA1**: stride of the first dimension of `A`.
--   **strideA2**: stride of the second dimension of `A`.
+-   **strideA1**: stride length for the first dimension of `A`.
+-   **strideA2**: stride length for the second dimension of `A`.
 -   **offsetA**: starting index for `A`.
 -   **x**: search vector stored as a [`Float32Array`][mdn-float32array].
--   **strideX**: stride length of `x`.
+-   **strideX**: stride length for `x`.
 -   **offsetX**: starting index for `x`.
--   **workspace**: workspace array stored as a [`Uint8Array`][mdn-uint8array] for tracking row match candidates. This parameter is ignored if the function is provided an input matrix stored in row-major order.
--   **strideW**: stride length of `workspace`.
+-   **workspace**: workspace array stored as a [`Uint8Array`][mdn-uint8array] for tracking row match candidates. This parameter is ignored if the input matrix is stored in row-major order.
+-   **strideW**: stride length for `workspace`.
 -   **offsetW**: starting index for `workspace`.
 
 When an input matrix is stored in row-major order, the workspace parameter is ignored, and, thus, one may provide an empty workspace array.
@@ -190,32 +182,57 @@ When an input matrix is stored in row-major order, the workspace parameter is ig
 var Float32Array = require( '@stdlib/array/float32' );
 var Uint8Array = require( '@stdlib/array/uint8' );
 
-var A = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 3.0, 4.0, 0.0, 0.0 ] );
+/*
+    A = [
+        [ 1.0, 2.0 ],
+        [ 3.0, 4.0 ],
+        [ 3.0, 4.0 ]
+    ]
+*/
+var A = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 3.0, 4.0 ] );
 
 var x = new Float32Array( [ 3.0, 4.0 ] );
 var workspace = new Uint8Array( 0 );
-var out = slastIndexOfRow.ndarray( 4, 2, A, 2, 1, 0, x, 1, 0, workspace, 1, 0 );
+var out = slastIndexOfRow.ndarray( 3, 2, A, 2, 1, 0, x, 1, 0, workspace, 1, 0 );
 // returns 2
 ```
 
+While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, offset parameters support indexing semantics based on starting indices. For example,
+
+```javascript
+var Float32Array = require( '@stdlib/array/float32' );
+var Uint8Array = require( '@stdlib/array/uint8' );
+
+/*
+    A = [
+        [ 1.0, 2.0 ],
+        [ 3.0, 4.0 ],
+        [ 0.0, 0.0 ]
+    ]
+*/
+var A = new Float32Array( [ 9999.0, 1.0, 2.0, 3.0, 4.0, 0.0, 0.0 ] );
+
+var x = new Float32Array( [ 9999.0, 3.0, 4.0 ] );
+var workspace = new Uint8Array( 3 );
+var out = slastIndexOfRow.ndarray( 3, 2, A, 2, 1, 1, x, 1, 1, workspace, 1, 0 );
+// returns 1
+```
+
 </section>
 
 <!-- /.usage -->
 
-<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
-
 <section class="notes">
 
 ## Notes
 
+-   If `M <= 0` or `N <= 0`, both functions return `-1`.
 -   When searching for a matching row, the function checks for equality using the strict equality operator `===`. As a consequence, `NaN` values are considered distinct, and `-0` and `+0` are considered the same.
 
 </section>
 
 <!-- /.notes -->
 
-<!-- Package usage examples. -->
-
 <section class="examples">
 
 ## Examples
@@ -231,11 +248,11 @@ var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
 var shape2strides = require( '@stdlib/ndarray/base/shape2strides' );
 var slastIndexOfRow = require( '@stdlib/blas/ext/base/slast-index-of-row' );
 
-var shape = [ 4, 3 ];
+var shape = [ 3, 3 ];
 var order = 'row-major';
 var strides = shape2strides( shape, order );
 
-var A = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 4.0, 5.0, 6.0, 0.0, 0.0, 0.0 ] );
+var A = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 4.0, 5.0, 6.0 ] );
 console.log( ndarray2array( A, shape, strides, 0, order ) );
 
 var x = new Float32Array( [ 4.0, 5.0, 6.0 ] );
@@ -303,10 +320,10 @@ The function accepts the following arguments:
 -   **M**: `[in] CBLAS_INT` number of rows in `A`.
 -   **N**: `[in] CBLAS_INT` number of columns in `A`.
 -   **A**: `[in] float*` input matrix.
--   **LDA**: `[in] CBLAS_INT` stride of the first dimension of `A` (a.k.a., leading dimension of the matrix `A`).
+-   **LDA**: `[in] CBLAS_INT` stride length for the first dimension of `A` (a.k.a., leading dimension of the matrix `A`).
 -   **X**: `[in] float*` search vector.
 -   **strideX**: `[in] CBLAS_INT` stride length for `X`.
--   **workspace**: `[inout] uint8_t*` workspace array for tracking row match candidates. This parameter is ignored if the function is provided an input matrix stored in row-major order.
+-   **workspace**: `[inout] uint8_t*` workspace array for tracking row match candidates. This parameter is ignored if the input matrix is stored in row-major order.
 -   **strideW**: `[in] CBLAS_INT` stride length for `workspace`.
 
 When an input matrix is stored in row-major order, the workspace parameter is ignored, and, thus, one may either provide an empty workspace array or a `NULL` pointer.
@@ -349,13 +366,13 @@ The function accepts the following arguments:
 -   **M**: `[in] CBLAS_INT` number of rows in `A`.
 -   **N**: `[in] CBLAS_INT` number of columns in `A`.
 -   **A**: `[in] float*` input matrix.
--   **strideA1**: `[in] CBLAS_INT` stride of the first dimension of `A`.
--   **strideA2**: `[in] CBLAS_INT` stride of the second dimension of `A`.
--   **offsetA**: `[in] CBLAS_INT` index offset for `A`.
+-   **strideA1**: `[in] CBLAS_INT` stride length for the first dimension of `A`.
+-   **strideA2**: `[in] CBLAS_INT` stride length for the second dimension of `A`.
+-   **offsetA**: `[in] CBLAS_INT` starting index for `A`.
 -   **X**: `[in] float*` search vector.
 -   **strideX**: `[in] CBLAS_INT` stride length for `X`.
 -   **offsetX**: `[in] CBLAS_INT` starting index for `X`.
--   **workspace**: `[inout] uint8_t*` workspace array for tracking row match candidates. This parameter is ignored if the function is provided an input matrix stored in row-major order.
+-   **workspace**: `[inout] uint8_t*` workspace array for tracking row match candidates. This parameter is ignored if the input matrix is stored in row-major order.
 -   **strideW**: `[in] CBLAS_INT` stride length for `workspace`.
 -   **offsetW**: `[in] CBLAS_INT` starting index for `workspace`.
 

lib/node_modules/@stdlib/blas/ext/base/slast-index-of-row/docs/repl.txt

@@ -25,8 +25,8 @@
         Input matrix `A`.
 
     LDA: integer
-        Stride of the first dimension of `A` (a.k.a., leading dimension of the
-        matrix `A`).
+        Stride length for the first dimension of `A` (a.k.a., leading dimension
+        of the matrix `A`).
 
     x: Float32Array
         Search vector.
@@ -35,8 +35,8 @@
         Stride length for `x`.
 
     workspace: Uint8Array
-        Workspace array for tracking row match candidates. This parameter
-        is ignored if the input matrix is stored in row-major order.
+        Workspace array for tracking row match candidates. This parameter is
+        ignored if the input matrix is stored in row-major order.
 
     strideW: integer
         Stride length for `workspace`.
@@ -48,11 +48,11 @@
 
     Examples
     --------
-    > var A = new {{alias:@stdlib/array/float32}}( [ 1.0, 2.0, 1.0, 2.0 ] );
-    > var x = new {{alias:@stdlib/array/float32}}( [ 1.0, 2.0 ] );
-    > var w = new {{alias:@stdlib/array/uint8}}( 2 );
-    > {{alias}}( 'row-major', 2, 2, A, 2, x, 1, w, 1 )
-    1
+    > var A = new {{alias:@stdlib/array/float32}}( [ 1.0, 2.0, 3.0, 4.0, 3.0, 4.0 ] );
+    > var x = new {{alias:@stdlib/array/float32}}( [ 3.0, 4.0 ] );
+    > var w = new {{alias:@stdlib/array/uint8}}( 3 );
+    > {{alias}}( 'row-major', 3, 2, A, 2, x, 1, w, 1 )
+    2
 
 
 {{alias}}.ndarray( M, N, A, sa1, sa2, oa, x, sx, ox, w, sw, ow )
@@ -79,10 +79,10 @@
         Input matrix `A`.
 
     sa1: integer
-        Stride of the first dimension of `A`.
+        Stride length for the first dimension of `A`.
 
     sa2: integer
-        Stride of the second dimension of `A`.
+        Stride length for the second dimension of `A`.
 
     oa: integer
         Starting index for `A`.
@@ -97,8 +97,8 @@
         Starting index for `x`.
 
     w: Uint8Array
-        Workspace array for tracking row match candidates. This parameter
-        is ignored if the input matrix is stored in row-major order.
+        Workspace array for tracking row match candidates. This parameter is
+        ignored if the input matrix is stored in row-major order.
 
     sw: integer
         Stride length for `w`.
@@ -113,11 +113,11 @@
 
     Examples
     --------
-    > var A = new {{alias:@stdlib/array/float32}}( [ 1.0, 2.0, 1.0, 2.0 ] );
-    > var x = new {{alias:@stdlib/array/float32}}( [ 1.0, 2.0 ] );
-    > var w = new {{alias:@stdlib/array/uint8}}( 2 );
-    > {{alias}}.ndarray( 2, 2, A, 2, 1, 0, x, 1, 0, w, 1, 0 )
-    1
+    > var A = new {{alias:@stdlib/array/float32}}( [ 1.0, 2.0, 3.0, 4.0, 3.0, 4.0 ] );
+    > var x = new {{alias:@stdlib/array/float32}}( [ 3.0, 4.0 ] );
+    > var w = new {{alias:@stdlib/array/uint8}}( 3 );
+    > {{alias}}.ndarray( 3, 2, A, 2, 1, 0, x, 1, 0, w, 1, 0 )
+    2
 
     See Also
     --------