feat: add fromIndex support to blas/ext/base/ndarray/dfirst-index-equal

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-equal/README.md

@@ -42,11 +42,16 @@ Returns the index of the first element in a one-dimensional double-precision flo
 
 ```javascript
 var Float64Vector = require( '@stdlib/ndarray/vector/float64' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 
 var x = new Float64Vector( [ 1.0, 2.0, 3.0, 4.0 ] );
 var y = new Float64Vector( [ 0.0, 0.0, 3.0, 0.0 ] );
 
-var idx = dfirstIndexEqual( [ x, y ] );
+var fromIndex = scalar2ndarray( 0, {
+    'dtype': 'generic'
+});
+
+var idx = dfirstIndexEqual( [ x, y, fromIndex ] );
 // returns 2
 ```
 
@@ -56,16 +61,22 @@ The function has the following parameters:
 
     -   first one-dimensional input ndarray.
     -   second one-dimensional input ndarray.
+    -   a zero-dimensional ndarray containing the index from which to begin searching.
 
 If the function is unable to find an element in the first one-dimensional input ndarray equal to a corresponding element in the second one-dimensional input ndarray, the function returns `-1`.
 
 ```javascript
 var Float64Vector = require( '@stdlib/ndarray/vector/float64' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 
 var x = new Float64Vector( [ 1.0, 2.0, 3.0, 4.0 ] );
 var y = new Float64Vector( [ 5.0, 6.0, 7.0, 8.0 ] );
 
-var idx = dfirstIndexEqual( [ x, y ] );
+var fromIndex = scalar2ndarray( 0, {
+    'dtype': 'generic'
+});
+
+var idx = dfirstIndexEqual( [ x, y, fromIndex ] );
 // returns -1
 ```
 
@@ -77,6 +88,7 @@ var idx = dfirstIndexEqual( [ x, y ] );
 
 ## Notes
 
+-   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).
 -   When comparing elements, 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>
@@ -91,7 +103,9 @@ var idx = dfirstIndexEqual( [ x, y ] );
 
 ```javascript
 var discreteUniform = require( '@stdlib/random/discrete-uniform' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var ndarray2array = require( '@stdlib/ndarray/to-array' );
+var ndarraylike2scalar = require( '@stdlib/ndarray/ndarraylike2scalar' );
 var dfirstIndexEqual = require( '@stdlib/blas/ext/base/ndarray/dfirst-index-equal' );
 
 var opts = {
@@ -103,7 +117,12 @@ console.log( ndarray2array( x ) );
 var y = discreteUniform( [ 10 ], 0, 10, opts );
 console.log( ndarray2array( y ) );
 
-var idx = dfirstIndexEqual( [ x, y ] );
+var fromIndex = scalar2ndarray( 0, {
+    'dtype': 'generic'
+});
+console.log( 'From Index:', ndarraylike2scalar( fromIndex ) );
+
+var idx = dfirstIndexEqual( [ x, y, fromIndex ] );
 console.log( idx );
 ```
 

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-equal/benchmark/benchmark.js

