feat!: add fromIndex support to blas/ext/find-index

lib/node_modules/@stdlib/blas/ext/find-index/README.md

@@ -30,7 +30,7 @@ limitations under the License.
 var findIndex = require( '@stdlib/blas/ext/find-index' );
 ```
 
-#### findIndex( x\[, options], clbk\[, thisArg] )
+#### findIndex( x\[, fromIndex]\[, options], clbk\[, thisArg] )
 
 Returns the index of the first element along an [ndarray][@stdlib/ndarray/ctor] dimension which passes a test implemented by a predicate function.
 
@@ -53,6 +53,7 @@ var out = findIndex( x, isEven );
 The function has the following parameters:
 
 -   **x**: input [ndarray][@stdlib/ndarray/ctor]. Must have at least one dimension.
+-   **fromIndex**: index from which to begin searching (_optional_). May be either a scalar value or an [ndarray][@stdlib/ndarray/ctor] having an integer index or "generic" [data type][@stdlib/ndarray/dtypes]. If provided an [ndarray][@stdlib/ndarray/ctor], the value must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the non-reduced dimensions of the input [ndarray][@stdlib/ndarray/ctor]. For example, given the input shape `[2, 3, 4]` and `options.dim=0`, a provided [ndarray][@stdlib/ndarray/ctor] must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the shape `[3, 4]`. If provided a negative integer, the index at which to begin searching along a dimension is determined by counting backward from the last element (where `-1` refers to the last element). Default: `0`.
 -   **options**: function options (_optional_).
 -   **clbk**: callback function.
 -   **thisArg**: callback execution context (_optional_).
@@ -111,6 +112,24 @@ var out = findIndex( x, isEven );
 // returns <ndarray>[ -1 ]
 ```
 
+By default, the function begins searching from the first element along the reduction dimension. To begin searching from a different index, provide a `fromIndex` argument.
+
+```javascript
+var array = require( '@stdlib/ndarray/array' );
+
+function isEven( v ) {
+    return v % 2.0 === 0.0;
+}
+
+// Create an input ndarray:
+var x = array( [ 2.0, 1.0, 3.0, 4.0, 5.0, 6.0 ] );
+// returns <ndarray>
+
+// Perform operation:
+var out = findIndex( x, 2, isEven );
+// returns <ndarray>[ 3 ]
+```
+
 By default, the function performs the operation over elements in the last dimension. To perform the operation over a different dimension, provide a `dim` option.
 
 ```javascript
@@ -173,7 +192,7 @@ var dt = dtype( idx );
 // returns 'generic'
 ```
 
-#### findIndex.assign( x, out\[, options], clbk\[, thisArg] )
+#### findIndex.assign( x\[, fromIndex], out\[, options], clbk\[, thisArg] )
 
 Returns the index of the first element along an [ndarray][@stdlib/ndarray/ctor] dimension which passes a test implemented by a predicate function and assigns results to a provided output [ndarray][@stdlib/ndarray/ctor].
 
@@ -200,6 +219,7 @@ var bool = ( out === y );
 The method has the following parameters:
 
 -   **x**: input [ndarray][@stdlib/ndarray/ctor]. Must have at least one dimension.
+-   **fromIndex**: index from which to begin searching (_optional_). May be either a scalar value or an [ndarray][@stdlib/ndarray/ctor] having an integer index or "generic" [data type][@stdlib/ndarray/dtypes]. If provided an [ndarray][@stdlib/ndarray/ctor], the value must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the non-reduced dimensions of the input [ndarray][@stdlib/ndarray/ctor]. For example, given the input shape `[2, 3, 4]` and `options.dim=0`, a provided [ndarray][@stdlib/ndarray/ctor] must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the shape `[3, 4]`. If provided a negative integer, the index at which to begin searching along a dimension is determined by counting backward from the last element (where `-1` refers to the last element). Default: `0`.
 -   **out**: output [ndarray][@stdlib/ndarray/ctor].
 -   **options**: function options (_optional_).
 -   **clbk**: callback function.

lib/node_modules/@stdlib/blas/ext/find-index/docs/repl.txt

@@ -1,5 +1,5 @@
 
-{{alias}}( x[, options], clbk[, thisArg] )
+{{alias}}( x[, fromIndex][, options], clbk[, thisArg] )
     Returns the index of the first element along an ndarray dimension which
     passes a test implemented by a predicate function.
 
@@ -18,7 +18,18 @@
     Parameters
     ----------
     x: ndarray
-        Input array. Must at least have one dimension.
+        Input array. Must have at least one dimension.
+
+    fromIndex: ndarray|integer (optional)
+        Index from which to begin searching. May be either a scalar value or an
+        ndarray having an integer or "generic" data type. If provided an ndarray
+        the value must have a shape which is broadcast compatible with the non-
+        reduced dimensions of the input ndarray. For example, given the input
+        shape `[2, 3, 4]` and `options.dim=0`, a provided ndarray must have a
+        shape which is broadcast-compatible with the shape `[3, 4]`. If provided
+        a negative integer, the index at which to begin searching along a
+        dimension is determined by counting backward from the last element
+        (where -1 refers to the last element). Default: 0.
 
     options: Object (optional)
         Function options.
