feat!: add start and end parameter support to blas/ext/base/ndarray/dfill-nan

BREAKING CHANGE: add `start` and `end` support

To maintain previous behavior, provide additional zero-dimensional ndarrays containing the value `0` and the number of elements, respectively.

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

Author: headlessNode

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfill-nan/README.md

@@ -50,8 +50,16 @@ var alpha = scalar2ndarray( 0.0, {
     'dtype': 'float64'
 });
 
-dfillNaN( [ x, alpha ] );
-// x => <ndarray>[ 0.0, -2.0, 3.0, 0.0, 4.0, -6.0 ]
+var start = scalar2ndarray( 0, {
+    'dtype': 'generic'
+});
+
+var end = scalar2ndarray( 2, {
+    'dtype': 'generic'
+});
+
+dfillNaN( [ x, alpha, start, end ] );
+// x => <ndarray>[ 0.0, -2.0, 3.0, NaN, 4.0, -6.0 ]
 ```
 
 The function has the following parameters:
@@ -60,6 +68,8 @@ The function has the following parameters:
 
     -   a one-dimensional input ndarray.
     -   a zero-dimensional ndarray containing the scalar constant.
+    -   a zero-dimensional ndarray containing the starting index (inclusive).
+    -   a zero-dimensional ndarray containing the ending index (exclusive).
 
 </section>
 
@@ -70,6 +80,7 @@ The function has the following parameters:
 ## Notes
 
 -   The input ndarray is modified **in-place** (i.e., the input ndarray is **mutated**).
+-   If a specified `start` or `end` index is negative, the function resolves the respective index by counting backward from the last element (where `-1` refers to the last element).
 
 </section>
 
@@ -92,13 +103,23 @@ var opts = {
     'dtype': 'float64'
 };
 
-var x = nans( [ 10 ], opts );
+var x = nans( [ 20 ], opts );
 console.log( ndarray2array( x ) );
 
 var alpha = scalar2ndarray( 5.0, opts );
 console.log( 'Alpha: %d', ndarraylike2scalar( alpha ) );
 
-dfillNaN( [ x, alpha ] );
+var start = scalar2ndarray( 5, {
+    'dtype': 'generic'
+});
+console.log( 'Start Index: %d', ndarraylike2scalar( start ) );
+
+var end = scalar2ndarray( 15, {
+    'dtype': 'generic'
+});
+console.log( 'End Index: %d', ndarraylike2scalar( end ) );
+
+dfillNaN( [ x, alpha, start, end ] );
 console.log( ndarray2array( x ) );
 ```
 

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfill-nan/benchmark/benchmark.js