@@ -23,6 +23,7 @@
 var bench = require( '@stdlib/bench' );
 var isInteger = require( '@stdlib/assert/is-integer' ).isPrimitive;
 var pow = require( '@stdlib/math/base/special/pow' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var oneTo = require( '@stdlib/blas/ext/one-to' );
 var zeros = require( '@stdlib/ndarray/zeros' );
 var format = require( '@stdlib/string/format' );
@@ -47,8 +48,15 @@ var options = {
 * @returns {Function} benchmark function
 */
 function createBenchmark( len ) {
-	var x = oneTo( [ len ], options );
-	var y = zeros( [ len ], options );
+	var fromIndex;
+	var x;
+	var y;
+
+	x = oneTo( [ len ], options );
+	y = zeros( [ len ], options );
+	fromIndex = scalar2ndarray( 0, {
+		'dtype': 'generic'
+	});
 	return benchmark;
 
 	/**
@@ -63,7 +71,7 @@ function createBenchmark( len ) {
 
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
-			out = dfirstIndexEqual( [ x, y ] );
+			out = dfirstIndexEqual( [ x, y, fromIndex ] );
 			if ( out !== out ) {
 				b.fail( 'should return an integer' );
 			}

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-equal/docs/repl.txt

@@ -4,6 +4,10 @@
     precision floating-point ndarray equal to a corresponding element in
     another one-dimensional double-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).
+
     When comparing elements, 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.
@@ -15,6 +19,8 @@
 
         - first one-dimensional input ndarray.
         - second one-dimensional input ndarray.
+        - a zero-dimensional ndarray containing the index from which to begin
+        searching.
 
     Returns
     -------
@@ -25,7 +31,8 @@
     --------
     > var x = new {{alias:@stdlib/ndarray/vector/float64}}( [ 1.0, 2.0, 3.0, 4.0 ] );
     > var y = new {{alias:@stdlib/ndarray/vector/float64}}( [ 0.0, 0.0, 3.0, 0.0 ] );
-    > {{alias}}( [ x, y ] )
+    > var i = {{alias:@stdlib/ndarray/from-scalar}}( 0, { 'dtype': 'generic' } );
+    > {{alias}}( [ x, y, i ] )
     2
 
     See Also

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

@@ -20,7 +20,7 @@
 
 /// <reference types="@stdlib/types"/>
 
-import { float64ndarray } from '@stdlib/types/ndarray';
+import { float64ndarray, typedndarray } from '@stdlib/types/ndarray';
 
 /**
 * Returns the index of the first element in a one-dimensional double-precision floating-point ndarray equal to a corresponding element in another one-dimensional double-precision floating-point ndarray.
@@ -31,6 +31,7 @@ import { float64ndarray } from '@stdlib/types/ndarray';
 *
 *     -   first one-dimensional input ndarray.
 *     -   second one-dimensional input ndarray.
+*     -   a zero-dimensional ndarray containing the index from which to begin searching.
 *
 * -   When comparing elements, 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.
 *
@@ -39,14 +40,19 @@ import { float64ndarray } from '@stdlib/types/ndarray';
 *
 * @example
 * var Float64Vector = require( '@stdlib/ndarray/vector/float64' );
+* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 *
 * var x = new Float64Vector( [ 1.0, 2.0, 3.0, 4.0 ] );
 * var y = new Float64Vector( [ 0.0, 0.0, 3.0, 0.0 ] );
 *
-* var idx = dfirstIndexEqual( [ x, y ] );
+* var fromIndex = scalar2ndarray( 0, {
+*     'dtype': 'generic'
+* });
+*
+* var idx = dfirstIndexEqual( [ x, y, fromIndex ] );
 * // returns 2
 */
-declare function dfirstIndexEqual( arrays: [ float64ndarray, float64ndarray ] ): number;
+declare function dfirstIndexEqual( arrays: [ float64ndarray, float64ndarray, typedndarray<number> ] ): number;
 
 
 // EXPORTS //

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-equal/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 dfirstIndexEqual = require( './index' );
 
 
@@ -32,8 +33,11 @@ import dfirstIndexEqual = require( './index' );
 	const y = zeros( [ 10 ], {
 		'dtype': 'float64'
 	});
+	const fromIndex = scalar2ndarray( 0, {
+		'dtype': 'generic'
+	});
 
-	dfirstIndexEqual( [ x, y ] ); // $ExpectType number
+	dfirstIndexEqual( [ x, y, fromIndex ] ); // $ExpectType number
 }
 
 // The compiler throws an error if the function is provided a first argument which is not an array of ndarrays...
@@ -57,7 +61,10 @@ import dfirstIndexEqual = require( './index' );
 	const y = zeros( [ 10 ], {
 		'dtype': 'float64'
 	});
+	const fromIndex = scalar2ndarray( 0, {
+		'dtype': 'generic'
+	});
 
 	dfirstIndexEqual(); // $ExpectError
-	dfirstIndexEqual( [ x, y ], {} ); // $ExpectError
+	dfirstIndexEqual( [ x, y, fromIndex ], {} ); // $ExpectError
 }

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-equal/examples/index.js

@@ -19,7 +19,9 @@
 'use strict';
 
 var discreteUniform = require( '@stdlib/random/discrete-uniform' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var ndarray2array = require( '@stdlib/ndarray/to-array' );
+var ndarraylike2scalar = require( '@stdlib/ndarray/ndarraylike2scalar' );
 var dfirstIndexEqual = require( './../lib' );
 
 var opts = {
@@ -31,5 +33,10 @@ console.log( ndarray2array( x ) );
 var y = discreteUniform( [ 10 ], 0, 10, opts );
 console.log( ndarray2array( y ) );
 
-var idx = dfirstIndexEqual( [ x, y ] );
+var fromIndex = scalar2ndarray( 0, {
+	'dtype': 'generic'
+});
+console.log( 'From Index:', ndarraylike2scalar( fromIndex ) );
+
+var idx = dfirstIndexEqual( [ x, y, fromIndex ] );
 console.log( idx );

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-equal/lib/index.js

@@ -25,12 +25,17 @@
 *
 * @example
 * var Float64Vector = require( '@stdlib/ndarray/vector/float64' );
+* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 * var dfirstIndexEqual = require( '@stdlib/blas/ext/base/ndarray/dfirst-index-equal' );
 *
 * var x = new Float64Vector( [ 1.0, 2.0, 3.0, 4.0 ] );
 * var y = new Float64Vector( [ 0.0, 0.0, 3.0, 0.0 ] );
 *
-* var idx = dfirstIndexEqual( [ x, y ] );
+* var fromIndex = scalar2ndarray( 0, {
+*     'dtype': 'generic'
+* });
+*
+* var idx = dfirstIndexEqual( [ x, y, fromIndex ] );
 * // returns 2
 */
 

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-equal/lib/main.js

@@ -25,6 +25,7 @@ var getStride = require( '@stdlib/ndarray/base/stride' );
 var getOffset = require( '@stdlib/ndarray/base/offset' );
 var getData = require( '@stdlib/ndarray/base/data-buffer' );
 var strided = require( '@stdlib/blas/ext/base/dfirst-index-equal' ).ndarray;
+var ndarraylike2scalar = require( '@stdlib/ndarray/base/ndarraylike2scalar' );
 
 
 // MAIN //
@@ -38,6 +39,7 @@ var strided = require( '@stdlib/blas/ext/base/dfirst-index-equal' ).ndarray;
 *
 *     -   first one-dimensional input ndarray.
 *     -   second one-dimensional input ndarray.
+*     -   a zero-dimensional ndarray containing the index from which to begin searching.
 *
 * -   When comparing elements, 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.
 *
@@ -46,17 +48,49 @@ var strided = require( '@stdlib/blas/ext/base/dfirst-index-equal' ).ndarray;
 *
 * @example
 * var Float64Vector = require( '@stdlib/ndarray/vector/float64' );
+* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 *
 * var x = new Float64Vector( [ 1.0, 2.0, 3.0, 4.0 ] );
 * var y = new Float64Vector( [ 0.0, 0.0, 3.0, 0.0 ] );
 *
-* var idx = dfirstIndexEqual( [ x, y ] );
+* var fromIndex = scalar2ndarray( 0, {
+*     'dtype': 'generic'
+* });
+*
+* var idx = dfirstIndexEqual( [ x, y, fromIndex ] );
 * // returns 2
 */
 function dfirstIndexEqual( arrays ) {
-	var x = arrays[ 0 ];
-	var y = arrays[ 1 ];
-	return strided( numelDimension( x, 0 ), getData( x ), getStride( x, 0 ), getOffset( x ), getData( y ), getStride( y, 0 ), getOffset( y ) ); // eslint-disable-line max-len
+	var fromIndex;
+	var strideX;
+	var strideY;
+	var idx;
+	var N;
+	var x;
+	var y;
+
+	x = arrays[ 0 ];
+	y = arrays[ 1 ];
+	N = numelDimension( x, 0 );
+	fromIndex = ndarraylike2scalar( arrays[ 2 ] );
+
+	if ( fromIndex < 0 ) {
+		fromIndex += N;
+		if ( fromIndex < 0 ) {
+			fromIndex = 0;
+		}
+	} else if ( fromIndex >= N ) {
+		return -1;
+	}
+	N -= fromIndex;
+	strideX = getStride( x, 0 );
+	strideY = getStride( y, 0 );
+
+	idx = strided( N, getData( x ), strideX, getOffset( x ) + ( strideX*fromIndex ), getData( y ), strideY, getOffset( y ) + ( strideY*fromIndex ) ); // eslint-disable-line max-len
+	if ( idx >= 0 ) {
+		idx += fromIndex;
+	}
+	return idx;
 }