@@ -55,7 +66,7 @@
     <ndarray>[ 1 ]
 
 
-{{alias}}.assign( x, out[, options], clbk[, thisArg] )
+{{alias}}.assign( x[, fromIndex], out[, options], clbk[, thisArg] )
     Returns the index of the first element along an ndarray dimension which
     passes a test implemented by a predicate function and assigns results to a
     provided output ndarray.
@@ -75,7 +86,18 @@
     Parameters
     ----------
     x: ndarray
-        Input array. Must at least have one dimension.
+        Input array. Must have at least one dimension.
+
+    fromIndex: ndarray|integer (optional)
+        Index from which to begin searching. May be either a scalar value or an
+        ndarray having an integer or "generic" data type. If provided an ndarray
+        the value must have a shape which is broadcast compatible with the non-
+        reduced dimensions of the input ndarray. For example, given the input
+        shape `[2, 3, 4]` and `options.dim=0`, a provided ndarray must have a
+        shape which is broadcast-compatible with the shape `[3, 4]`. If provided
+        a negative integer, the index at which to begin searching along a
+        dimension is determined by counting backward from the last element
+        (where -1 refers to the last element). Default: 0.
 
     out: ndarray
         Output array.
@@ -103,7 +125,7 @@
     Examples
     --------
     > var x = {{alias:@stdlib/ndarray/array}}( [ -1.0, 2.0, -3.0, -4.0 ] );
-    > var out = {{alias:@stdlib/ndarray/zeros}}( [] );
+    > var out = {{alias:@stdlib/ndarray/zeros}}( [], { 'dtype': 'int32' } );
     > function clbk( v ) { return v % 2.0 === 0.0; };
     > var y = {{alias}}.assign( x, out, clbk )
     <ndarray>[ 1 ]

lib/node_modules/@stdlib/blas/ext/find-index/docs/types/index.d.ts

@@ -27,6 +27,11 @@
 */
 type InputArray<T> = typedndarray<T>;
 
+/**
+* From index.
+*/
+type FromIndex = typedndarray<number> | number;
+
 /**
 * Output array.
 */
@@ -135,6 +140,33 @@
 	*/
 	<T = unknown, U extends InputArray<T> = InputArray<T>, ThisArg = unknown>( x: U, clbk: Predicate<T, U, ThisArg>, thisArg?: ThisParameterType<Predicate<T, U, ThisArg>> ): OutputArray;
 
+	/**
+	* Returns the index of the first element along an ndarray dimension which passes a test implemented by a predicate function.
+	*
+	* ## Notes
+	*
+	* -   If no element along an ndarray dimension passes a test implemented by the predicate function, the corresponding element in the returned ndarray is `-1`.
+	*
+	* @param x - input ndarray
+	* @param fromIndex - index from which to begin searching
+	* @param clbk - predicate function
+	* @param thisArg - predicate function execution context
+	* @returns output ndarray
+	*
+	* @example
+	* var array = require( '@stdlib/ndarray/array' );
+	*
+	* function clbk( value ) {
+	*     return value % 2.0 === 0.0;
+	* }
+	*
+	* var x = array( [ 2.0, 1.0, -3.0, 4.0 ] );
+	*
+	* var y = findIndex( x, 2, clbk );
+	* // returns <ndarray>[ 3 ]
+	*/
+	<T = unknown, U extends InputArray<T> = InputArray<T>, ThisArg = unknown>( x: U, fromIndex: FromIndex, clbk: Predicate<T, U, ThisArg>, thisArg?: ThisParameterType<Predicate<T, U, ThisArg>> ): OutputArray;
+
 	/**
 	* Returns the index of the first element along an ndarray dimension which passes a test implemented by a predicate function.
 	*
@@ -160,8 +192,36 @@
 	* var y = findIndex( x, {}, clbk );
 	* // returns <ndarray>[ 1 ]
 	*/
 	<T = unknown, U extends InputArray<T> = InputArray<T>, ThisArg = unknown>( x: U, options: Options, clbk: Predicate<T, U, ThisArg>, thisArg?: ThisParameterType<Predicate<T, U, ThisArg>> ): OutputArray;
 