@@ -63,10 +63,18 @@ function clbk( value, indices ) {
 */
 function createBenchmark( len ) {
 	var alpha;
+	var start;
+	var end;
 	var x;
 
 	x = fillBy( zeros( [ len ], options ), clbk );
 	alpha = scalar2ndarray( 0.0, options );
+	start = scalar2ndarray( 0, {
+		'dtype': 'generic'
+	});
+	end = scalar2ndarray( len, {
+		'dtype': 'generic'
+	});
 	return benchmark;
 
 	/**
@@ -81,7 +89,7 @@ function createBenchmark( len ) {
 
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
-			out = dfillNaN( [ x, alpha ] );
+			out = dfillNaN( [ x, alpha, start, end ] );
 			if ( typeof out !== 'object' ) {
 				b.fail( 'should return an ndarray' );
 			}

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfill-nan/docs/repl.txt

@@ -6,13 +6,19 @@
     The input ndarray is modified *in-place* (i.e., the input ndarray is
     *mutated*).
 
+    If a specified `start` or `end` index is negative, the function resolves
+    the respective index by counting backward from the last element (where `-1`
+    refers to the last element).
+
     Parameters
     ----------
     arrays: ArrayLikeObject<ndarray>
         Array-like object containing the following ndarrays:
 
         - a one-dimensional input ndarray.
         - a zero-dimensional ndarray containing the scalar constant.
+        - a zero-dimensional ndarray containing the starting index (inclusive).
+        - a zero-dimensional ndarray containing the ending index (exclusive).
 
     Returns
     -------
@@ -23,8 +29,10 @@
     --------
     > var x = new {{alias:@stdlib/ndarray/vector/float64}}( [ NaN, -2.0, 3.0, NaN, 4.0, -6.0 ] );
     > var alpha = {{alias:@stdlib/ndarray/from-scalar}}( 0.0, { 'dtype': 'float64' } );
-    > {{alias}}( [ x, alpha ] )
-    <ndarray>[ 0.0, -2.0, 3.0, 0.0, 4.0, -6.0 ]
+    > var st = {{alias:@stdlib/ndarray/from-scalar}}( 0, { 'dtype': 'generic' } );
+    > var en = {{alias:@stdlib/ndarray/from-scalar}}( 2, { 'dtype': 'generic' } );
+    > {{alias}}( [ x, alpha, st, en ] )
+    <ndarray>[ 0.0, -2.0, 3.0, NaN, 4.0, -6.0 ]
 
     See Also
     --------

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

@@ -31,6 +31,8 @@ import { float64ndarray, typedndarray } from '@stdlib/types/ndarray';
 *
 *     -   a one-dimensional input ndarray.
 *     -   a zero-dimensional ndarray containing the scalar constant.
+*     -   a zero-dimensional ndarray containing the starting index (inclusive).
+*     -   a zero-dimensional ndarray containing the ending index (exclusive).
 *
 * @param arrays - array-like object containing ndarrays
 * @returns input ndarray
@@ -45,10 +47,18 @@ import { float64ndarray, typedndarray } from '@stdlib/types/ndarray';
 *     'dtype': 'float64'
 * });
 *
-* var out = dfillNaN( [ x, alpha ] );
-* // returns <ndarray>[ 0.0, -2.0, 3.0, 0.0, 4.0, -6.0 ]
+* var start = scalar2ndarray( 0, {
+*     'dtype': 'generic'
+* });
+*
+* var end = scalar2ndarray( 2, {
+*     'dtype': 'generic'
+* });
+*
+* var out = dfillNaN( [ x, alpha, start, end ] );
+* // returns <ndarray>[ 0.0, -2.0, 3.0, NaN, 4.0, -6.0 ]
 */
-declare function dfillNaN( arrays: [ float64ndarray, typedndarray<number> ] ): float64ndarray;
+declare function dfillNaN( arrays: [ float64ndarray, typedndarray<number>, typedndarray<number>, typedndarray<number> ] ): float64ndarray;
 
 
 // EXPORTS //

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfill-nan/docs/types/test.ts

@@ -33,8 +33,14 @@ import dfillNaN = require( './index' );
 	const alpha = scalar2ndarray( 0.0, {
 		'dtype': 'float64'
 	});
+	const start = scalar2ndarray( 0, {
+		'dtype': 'generic'
+	});
+	const end = scalar2ndarray( 10, {
+		'dtype': 'generic'
+	});
 
-	dfillNaN( [ x, alpha ] ); // $ExpectType float64ndarray
+	dfillNaN( [ x, alpha, start, end ] ); // $ExpectType float64ndarray
 }
 
 // The compiler throws an error if the function is provided a first argument which is not an array of ndarrays...
@@ -58,7 +64,13 @@ import dfillNaN = require( './index' );
 	const alpha = scalar2ndarray( 0.0, {
 		'dtype': 'float64'
 	});
+	const start = scalar2ndarray( 0, {
+		'dtype': 'generic'
+	});
+	const end = scalar2ndarray( 10, {
+		'dtype': 'generic'
+	});
 
 	dfillNaN(); // $ExpectError
-	dfillNaN( [ x, alpha ], {} ); // $ExpectError
+	dfillNaN( [ x, alpha, start, end ], {} ); // $ExpectError
 }

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfill-nan/examples/index.js

@@ -28,11 +28,21 @@ var opts = {
 	'dtype': 'float64'
 };
 
-var x = nans( [ 10 ], opts );
+var x = nans( [ 20 ], opts );
 console.log( ndarray2array( x ) );
 
 var alpha = scalar2ndarray( 5.0, opts );
 console.log( 'Alpha: %d', ndarraylike2scalar( alpha ) );
 
