From c1eefaf7fdc31b65b371f913bdd4c5cf33084ff5 Mon Sep 17 00:00:00 2001
From: Muhammad Haris <101793258+headlessNode@users.noreply.github.com>
Date: Fri, 25 Jul 2025 20:01:43 +0000
Subject: [PATCH 1/8] feat: add blas/ext/base/ndarray/gfind-index
---
.../ext/base/ndarray/gfind-index/README.md | 173 +++++++++++++
.../gfind-index/benchmark/benchmark.js | 113 +++++++++
.../base/ndarray/gfind-index/docs/repl.txt | 47 ++++
.../ndarray/gfind-index/docs/types/index.d.ts | 95 +++++++
.../ndarray/gfind-index/docs/types/test.ts | 103 ++++++++
.../ndarray/gfind-index/examples/index.js | 37 +++
.../ext/base/ndarray/gfind-index/lib/index.js | 48 ++++
.../ext/base/ndarray/gfind-index/lib/main.js | 75 ++++++
.../ext/base/ndarray/gfind-index/package.json | 66 +++++
.../ext/base/ndarray/gfind-index/test/test.js | 234 ++++++++++++++++++
10 files changed, 991 insertions(+)
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/README.md
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/benchmark/benchmark.js
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/docs/repl.txt
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/docs/types/index.d.ts
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/docs/types/test.ts
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/examples/index.js
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/lib/index.js
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/lib/main.js
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/package.json
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/test/test.js
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/README.md b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/README.md
new file mode 100644
index 000000000000..544602799c59
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/README.md
@@ -0,0 +1,173 @@
+
+
+# gfindIndex
+
+> Return the index of the first element in a one-dimensional ndarray which passes a test implemented by a predicate function.
+
+
+
+
+
+
+
+
+
+## Usage
+
+```javascript
+var gfindIndex = require( '@stdlib/blas/ext/base/ndarray/gfind-index' );
+```
+
+#### gfindIndex( arrays, clbk\[, thisArg] )
+
+Returns the index of the first element in a one-dimensional ndarray which passes a test implemented by a predicate function.
+
+```javascript
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
+var ndarray = require( '@stdlib/ndarray/base/ctor' );
+
+function isEven( v ) {
+ return v % 2.0 === 0.0;
+}
+
+var xbuf = [ 1.0, 3.0, 4.0, 2.0 ];
+var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
+
+var idx = gfindIndex( [ x ], isEven );
+// returns 2
+```
+
+If the function is unable to find a search element, the function returns `-1`.
+
+```javascript
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
+var ndarray = require( '@stdlib/ndarray/base/ctor' );
+
+var xbuf = [ 1.0, 3.0, 4.0, 2.0 ];
+var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
+
+var searchElement = scalar2ndarray( 10.0, {
+ 'dtype': 'generic'
+});
+
+var fromIndex = scalar2ndarray( 0, {
+ 'dtype': 'generic'
+});
+
+var idx = gfindIndex( [ x, searchElement, fromIndex ] );
+// returns -1
+```
+
+The function has the following parameters:
+
+- **arrays**: array-like object containing a one-dimensional input ndarray.
+- **clbk**: callback function.
+- **thisArg**: callback execution context (_optional_).
+
+The callback function is provided the following arguments:
+
+- **value**: current array element.
+- **idx**: current array element index.
+- **array**: the input ndarray.
+
+To set the callback execution context, provide a `thisArg`.
+
+```javascript
+var ndarray = require( '@stdlib/ndarray/base/ctor' );
+
+function isEven( v ) {
+ this.count += 1;
+ return v % 2.0 === 0.0;
+}
+
+var xbuf = [ 1.0, 3.0, 4.0, 2.0 ];
+var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
+var ctx = {
+ 'count': 0
+};
+
+var v = gfindIndex( [ x ], clbk, ctx );
+// returns 2
+
+var count = ctx.count;
+// returns 3
+```
+
+
+
+
+
+
+
+## Notes
+
+- If provided an empty one-dimensional ndarray, the function returns `-1`.
+- A provided callback function should return a boolean value.
+
+
+
+
+
+
+
+## Examples
+
+
+
+```javascript
+var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
+var ndarray = require( '@stdlib/ndarray/base/ctor' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
+var gfindIndex = require( '@stdlib/blas/ext/base/ndarray/gfind-index' );
+
+function isEven( v ) {
+ return v % 2.0 === 0.0;
+}
+
+var xbuf = discreteUniform( 10, -100, 100, {
+ 'dtype': 'generic'
+});
+var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
+console.log( ndarray2array( x ) );
+
+var idx = gfindIndex( [ x ], isEven );
+console.log( idx );
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/benchmark/benchmark.js b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/benchmark/benchmark.js
new file mode 100644
index 000000000000..7ad7d36a73a8
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/benchmark/benchmark.js
@@ -0,0 +1,113 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var uniform = require( '@stdlib/random/array/uniform' );
+var isnan = require( '@stdlib/math/base/assert/is-nan' );
+var pow = require( '@stdlib/math/base/special/pow' );
+var ndarray = require( '@stdlib/ndarray/base/ctor' );
+var pkg = require( './../package.json' ).name;
+var gfindIndex = require( './../lib' );
+
+
+// VARIABLES //
+
+var options = {
+ 'dtype': 'generic'
+};
+
+
+// FUNCTIONS //
+
+/**
+* Callback function.
+*
+* @private
+* @param {number} v - array element
+* @returns {number} callback result
+*/
+function clbk( v ) {
+ return v < 0.0;
+}
+
+/**
+* Creates a benchmark function.
+*
+* @private
+* @param {PositiveInteger} len - array length
+* @returns {Function} benchmark function
+*/
+function createBenchmark( len ) {
+ var xbuf;
+ var x;
+
+ xbuf = uniform( len, 0.0, 100.0, options );
+ x = new ndarray( options.dtype, xbuf, [ len ], [ 1 ], 0, 'row-major' );
+
+ return benchmark;
+
+ function benchmark( b ) {
+ var v;
+ var i;
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ v = gfindIndex( [ x ], clbk );
+ if ( isnan( v ) ) {
+ b.fail( 'should not return NaN' );
+ }
+ }
+ b.toc();
+ if ( isnan( v ) ) {
+ b.fail( 'should not return NaN' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+ }
+}
+
+
+// MAIN //
+
+/**
+* Main execution sequence.
+*
+* @private
+*/
+function main() {
+ var len;
+ var min;
+ var max;
+ var f;
+ var i;
+
+ min = 1; // 10^min
+ max = 6; // 10^max
+
+ for ( i = min; i <= max; i++ ) {
+ len = pow( 10, i );
+ f = createBenchmark( len );
+ bench( pkg+':len='+len, f );
+ }
+}
+
+main();
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/docs/repl.txt b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/docs/repl.txt
new file mode 100644
index 000000000000..511b4df231cf
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/docs/repl.txt
@@ -0,0 +1,47 @@
+
+{{alias}}( arrays, clbk[, thisArg] )
+ Returns the index of the first element in a one-dimensional ndarray which
+ passes a test implemented by a predicate function.
+
+ If provided an empty ndarray, the function returns `-1`.
+
+ The callback function is provided three arguments:
+
+ - value: current array element.
+ - index: current array index.
+ - array: the input ndarray.
+
+ The callback function should return a boolean value.
+
+ Parameters
+ ----------
+ arrays: ArrayLikeObject
+ Array-like object containing a one-dimensional input ndarray.
+
+ clbk: Function
+ Callback function.
+
+ thisArg: any (optional)
+ Callback execution context.
+
+ Returns
+ -------
+ out: integer
+ Index.
+
+ Examples
+ --------
+ > var xbuf = [ 1.0, -2.0, 2.0 ];
+ > var dt = 'generic';
+ > var sh = [ xbuf.length ];
+ > var sx = [ 1 ];
+ > var ox = 0;
+ > var ord = 'row-major';
+ > var x = new {{alias:@stdlib/ndarray/ctor}}( dt, xbuf, sh, sx, ox, ord );
+ > function f ( v ) { return v % 2.0 === 0.0; };
+ > {{alias}}( [ x ], f )
+ 1
+
+ See Also
+ --------
+
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/docs/types/index.d.ts b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/docs/types/index.d.ts
new file mode 100644
index 000000000000..ab19b2302c81
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/docs/types/index.d.ts
@@ -0,0 +1,95 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+// TypeScript Version: 4.1
+
+///
+
+import { typedndarray } from '@stdlib/types/ndarray';
+
+/**
+* Returns the result of callback function.
+*
+* @returns result
+*/
+type Nullary = ( this: ThisArg ) => boolean;
+
+/**
+* Returns the result of callback function.
+*
+* @param value - current array element
+* @returns result
+*/
+type Unary = ( this: ThisArg, value: T ) => boolean;
+
+/**
+* Returns the result of callback function.
+*
+* @param value - current array element
+* @param index - current array element index
+* @returns result
+*/
+type Binary = ( this: ThisArg, value: T, index: number ) => boolean;
+
+/**
+* Returns the result of callback function.
+*
+* @param value - current array element
+* @param index - current array element index
+* @param array - input ndarray
+* @returns result
+*/
+type Ternary = ( this: ThisArg, value: T, index: number, array: U ) => boolean;
+
+/**
+* Returns the result of callback function.
+*
+* @param value - current array element
+* @param index - current array element index
+* @param array - input ndarray
+* @returns result
+*/
+type Callback = Nullary | Unary | Binary | Ternary;
+
+/**
+* Returns the index of the first element in a one-dimensional ndarray which passes a test implemented by a predicate function.
+*
+* @param arrays - array-like object containing an input ndarray
+* @param clbk - callback function
+* @param thisArg - callback execution context
+* @returns index
+*
+* @example
+* var ndarray = require( '@stdlib/ndarray/base/ctor' );
+*
+* function clbk( v ) {
+* return v % 2.0 === 0.0;
+* }
+*
+* var xbuf = [ 1.0, 3.0, 4.0, 2.0 ];
+* var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
+*
+* var v = gfindIndex( [ x ], clbk );
+* // returns 8.0
+*/
+declare function gfindIndex = typedndarray, ThisArg = unknown>( arrays: [ U ], clbk: Callback, thisArg?: ThisParameterType> ): number;
+
+
+// EXPORTS //
+
+export = gfindIndex;
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/docs/types/test.ts b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/docs/types/test.ts
new file mode 100644
index 000000000000..9805a8639808
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/docs/types/test.ts
@@ -0,0 +1,103 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/* eslint-disable space-in-parens */
+
+import zeros = require( '@stdlib/ndarray/zeros' );
+import gfindIndex = require( './index' );
+
+/**
+* Callback function.
+*
+* @param value - ndarray element
+* @returns result
+*/
+function clbk( value: any ): boolean {
+ return value % 2.0 === 0.0;
+}
+
+
+// TESTS //
+
+// The function returns a number...
+{
+ const x = zeros( [ 10 ], {
+ 'dtype': 'generic'
+ });
+
+ gfindIndex( [ x ], clbk ); // $ExpectType number
+ gfindIndex( [ x ], clbk, {} ); // $ExpectType number
+}
+
+// The compiler throws an error if the function is provided a first argument which is not an array of ndarrays...
+{
+ gfindIndex( '10', clbk ); // $ExpectError
+ gfindIndex( 10, clbk ); // $ExpectError
+ gfindIndex( true, clbk ); // $ExpectError
+ gfindIndex( false, clbk ); // $ExpectError
+ gfindIndex( null, clbk ); // $ExpectError
+ gfindIndex( undefined, clbk ); // $ExpectError
+ gfindIndex( [], clbk ); // $ExpectError
+ gfindIndex( {}, clbk ); // $ExpectError
+ gfindIndex( ( x: number ): number => x, clbk ); // $ExpectError
+
+ gfindIndex( '10', clbk, {} ); // $ExpectError
+ gfindIndex( 10, clbk, {} ); // $ExpectError
+ gfindIndex( true, clbk, {} ); // $ExpectError
+ gfindIndex( false, clbk, {} ); // $ExpectError
+ gfindIndex( null, clbk, {} ); // $ExpectError
+ gfindIndex( undefined, clbk, {} ); // $ExpectError
+ gfindIndex( [], clbk, {} ); // $ExpectError
+ gfindIndex( {}, clbk, {} ); // $ExpectError
+ gfindIndex( ( x: number ): number => x, clbk, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a second argument which is not a callback function...
+{
+ const x = zeros( [ 10 ], {
+ 'dtype': 'generic'
+ });
+
+ gfindIndex( [ x ], '10' ); // $ExpectError
+ gfindIndex( [ x ], 10 ); // $ExpectError
+ gfindIndex( [ x ], true ); // $ExpectError
+ gfindIndex( [ x ], false ); // $ExpectError
+ gfindIndex( [ x ], null ); // $ExpectError
+ gfindIndex( [ x ], undefined ); // $ExpectError
+ gfindIndex( [ x ], [] ); // $ExpectError
+ gfindIndex( [ x ], {} ); // $ExpectError
+
+ gfindIndex( [ x ], '10', {} ); // $ExpectError
+ gfindIndex( [ x ], 10, {} ); // $ExpectError
+ gfindIndex( [ x ], true, {} ); // $ExpectError
+ gfindIndex( [ x ], false, {} ); // $ExpectError
+ gfindIndex( [ x ], null, {} ); // $ExpectError
+ gfindIndex( [ x ], undefined, {} ); // $ExpectError
+ gfindIndex( [ x ], [], {} ); // $ExpectError
+ gfindIndex( [ x ], {}, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an unsupported number of arguments...
+{
+ const x = zeros( [ 10 ], {
+ 'dtype': 'generic'
+ });
+
+ gfindIndex(); // $ExpectError
+ gfindIndex( [ x ], clbk, {}, {} ); // $ExpectError
+}
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/examples/index.js b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/examples/index.js
new file mode 100644
index 000000000000..3e2728597d1a
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/examples/index.js
@@ -0,0 +1,37 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
+var ndarray = require( '@stdlib/ndarray/base/ctor' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
+var gfindIndex = require( './../lib' );
+
+function isEven( v ) {
+ return v % 2.0 === 0.0;
+}
+
+var xbuf = discreteUniform( 10, -100, 100, {
+ 'dtype': 'generic'
+});
+var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
+console.log( ndarray2array( x ) );
+
+var idx = gfindIndex( [ x ], isEven );
+console.log( idx );
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/lib/index.js b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/lib/index.js
new file mode 100644
index 000000000000..176f7cc920d7
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/lib/index.js
@@ -0,0 +1,48 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+/**
+* Return the index of the first element in a one-dimensional ndarray which passes a test implemented by a predicate function.
+*
+* @module @stdlib/blas/ext/base/ndarray/gfind-index
+*
+* @example
+* var ndarray = require( '@stdlib/ndarray/base/ctor' );
+* var gfindIndex = require( '@stdlib/blas/ext/base/ndarray/gfind-index' );
+*
+* function clbk( v ) {
+* return v % 2.0 === 0.0;
+* }
+*
+* var xbuf = [ 1.0, 3.0, 4.0, 2.0 ];
+* var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
+*
+* var v = gfindIndex( [ x ], clbk );
+* // returns 2
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/lib/main.js b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/lib/main.js
new file mode 100644
index 000000000000..5938f9f19c6a
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gfind-index/lib/main.js
@@ -0,0 +1,75 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var numelDimension = require( '@stdlib/ndarray/base/numel-dimension' );
+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/gfind-index' ).ndarray;
+
+
+// MAIN //
+
+/**
+* Returns the index of the first element in a one-dimensional ndarray which passes a test implemented by a predicate function.
+*
+* @param {ArrayLikeObject