feat!: add fromIndex support to blas/ext/base/ndarray/slast-index-of-falsy

BREAKING CHANGE: add `fromIndex` support

To maintain previous behavior, provide an additional zero-dimensional ndarray containing the index of the last element.

PR-URL: #14653
Reviewed-by: Athan Reines <kgryte@gmail.com>
Closes: stdlib-js/metr-issue-tracker#1198

Author: headlessNode

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

@@ -42,25 +42,38 @@ Returns the index of the last falsy element in a one-dimensional single-precisio
 
 ```javascript
 var Float32Vector = require( '@stdlib/ndarray/vector/float32' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 
 var x = new Float32Vector( [ 1.0, 0.0, 3.0, 0.0 ] );
 
-var idx = slastIndexOfFalsy( [ x ] );
+var fromIndex = scalar2ndarray( 3, {
+    'dtype': 'generic'
+});
+
+var idx = slastIndexOfFalsy( [ x, fromIndex ] );
 // returns 3
 ```
 
 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.
 
 If the function is unable to find a falsy element, the function returns `-1`.
 
 ```javascript
 var Float32Vector = require( '@stdlib/ndarray/vector/float32' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 
 var x = new Float32Vector( [ 1.0, 2.0, 3.0, 4.0 ] );
 
-var idx = slastIndexOfFalsy( [ x ] );
+var fromIndex = scalar2ndarray( 3, {
+    'dtype': 'generic'
+});
+
+var idx = slastIndexOfFalsy( [ x, fromIndex ] );
 // returns -1
 ```
 
@@ -73,6 +86,7 @@ var idx = slastIndexOfFalsy( [ x ] );
 ## Notes
 
 -   The function treats `NaN` values as falsy.
+-   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>
 
@@ -86,6 +100,7 @@ var idx = slastIndexOfFalsy( [ x ] );
 
 ```javascript
 var bernoulli = require( '@stdlib/random/bernoulli' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var slastIndexOfFalsy = require( '@stdlib/blas/ext/base/ndarray/slast-index-of-falsy' );
 
@@ -96,7 +111,11 @@ var opts = {
 var x = bernoulli( [ 10 ], 0.7, opts );
 console.log( ndarray2array( x ) );
 
-var idx = slastIndexOfFalsy( [ x ] );
+var fromIndex = scalar2ndarray( 9, {
+    'dtype': 'generic'
+});
+
+var idx = slastIndexOfFalsy( [ x, fromIndex ] );
 console.log( idx );
 ```
 

lib/node_modules/@stdlib/blas/ext/base/ndarray/slast-index-of-falsy/benchmark/benchmark.js