-dfillNaN( [ x, alpha ] );
+var start = scalar2ndarray( 5, {
+	'dtype': 'generic'
+});
+console.log( 'Start Index: %d', ndarraylike2scalar( start ) );
+
+var end = scalar2ndarray( 15, {
+	'dtype': 'generic'
+});
+console.log( 'End Index: %d', ndarraylike2scalar( end ) );
+
+dfillNaN( [ x, alpha, start, end ] );
 console.log( ndarray2array( x ) );

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfill-nan/lib/index.js

@@ -34,8 +34,16 @@
 *     'dtype': 'float64'
 * });
 *
-* var out = dfillNaN( [ x, alpha ] );
-* // returns <ndarray>[ 0.0, -2.0, 3.0, 0.0, 4.0, -6.0 ]
+* var start = scalar2ndarray( 0, {
+*     'dtype': 'generic'
+* });
+*
+* var end = scalar2ndarray( 2, {
+*     'dtype': 'generic'
+* });
+*
+* var out = dfillNaN( [ x, alpha, start, end ] );
+* // returns <ndarray>[ 0.0, -2.0, 3.0, NaN, 4.0, -6.0 ]
 */
 
 // MODULES //

lib/node_modules/@stdlib/blas/ext/base/ndarray/dfill-nan/lib/main.js

@@ -21,11 +21,12 @@
 // MODULES //
 
 var numelDimension = require( '@stdlib/ndarray/base/numel-dimension' );
+var clipIndex = require( '@stdlib/ndarray/base/clip-index' );
 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/dfill-nan' ).ndarray;
 var ndarraylike2scalar = require( '@stdlib/ndarray/base/ndarraylike2scalar' );
+var strided = require( '@stdlib/blas/ext/base/dfill-nan' ).ndarray;
 
 
 // MAIN //
@@ -39,6 +40,8 @@ var ndarraylike2scalar = require( '@stdlib/ndarray/base/ndarraylike2scalar' );
 *
 *     -   a one-dimensional input ndarray.
 *     -   a zero-dimensional ndarray containing the scalar constant.
+*     -   a zero-dimensional ndarray containing the starting index (inclusive).
+*     -   a zero-dimensional ndarray containing the ending index (exclusive).
 *
 * @param {ArrayLikeObject<Object>} arrays - array-like object containing ndarrays
 * @returns {ndarray} input ndarray
@@ -53,16 +56,39 @@ var ndarraylike2scalar = require( '@stdlib/ndarray/base/ndarraylike2scalar' );
 *     'dtype': 'float64'
 * });
 *
-* var out = dfillNaN( [ x, alpha ] );
-* // returns <ndarray>[ 0.0, -2.0, 3.0, 0.0, 4.0, -6.0 ]
+* var start = scalar2ndarray( 0, {
+*     'dtype': 'generic'
+* });
+*
+* var end = scalar2ndarray( 2, {
+*     'dtype': 'generic'
+* });
+*
+* var out = dfillNaN( [ x, alpha, start, end ] );
+* // returns <ndarray>[ 0.0, -2.0, 3.0, NaN, 4.0, -6.0 ]
 */
 function dfillNaN( arrays ) {
+	var stride;
+	var offset;
 	var alpha;
+	var start;
+	var end;
+	var N;
 	var x;
 
 	x = arrays[ 0 ];
 	alpha = ndarraylike2scalar( arrays[ 1 ] );
-	strided( numelDimension( x, 0 ), alpha, getData( x ), getStride( x, 0 ), getOffset( x ) ); // eslint-disable-line max-len
+
+	N = numelDimension( x, 0 );
+	start = clipIndex( ndarraylike2scalar( arrays[ 2 ] ), N );
+	end = clipIndex( ndarraylike2scalar( arrays[ 3 ] ), N );
+	if ( start >= end ) {
+		return x;
+	}
+	stride = getStride( x, 0 );
+	offset = getOffset( x ) + ( stride*start );
+
+	strided( end-start, alpha, getData( x ), stride, offset );
 	return x;
 }