feat!: add fromIndex support to blas/ext/base/ndarray/gfind-last-index

lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-last-index/README.md

@@ -41,6 +41,7 @@ var gfindLastIndex = require( '@stdlib/blas/ext/base/ndarray/gfind-last-index' )
 Returns the index of the last element in a one-dimensional ndarray which passes a test implemented by a predicate function.
 
 ```javascript
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var vector = require( '@stdlib/ndarray/vector/ctor' );
 
 function isEven( v ) {
@@ -49,13 +50,18 @@ function isEven( v ) {
 
 var x = vector( [ 1.0, 3.0, 4.0, 2.0 ], 'generic' );
 
-var idx = gfindLastIndex( [ x ], isEven );
+var fromIndex = scalar2ndarray( 3, {
+    'dtype': 'generic'
+});
+
+var idx = gfindLastIndex( [ x, fromIndex ], isEven );
 // returns 3
 ```
 
 If no element passes a test implemented by a predicate function, the function returns `-1`.
 
 ```javascript
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var vector = require( '@stdlib/ndarray/vector/ctor' );
 
 function isEven( v ) {
@@ -64,14 +70,23 @@ function isEven( v ) {
 
 var x = vector( [ 1.0, 3.0, 5.0, 7.0 ], 'generic' );
 
-var idx = gfindLastIndex( [ x ], isEven );
+var fromIndex = scalar2ndarray( 3, {
+    'dtype': 'generic'
+});
+
+var idx = gfindLastIndex( [ x, fromIndex ], isEven );
 // returns -1
 ```
 
 The function has the following parameters:
 
--   **arrays**: array-like object containing a one-dimensional input ndarray.
+-   **arrays**: array-like object containing the following ndarrays:
+
+    -   a one-dimensional input ndarray.
+    -   a zero-dimensional ndarray containing the index from which to begin searching.
+
 -   **clbk**: callback function.
+
 -   **thisArg**: callback execution context (_optional_).
 
 The callback function is provided the following arguments:
