Skip to content

Commit 3ac7464

Browse files
headlessNodekgryte
headlessNode
and
kgryte
authored
feat: add blas/ext/find-index
PR-URL: #7814 Ref: #2656 Co-authored-by: Athan Reines <[email protected]> Reviewed-by: Athan Reines <[email protected]>
1 parent 5fb8da6 commit 3ac7464

File tree

15 files changed

+3661
-0
lines changed

15 files changed

+3661
-0
lines changed

‎lib/node_modules/@stdlib/blas/ext/find-index/README.md

Lines changed: 312 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,312 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# findIndex
22+
23+
> Return the index of the first element along an [ndarray][@stdlib/ndarray/ctor] dimension which passes a test implemented by a predicate function.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var findIndex = require( '@stdlib/blas/ext/find-index' );
31+
```
32+
33+
#### findIndex( x\[, options], clbk\[, thisArg] )
34+
35+
Returns the index of the first element along an [ndarray][@stdlib/ndarray/ctor] dimension which passes a test implemented by a predicate function.
36+
37+
```javascript
38+
var array = require( '@stdlib/ndarray/array' );
39+
40+
function isEven( v ) {
41+
return v % 2.0 === 0.0;
42+
}
43+
44+
// Create an input ndarray:
45+
var x = array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
46+
// returns <ndarray>
47+
48+
// Perform operation:
49+
var out = findIndex( x, isEven );
50+
// returns <ndarray>
51+
52+
var idx = out.get();
53+
// returns 1
54+
```
55+
56+
The function has the following parameters:
57+
58+
- **x**: input [ndarray][@stdlib/ndarray/ctor]. Must have at least one dimension.
59+
- **options**: function options (_optional_).
60+
- **clbk**: callback function.
61+
- **thisArg**: callback execution context (_optional_).
62+
63+
The invoked callback is provided three arguments:
64+
65+
- **value**: current array element.
66+
- **idx**: current array element index.
67+
- **array**: input ndarray.
68+
69+
To set the callback execution context, provide a `thisArg`.
70+
71+
<!-- eslint-disable no-invalid-this -->
72+
73+
```javascript
74+
var array = require( '@stdlib/ndarray/array' );
75+
76+
function isEven( v ) {
77+
this.count += 1;
78+
return v % 2.0 === 0.0;
79+
}
80+
81+
var x = array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
82+
83+
var ctx = {
84+
'count': 0
85+
};
86+
var out = findIndex( x, isEven, ctx );
87+
// returns <ndarray>
88+
89+
var idx = out.get();
90+
// returns 1
91+
92+
var count = ctx.count;
93+
// returns 2
94+
```
95+
96+
The function accepts the following options:
97+
98+
- **dtype**: output ndarray [data type][@stdlib/ndarray/dtypes]. Must be an integer index or generic [data type][@stdlib/ndarray/dtypes].
99+
- **dim**: dimension over which to perform operation. If provided a negative integer, the dimension along which to perform the operation is determined by counting backward from the last dimension (where `-1` refers to the last dimension). Default: `-1`.
100+
- **keepdims**: boolean indicating whether the reduced dimensions should be included in the returned [ndarray][@stdlib/ndarray/ctor] as singleton dimensions. Default: `false`.
101+
102+
If no element along an [ndarray][@stdlib/ndarray/ctor] dimension passes a test implemented by the predicate function, the corresponding element in the returned [ndarray][@stdlib/ndarray/ctor] is `-1`.
103+
104+
```javascript
105+
var array = require( '@stdlib/ndarray/array' );
106+
107+
function isEven( v ) {
108+
return v % 2.0 === 0.0;
109+
}
110+
111+
// Create an input ndarray:
112+
var x = array( [ 1.0, 3.0, 5.0, 7.0 ] );
113+
// returns <ndarray>
114+
115+
// Perform operation:
116+
var out = findIndex( x, isEven );
117+
// returns <ndarray>
118+
119+
var idx = out.get();
120+
// returns -1
121+
```
122+
123+
By default, the function performs the operation over elements in the last dimension. To perform the operation over a different dimension, provide a `dim` option.
124+
125+
```javascript
126+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
127+
var array = require( '@stdlib/ndarray/array' );
128+
129+
function isEven( v ) {
130+
return v % 2.0 === 0.0;
131+
}
132+
133+
var x = array( [ [ -1.0, 2.0 ], [ -3.0, 4.0 ] ] );
134+
135+
var opts = {
136+
'dim': 0
137+
};
138+
139+
var out = findIndex( x, opts, isEven );
140+
// returns <ndarray>
141+
142+
var idx = ndarray2array( out );
143+
// returns [ -1, 0 ]
144+
```
145+
146+
By default, the function excludes reduced dimensions from the output [ndarray][@stdlib/ndarray/ctor]. To include the reduced dimensions as singleton dimensions, set the `keepdims` option to `true`.
147+
148+
```javascript
149+
var array = require( '@stdlib/ndarray/array' );
150+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
151+
152+
function isEven( v ) {
153+
return v % 2.0 === 0.0;
154+
}
155+
156+
var x = array( [ [ -1.0, 2.0 ], [ -3.0, 4.0 ] ] );
157+
158+
var opts = {
159+
'dim': 0,
160+
'keepdims': true
161+
};
162+
163+
var out = findIndex( x, opts, isEven );
164+
// returns <ndarray>
165+
166+
var idx = ndarray2array( out );
167+
// returns [ [ -1, 0 ] ]
168+
```
169+
170+
By default, the function returns an [ndarray][@stdlib/ndarray/ctor] having a [data type][@stdlib/ndarray/dtypes] determined by the function's output data type [policy][@stdlib/ndarray/output-dtype-policies]. To override the default behavior, set the `dtype` option.
171+
172+
```javascript
173+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
174+
var dtype = require( '@stdlib/ndarray/dtype' );
175+
var array = require( '@stdlib/ndarray/array' );
176+
177+
function isEven( v ) {
178+
return v % 2.0 === 0.0;
179+
}
180+
181+
var x = array( [ 1.0, 2.0, 3.0, 4.0 ] );
182+
183+
var opts = {
184+
'dtype': 'generic'
185+
};
186+
187+
var idx = findIndex( x, opts, isEven );
188+
// returns <ndarray>
189+
190+
var dt = dtype( idx );
191+
// returns 'generic'
192+
```
193+
194+
#### findIndex.assign( x, out\[, options], clbk\[, thisArg] )
195+
196+
Returns the index of the first element along an [ndarray][@stdlib/ndarray/ctor] dimension which passes a test implemented by a predicate function and assigns results to a provided output [ndarray][@stdlib/ndarray/ctor].
197+
198+
```javascript
199+
var array = require( '@stdlib/ndarray/array' );
200+
var zeros = require( '@stdlib/ndarray/zeros' );
201+
202+
function isEven( v ) {
203+
return v % 2.0 === 0.0;
204+
}
205+
206+
var x = array( [ 1.0, 2.0, 3.0, 4.0 ] );
207+
var y = zeros( [], {
208+
'dtype': 'int32'
209+
});
210+
211+
var out = findIndex.assign( x, y, isEven );
212+
// returns <ndarray>
213+
214+
var idx = out.get();
215+
// returns 1
216+
217+
var bool = ( out === y );
218+
// returns true
219+
```
220+
221+
The method has the following parameters:
222+
223+
- **x**: input [ndarray][@stdlib/ndarray/ctor]. Must have at least one dimension.
224+
- **out**: output [ndarray][@stdlib/ndarray/ctor].
225+
- **options**: function options (_optional_).
226+
- **clbk**: callback function.
227+
- **thisArg**: callback execution context (_optional_).
228+
229+
The method accepts the following options:
230+
231+
- **dim**: dimension over which to perform operation. If provided a negative integer, the dimension along which to perform the operation is determined by counting backward from the last dimension (where `-1` refers to the last dimension). Default: `-1`.
232+
233+
</section>
234+
235+
<!-- /.usage -->
236+
237+
<section class="notes">
238+
239+
## Notes
240+
241+
- A provided callback function should return a boolean.
242+
- Setting the `keepdims` option to `true` can be useful when wanting to ensure that the output [ndarray][@stdlib/ndarray/ctor] is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with ndarrays having the same shape as the input [ndarray][@stdlib/ndarray/ctor].
243+
- The output data type [policy][@stdlib/ndarray/output-dtype-policies] only applies to the main function and specifies that, by default, the function must return an [ndarray][@stdlib/ndarray/ctor] having an integer index or "generic" [data type][@stdlib/ndarray/dtypes]. For the `assign` method, the output [ndarray][@stdlib/ndarray/ctor] is allowed to have any supported output [data type][@stdlib/ndarray/dtypes].
244+
245+
</section>
246+
247+
<!-- /.notes -->
248+
249+
<section class="examples">
250+
251+
## Examples
252+
253+
<!-- eslint no-undef: "error" -->
254+
255+
```javascript
256+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
257+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
258+
var ndarray = require( '@stdlib/ndarray/ctor' );
259+
var findIndex = require( '@stdlib/blas/ext/find-index' );
260+
261+
// Define a callback function:
262+
function isEven( v ) {
263+
return v % 2.0 === 0.0;
264+
}
265+
266+
// Generate an array of random numbers:
267+
var xbuf = discreteUniform( 10, 0, 20, {
268+
'dtype': 'generic'
269+
});
270+
271+
// Wrap in an ndarray:
272+
var x = new ndarray( 'generic', xbuf, [ 5, 2 ], [ 2, 1 ], 0, 'row-major' );
273+
console.log( ndarray2array( x ) );
274+
275+
var opts = {
276+
'dim': 0
277+
};
278+
279+
// Perform operation:
280+
var idx = findIndex( x, opts, isEven );
281+
282+
// Print the results:
283+
console.log( ndarray2array( idx ) );
284+
```
285+
286+
</section>
287+
288+
<!-- /.examples -->
289+
290+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
291+
292+
<section class="related">
293+
294+
</section>
295+
296+
<!-- /.related -->
297+
298+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
299+
300+
<section class="links">
301+
302+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
303+
304+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/dtypes
305+
306+
[@stdlib/ndarray/output-dtype-policies]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/output-dtype-policies
307+
308+
[@stdlib/ndarray/base/broadcast-shapes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/broadcast-shapes
309+
310+
</section>
311+
312+
<!-- /.links -->

0 commit comments

Comments
 (0)