+	/**
+	* Returns the index of the first element along an ndarray dimension which passes a test implemented by a predicate function.
+	*
+	* ## Notes
+	*
+	* -   If no element along an ndarray dimension passes a test implemented by the predicate function, the corresponding element in the returned ndarray is `-1`.
+	*
+	* @param x - input ndarray
+	* @param fromIndex - index from which to begin searching
+	* @param options - function options
+	* @param clbk - predicate function
+	* @param thisArg - predicate function execution context
+	* @returns output ndarray
+	*
+	* @example
+	* var array = require( '@stdlib/ndarray/array' );
+	*
+	* function clbk( value ) {
+	*     return value % 2.0 === 0.0;
+	* }
+	*
+	* var x = array( [ 2.0, 1.0, -3.0, 4.0 ] );
+	*
+	* var y = findIndex( x, 2, {}, clbk );
+	* // returns <ndarray>[ 3 ]
+	*/
+	<T = unknown, U extends InputArray<T> = InputArray<T>, ThisArg = unknown>( x: U, fromIndex: FromIndex, options: Options, clbk: Predicate<T, U, ThisArg>, thisArg?: ThisParameterType<Predicate<T, U, ThisArg>> ): OutputArray;
+
 	/**
 	* Returns the index of the first element along an ndarray dimension which passes a test implemented by a predicate function and assigns results to a provided output ndarray.
 	*
@@ -194,6 +254,39 @@
 	*/
 	assign<T = unknown, U extends InputArray<T> = InputArray<T>, V extends OutputArray = OutputArray, ThisArg = unknown>( x: U, out: V, clbk: Predicate<T, U, ThisArg>, thisArg?: ThisParameterType<Predicate<T, U, ThisArg>> ): V;
 
+	/**
+	* Returns the index of the first element along an ndarray dimension which passes a test implemented by a predicate function and assigns results to a provided output ndarray.
+	*
+	* ## Notes
+	*
+	* -   If no element along an ndarray dimension passes a test implemented by the predicate function, the corresponding element in the returned ndarray is `-1`.
+	*
+	* @param x - input ndarray
+	* @param fromIndex - index from which to begin searching
+	* @param out - output ndarray
+	* @param clbk - predicate function
+	* @param thisArg - predicate function execution context
+	* @returns output ndarray
+	*
+	* @example
+	* var array = require( '@stdlib/ndarray/array' );
+	* var zeros = require( '@stdlib/ndarray/zeros' );
+	*
+	* function clbk( value ) {
+	*     return value % 2.0 === 0.0;
+	* }
+	*
+	* var x = array( [ 2.0, 1.0, -3.0, 4.0 ] );
+	* var y = zeros( [] );
+	*
+	* var out = findIndex.assign( x, 2, y, clbk );
+	* // returns <ndarray>[ 3 ]
+	*
+	* var bool = ( out === y );
+	* // returns true
+	*/
+	assign<T = unknown, U extends InputArray<T> = InputArray<T>, V extends OutputArray = OutputArray, ThisArg = unknown>( x: U, fromIndex: FromIndex, out: V, clbk: Predicate<T, U, ThisArg>, thisArg?: ThisParameterType<Predicate<T, U, ThisArg>> ): V;
+
 	/**
 	* Returns the index of the first element along an ndarray dimension which passes a test implemented by a predicate function and assigns results to a provided output ndarray.
 	*
@@ -226,6 +319,40 @@
 	* // returns true
 	*/
 	assign<T = unknown, U extends InputArray<T> = InputArray<T>, V extends OutputArray = OutputArray, ThisArg = unknown>( x: U, out: V, options: BaseOptions, clbk: Predicate<T, U, ThisArg>, thisArg?: ThisParameterType<Predicate<T, U, ThisArg>> ): V;
+
+	/**
+	* Returns the index of the first element along an ndarray dimension which passes a test implemented by a predicate function and assigns results to a provided output ndarray.
+	*
+	* ## Notes
+	*
+	* -   If no element along an ndarray dimension passes a test implemented by the predicate function, the corresponding element in the returned ndarray is `-1`.
+	*
+	* @param x - input ndarray
+	* @param fromIndex - index from which to begin searching
+	* @param out - output ndarray
+	* @param options - function options
+	* @param clbk - predicate function
+	* @param thisArg - predicate function execution context
+	* @returns output ndarray
+	*
+	* @example
+	* var array = require( '@stdlib/ndarray/array' );
+	* var zeros = require( '@stdlib/ndarray/zeros' );
+	*
+	* function clbk( value ) {
+	*     return value % 2.0 === 0.0;
+	* }
+	*
+	* var x = array( [ 2.0, 1.0, -3.0, 4.0 ] );
+	* var y = zeros( [] );
+	*
+	* var out = findIndex.assign( x, 2, y, {}, clbk );
+	* // returns <ndarray>[ 3 ]
+	*
+	* var bool = ( out === y );
+	* // returns true
+	*/
+	assign<T = unknown, U extends InputArray<T> = InputArray<T>, V extends OutputArray = OutputArray, ThisArg = unknown>( x: U, fromIndex: FromIndex, out: V, options: BaseOptions, clbk: Predicate<T, U, ThisArg>, thisArg?: ThisParameterType<Predicate<T, U, ThisArg>> ): V;
 }
 
 /**
@@ -236,6 +363,7 @@
 * -   If no element along an ndarray dimension passes a test implemented by the predicate function, the corresponding element in the returned ndarray is `-1`.
 *
 * @param x - input ndarray
+* @param fromIndex - index from which to begin searching
 * @param options - function options
 * @param clbk - predicate function
 * @param thisArg - predicate function execution context