@@ -83,6 +98,7 @@ The callback function is provided the following arguments:
 To set the callback execution context, provide a `thisArg`.
 
 ```javascript
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var vector = require( '@stdlib/ndarray/vector/ctor' );
 
 function isEven( v ) {
@@ -95,7 +111,11 @@ var ctx = {
     'count': 0
 };
 
-var v = gfindLastIndex( [ x ], isEven, ctx );
+var fromIndex = scalar2ndarray( 3, {
+    'dtype': 'generic'
+});
+
+var v = gfindLastIndex( [ x, fromIndex ], isEven, ctx );
 // returns 3
 
 var count = ctx.count;
@@ -111,6 +131,7 @@ var count = ctx.count;
 ## Notes
 
 -   If provided an empty one-dimensional ndarray, the function returns `-1`.
+-   If a specified starting search index is negative, the function resolves the starting search index by counting backward from the last element (where `-1` refers to the last element).
 
 </section>
 
@@ -124,6 +145,7 @@ var count = ctx.count;
 
 ```javascript
 var discreteUniform = require( '@stdlib/random/discrete-uniform' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var gfindLastIndex = require( '@stdlib/blas/ext/base/ndarray/gfind-last-index' );
 
@@ -138,7 +160,11 @@ var opts = {
 var x = discreteUniform( [ 10 ], -100, 100, opts );
 console.log( ndarray2array( x ) );
 
-var idx = gfindLastIndex( [ x ], isEven );
+var fromIndex = scalar2ndarray( 9, {
+    'dtype': 'generic'
+});
+
+var idx = gfindLastIndex( [ x, fromIndex ], isEven );
 console.log( idx );
 ```
 

lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-last-index/benchmark/benchmark.js

@@ -22,6 +22,7 @@
 
 var bench = require( '@stdlib/bench' );
 var uniform = require( '@stdlib/random/uniform' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
 var pow = require( '@stdlib/math/base/special/pow' );
 var format = require( '@stdlib/string/format' );
@@ -57,7 +58,13 @@ function clbk( v ) {
 * @returns {Function} benchmark function
 */
 function createBenchmark( len ) {
-	var x = uniform( [ len ], 0.0, 100.0, options );
+	var fromIndex;
+	var x;
+
+	x = uniform( [ len ], 0.0, 100.0, options );
+	fromIndex = scalar2ndarray( len - 1, {
+		'dtype': 'generic'
+	});
 	return benchmark;
 
 	/**
@@ -72,7 +79,7 @@ function createBenchmark( len ) {
 
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
-			v = gfindLastIndex( [ x ], clbk );
+			v = gfindLastIndex( [ x, fromIndex ], clbk );
 			if ( isnan( v ) ) {
 				b.fail( 'should not return NaN' );
 			}

lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-last-index/docs/repl.txt

@@ -3,6 +3,10 @@
     Returns the index of the last element in a one-dimensional ndarray which
     passes a test implemented by a predicate function.
 
+    If a specified starting search index is negative, the function resolves the
+    starting search index by counting backward from the last element (where `-1`
+    refers to the last element).
+
     If provided an empty ndarray or no element passes a test implemented by a
     predicate function, the function returns `-1`.
 
@@ -15,7 +19,11 @@
     Parameters
     ----------
     arrays: ArrayLikeObject<ndarray>
-        Array-like object containing a one-dimensional input ndarray.
+        Array-like object containing the following ndarrays:
+
+        - a one-dimensional input ndarray.
+        - a zero-dimensional ndarray containing the index from which to begin
+        searching.
 
     clbk: Function
         Callback function.
@@ -31,8 +39,9 @@
     Examples
     --------
     > var x = {{alias:@stdlib/ndarray/vector/ctor}}( [ 1.0, -2.0, 2.0 ], 'generic' );
+    > var i = {{alias:@stdlib/ndarray/from-scalar}}( 2, { 'dtype': 'generic' } );
     > function f ( v ) { return v % 2.0 === 0.0; };
-    > {{alias}}( [ x ], f )
+    > {{alias}}( [ x, i ], f )
     2
 
     See Also

lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-last-index/docs/types/index.d.ts

@@ -74,6 +74,7 @@ type Predicate<T, U, ThisArg> = Nullary<ThisArg> | Unary<T, ThisArg> | Binary<T,
 * -   The function expects the following ndarrays:
 *
 *     -   a one-dimensional input ndarray.
+*     -   a zero-dimensional ndarray containing the index from which to begin searching.
 *
 * -   If no element passes a test implemented by a predicate function, the function returns `-1`.
 *
@@ -83,6 +84,7 @@ type Predicate<T, U, ThisArg> = Nullary<ThisArg> | Unary<T, ThisArg> | Binary<T,
 * @returns index
 *
 * @example
+* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 * var vector = require( '@stdlib/ndarray/vector/ctor' );
 *
 * function clbk( v ) {
@@ -91,10 +93,14 @@ type Predicate<T, U, ThisArg> = Nullary<ThisArg> | Unary<T, ThisArg> | Binary<T,
 *
 * var x = vector( [ 1.0, 3.0, 4.0, 2.0 ], 'generic' );
 *
-* var v = gfindLastIndex( [ x ], clbk );
+* var fromIndex = scalar2ndarray( 3, {
+*     'dtype': 'generic'
+* });
+*
+* var v = gfindLastIndex( [ x, fromIndex ], clbk );
 * // returns 3
 */
-declare function gfindLastIndex<T = unknown, U extends typedndarray<T> = typedndarray<T>, ThisArg = unknown>( arrays: [ U ], clbk: Predicate<T, U, ThisArg>, thisArg?: ThisParameterType<Predicate<T, U, ThisArg>> ): number;
+declare function gfindLastIndex<T = unknown, U extends typedndarray<T> = typedndarray<T>, ThisArg = unknown>( arrays: [ U, typedndarray<number> ], clbk: Predicate<T, U, ThisArg>, thisArg?: ThisParameterType<Predicate<T, U, ThisArg>> ): number;
 
 
 // EXPORTS //

lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-last-index/docs/types/test.ts

@@ -19,6 +19,7 @@
 /* eslint-disable space-in-parens */
 
 import zeros = require( '@stdlib/ndarray/zeros' );
+import scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 import gfindLastIndex = require( './index' );
 
 /**
@@ -27,7 +28,7 @@
 * @param value - ndarray element
 * @returns result
 */
 function clbk( value: any ): boolean {
 	return value % 2.0 === 0.0;
 }
 
@@ -39,9 +40,12 @@
 	const x = zeros( [ 10 ], {
 		'dtype': 'generic'
 	});
+	const fromIndex = scalar2ndarray( 0, {
+		'dtype': 'generic'
+	});
 
-	gfindLastIndex( [ x ], clbk ); // $ExpectType number
-	gfindLastIndex( [ x ], clbk, {} ); // $ExpectType number
+	gfindLastIndex( [ x, fromIndex ], clbk ); // $ExpectType number
+	gfindLastIndex( [ x, fromIndex ], clbk, {} ); // $ExpectType number
 }
 
 // The compiler throws an error if the function is provided a first argument which is not an array of ndarrays...
@@ -72,32 +76,38 @@
 	const x = zeros( [ 10 ], {
 		'dtype': 'generic'
 	});
+	const fromIndex = scalar2ndarray( 0, {
+		'dtype': 'generic'
+	});
 
-	gfindLastIndex( [ x ], '10' ); // $ExpectError
-	gfindLastIndex( [ x ], 10 ); // $ExpectError
-	gfindLastIndex( [ x ], true ); // $ExpectError
-	gfindLastIndex( [ x ], false ); // $ExpectError
-	gfindLastIndex( [ x ], null ); // $ExpectError
-	gfindLastIndex( [ x ], undefined ); // $ExpectError
-	gfindLastIndex( [ x ], [] ); // $ExpectError
-	gfindLastIndex( [ x ], {} ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], '10' ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], 10 ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], true ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], false ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], null ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], undefined ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], [] ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], {} ); // $ExpectError
 
-	gfindLastIndex( [ x ], '10', {} ); // $ExpectError
-	gfindLastIndex( [ x ], 10, {} ); // $ExpectError
-	gfindLastIndex( [ x ], true, {} ); // $ExpectError
-	gfindLastIndex( [ x ], false, {} ); // $ExpectError
-	gfindLastIndex( [ x ], null, {} ); // $ExpectError
-	gfindLastIndex( [ x ], undefined, {} ); // $ExpectError
-	gfindLastIndex( [ x ], [], {} ); // $ExpectError
-	gfindLastIndex( [ x ], {}, {} ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], '10', {} ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], 10, {} ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], true, {} ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], false, {} ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], null, {} ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], undefined, {} ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], [], {} ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], {}, {} ); // $ExpectError
 }
 
 // The compiler throws an error if the function is provided an unsupported number of arguments...
 {
 	const x = zeros( [ 10 ], {
 		'dtype': 'generic'
 	});
+	const fromIndex = scalar2ndarray( 0, {
+		'dtype': 'generic'
+	});
 
 	gfindLastIndex(); // $ExpectError
-	gfindLastIndex( [ x ], clbk, {}, {} ); // $ExpectError
+	gfindLastIndex( [ x, fromIndex ], clbk, {}, {} ); // $ExpectError
 }

lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-last-index/examples/index.js

@@ -19,6 +19,7 @@
 'use strict';
 
 var discreteUniform = require( '@stdlib/random/discrete-uniform' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var gfindLastIndex = require( './../lib' );
 
@@ -33,5 +34,9 @@ var opts = {
 var x = discreteUniform( [ 10 ], -100, 100, opts );
 console.log( ndarray2array( x ) );
 
-var idx = gfindLastIndex( [ x ], isEven );
+var fromIndex = scalar2ndarray( 9, {
+	'dtype': 'generic'
+});
+
+var idx = gfindLastIndex( [ x, fromIndex ], isEven );
 console.log( idx );

lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-last-index/lib/index.js

@@ -24,6 +24,7 @@
 * @module @stdlib/blas/ext/base/ndarray/gfind-last-index
 *
 * @example
+* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 * var vector = require( '@stdlib/ndarray/vector/ctor' );
 * var gfindLastIndex = require( '@stdlib/blas/ext/base/ndarray/gfind-last-index' );
 *
@@ -33,7 +34,11 @@
 *
 * var x = vector( [ 1.0, 3.0, 4.0, 2.0 ], 'generic' );
 *
-* var v = gfindLastIndex( [ x ], clbk );
+* var fromIndex = scalar2ndarray( 3, {
+*     'dtype': 'generic'
+* });
+*
+* var v = gfindLastIndex( [ x, fromIndex ], clbk );
 * // returns 3
 */
 

lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-last-index/lib/main.js

@@ -20,7 +20,9 @@
 
 // MODULES //
 
+var ndarraylike2scalar = require( '@stdlib/ndarray/base/ndarraylike2scalar' );
 var numelDimension = require( '@stdlib/ndarray/base/numel-dimension' );
+var clipUpperIndex = require( '@stdlib/ndarray/base/clip-upper-index' );
 var getStride = require( '@stdlib/ndarray/base/stride' );
 var getOffset = require( '@stdlib/ndarray/base/offset' );
 var getData = require( '@stdlib/ndarray/base/data-buffer' );
@@ -37,13 +39,15 @@ var strided = require( '@stdlib/blas/ext/base/gfind-last-index' ).ndarray;
 * -   The function expects the following ndarrays:
 *
 *     -   a one-dimensional input ndarray.
+*     -   a zero-dimensional ndarray containing the index from which to begin searching.
 *
 * @param {ArrayLikeObject<Object>} arrays - array-like object containing ndarrays
 * @param {Function} clbk - callback function
 * @param {*} [thisArg] - callback execution context
 * @returns {integer} index
 *
 * @example
+* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 * var vector = require( '@stdlib/ndarray/vector/ctor' );
 *
 * function isEven( v ) {
@@ -52,12 +56,27 @@ var strided = require( '@stdlib/blas/ext/base/gfind-last-index' ).ndarray;
 *
 * var x = vector( [ 1.0, 3.0, 4.0, 2.0 ], 'generic' );
 *
-* var v = gfindLastIndex( [ x ], isEven );
+* var fromIndex = scalar2ndarray( 3, {
+*     'dtype': 'generic'
+* });
+*
+* var v = gfindLastIndex( [ x, fromIndex ], isEven );
 * // returns 3
 */
 function gfindLastIndex( arrays, clbk, thisArg ) {
-	var x = arrays[ 0 ];
-	return strided( numelDimension( x, 0 ), getData( x ), getStride( x, 0 ), getOffset( x ), wrapper, null ); // eslint-disable-line max-len
+	var fromIndex;
+	var N;
+	var x;
+
+	x = arrays[ 0 ];
+	fromIndex = ndarraylike2scalar( arrays[ 1 ] );
+
+	N = numelDimension( x, 0 );
+	fromIndex = clipUpperIndex( fromIndex, ( fromIndex < 0 ) ? N : N-1 );
+	if ( fromIndex < 0 ) {
+		return -1;
+	}
+	return strided( fromIndex+1, getData( x ), getStride( x, 0 ), getOffset( x ), wrapper, null ); // eslint-disable-line max-len
 
 	/**
 	* Invokes a provided callback.
@@ -70,7 +89,7 @@ function gfindLastIndex( arrays, clbk, thisArg ) {
 	* @returns {*} result
 	*/
 	function wrapper( value, aidx ) {
-		return clbk.call( thisArg, value, aidx, x );
+		return clbk.call( thisArg, value, fromIndex - aidx, x );
 	}
 }