@@ -22,6 +22,7 @@
 
 var bench = require( '@stdlib/bench' );
 var ones = require( '@stdlib/ndarray/ones' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var isInteger = require( '@stdlib/assert/is-integer' ).isPrimitive;
 var pow = require( '@stdlib/math/base/special/pow' );
 var format = require( '@stdlib/string/format' );
@@ -46,7 +47,13 @@ var options = {
 * @returns {Function} benchmark function
 */
 function createBenchmark( len ) {
-	var x = ones( [ len ], options );
+	var fromIndex;
+	var x;
+
+	x = ones( [ len ], options );
+	fromIndex = scalar2ndarray( len - 1, {
+		'dtype': 'generic'
+	});
 	return benchmark;
 
 	/**
@@ -61,7 +68,7 @@ function createBenchmark( len ) {
 
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
-			out = slastIndexOfFalsy( [ x ] );
+			out = slastIndexOfFalsy( [ x, fromIndex ] );
 			if ( out !== out ) {
 				b.fail( 'should return an integer' );
 			}

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

@@ -3,6 +3,10 @@
     Returns the index of the last falsy element in a one-dimensional single-
     precision floating-point ndarray.
 
+    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 unable to find a falsy element, the function returns `-1`.
 
     Parameters
@@ -11,6 +15,8 @@
         Array-like object containing the following ndarrays:
 
         - a one-dimensional input ndarray.
+        - a zero-dimensional ndarray containing the index from which to begin
+        searching.
 
     Returns
     -------
@@ -20,7 +26,8 @@
     Examples
     --------
     > var x = new {{alias:@stdlib/ndarray/vector/float32}}( [ 1.0, 0.0, 0.0 ] );
-    > {{alias}}( [ x ] )
+    > var i = {{alias:@stdlib/ndarray/from-scalar}}( 2, { 'dtype': 'generic' } );
+    > {{alias}}( [ x, i ] )
     2
 
     See Also

lib/node_modules/@stdlib/blas/ext/base/ndarray/slast-index-of-falsy/docs/types/index.d.ts

@@ -20,7 +20,7 @@
 
 /// <reference types="@stdlib/types"/>
 
-import { float32ndarray } from '@stdlib/types/ndarray';
+import { float32ndarray, typedndarray } from '@stdlib/types/ndarray';
 
 /**
 * Returns the index of the last falsy element in a one-dimensional single-precision floating-point ndarray.
@@ -30,19 +30,25 @@ import { float32ndarray } from '@stdlib/types/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 arrays - array-like object containing ndarrays
 * @returns index
 *
 * @example
 * var Float32Vector = require( '@stdlib/ndarray/vector/float32' );
+* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 *
 * var x = new Float32Vector( [ 1.0, 0.0, 3.0, 0.0 ] );
 *
-* var v = slastIndexOfFalsy( [ x ] );
+* var fromIndex = scalar2ndarray( 3, {
+*     'dtype': 'generic'
+* });
+*
+* var v = slastIndexOfFalsy( [ x, fromIndex ] );
 * // returns 3
 */
-declare function slastIndexOfFalsy( arrays: [ float32ndarray ] ): number;
+declare function slastIndexOfFalsy( arrays: [ float32ndarray, typedndarray<number> ] ): number;
 
 
 // EXPORTS //

lib/node_modules/@stdlib/blas/ext/base/ndarray/slast-index-of-falsy/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 slastIndexOfFalsy = require( './index' );
 
 
@@ -29,8 +30,11 @@ import slastIndexOfFalsy = require( './index' );
 	const x = zeros( [ 10 ], {
 		'dtype': 'float32'
 	});
+	const fromIndex = scalar2ndarray( 0, {
+		'dtype': 'generic'
+	});
 
-	slastIndexOfFalsy( [ x ] ); // $ExpectType number
+	slastIndexOfFalsy( [ x, fromIndex ] ); // $ExpectType number
 }
 
 // The compiler throws an error if the function is provided a first argument which is not an array of ndarrays...
@@ -51,7 +55,10 @@ import slastIndexOfFalsy = require( './index' );
 	const x = zeros( [ 10 ], {
 		'dtype': 'float32'
 	});
+	const fromIndex = scalar2ndarray( 0, {
+		'dtype': 'generic'
+	});
 
 	slastIndexOfFalsy(); // $ExpectError
-	slastIndexOfFalsy( [ x ], {} ); // $ExpectError
+	slastIndexOfFalsy( [ x, fromIndex ], {} ); // $ExpectError
 }

lib/node_modules/@stdlib/blas/ext/base/ndarray/slast-index-of-falsy/examples/index.js

@@ -19,6 +19,7 @@
 'use strict';
 
 var bernoulli = require( '@stdlib/random/bernoulli' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var slastIndexOfFalsy = require( './../lib' );
 
@@ -29,5 +30,9 @@ var opts = {
 var x = bernoulli( [ 10 ], 0.7, opts );
 console.log( ndarray2array( x ) );
 
-var idx = slastIndexOfFalsy( [ x ] );
+var fromIndex = scalar2ndarray( 9, {
+	'dtype': 'generic'
+});
+
+var idx = slastIndexOfFalsy( [ x, fromIndex ] );
 console.log( idx );

lib/node_modules/@stdlib/blas/ext/base/ndarray/slast-index-of-falsy/lib/index.js

@@ -25,11 +25,16 @@
 *
 * @example
 * var Float32Vector = require( '@stdlib/ndarray/vector/float32' );
+* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 * var slastIndexOfFalsy = require( '@stdlib/blas/ext/base/ndarray/slast-index-of-falsy' );
 *
 * var x = new Float32Vector( [ 1.0, 0.0, 3.0, 0.0 ] );
 *
-* var v = slastIndexOfFalsy( [ x ] );
+* var fromIndex = scalar2ndarray( 3, {
+*     'dtype': 'generic'
+* });
+*
+* var v = slastIndexOfFalsy( [ x, fromIndex ] );
 * // returns 3
 */
 

lib/node_modules/@stdlib/blas/ext/base/ndarray/slast-index-of-falsy/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,21 +39,38 @@ var strided = require( '@stdlib/blas/ext/base/slast-index-of-falsy' ).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
 * @returns {integer} index
 *
 * @example
 * var Float32Vector = require( '@stdlib/ndarray/vector/float32' );
+* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 *
 * var x = new Float32Vector( [ 1.0, 0.0, 3.0, 0.0 ] );
 *
-* var v = slastIndexOfFalsy( [ x ] );
+* var fromIndex = scalar2ndarray( 3, {
+*     'dtype': 'generic'
+* });
+*
+* var v = slastIndexOfFalsy( [ x, fromIndex ] );
 * // returns 3
 */
 function slastIndexOfFalsy( arrays ) {
-	var x = arrays[ 0 ];
-	return strided( numelDimension( x, 0 ), getData( x ), getStride( x, 0 ), getOffset( x ) );
+	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 ) );
 }