Skip to content

Commit 3237c87

Browse files
headlessNodeheadlessNode
committed
feat: add blas/ext/base/zindex-of
1 parent 013a23b commit 3237c87

33 files changed

Lines changed: 3500 additions & 0 deletions

‎lib/node_modules/@stdlib/blas/ext/base/zindex-of/README.md‎

Lines changed: 336 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,336 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2026 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+
# zindexOf
22+
23+
> Return the first index of a specified search element in a double-precision complex floating-point strided array.
24+
25+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
26+
27+
<section class="intro">
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<!-- Package usage documentation. -->
34+
35+
<section class="usage">
36+
37+
## Usage
38+
39+
```javascript
40+
var zindexOf = require( '@stdlib/blas/ext/base/zindex-of' );
41+
```
42+
43+
#### zindexOf( N, searchElement, x, strideX )
44+
45+
Returns the first index of a specified search element in a double-precision complex floating-point strided array.
46+
47+
```javascript
48+
var Complex128Array = require( '@stdlib/array/complex128' );
49+
var Complex128 = require( '@stdlib/complex/float64/ctor' );
50+
51+
var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
52+
53+
var idx = zindexOf( x.length, new Complex128( 3.0, 4.0 ), x, 1 );
54+
// returns 1
55+
```
56+
57+
The function has the following parameters:
58+
59+
- **N**: number of indexed elements.
60+
- **searchElement**: search element ([`Complex128`][@stdlib/complex/float64/ctor]).
61+
- **x**: input [`Complex128Array`][@stdlib/array/complex128].
62+
- **strideX**: stride length.
63+
64+
If the function is unable to find a search element, the function returns `-1`.
65+
66+
```javascript
67+
var Complex128Array = require( '@stdlib/array/complex128' );
68+
var Complex128 = require( '@stdlib/complex/float64/ctor' );
69+
70+
var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
71+
72+
var idx = zindexOf( x.length, new Complex128( 7.0, 8.0 ), x, 1 );
73+
// returns -1
74+
```
75+
76+
The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to search every other element:
77+
78+
```javascript
79+
var Complex128Array = require( '@stdlib/array/complex128' );
80+
var Complex128 = require( '@stdlib/complex/float64/ctor' );
81+
82+
var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
83+
84+
var idx = zindexOf( 2, new Complex128( 5.0, 6.0 ), x, 2 );
85+
// returns 1
86+
```
87+
88+
Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
89+
90+
```javascript
91+
var Complex128Array = require( '@stdlib/array/complex128' );
92+
var Complex128 = require( '@stdlib/complex/float64/ctor' );
93+
94+
// Initial array...
95+
var x0 = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
96+
97+
// Create an offset view...
98+
var x1 = new Complex128Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
99+
100+
// Find index...
101+
var idx = zindexOf( 3, new Complex128( 7.0, 8.0 ), x1, 1 );
102+
// returns 2
103+
```
104+
105+
#### zindexOf.ndarray( N, searchElement, x, strideX, offsetX )
106+
107+
Returns the first index of a specified search element in a double-precision complex floating-point strided array using alternative indexing semantics.
108+
109+
```javascript
110+
var Complex128Array = require( '@stdlib/array/complex128' );
111+
var Complex128 = require( '@stdlib/complex/float64/ctor' );
112+
113+
var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
114+
115+
var idx = zindexOf.ndarray( x.length, new Complex128( 3.0, 4.0 ), x, 1, 0 );
116+
// returns 1
117+
```
118+
119+
The function has the following additional parameters:
120+
121+
- **offsetX**: starting index.
122+
123+
While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameter supports indexing semantics based on a starting index. For example, to access only the last three elements of the strided array
124+
125+
```javascript
126+
var Complex128Array = require( '@stdlib/array/complex128' );
127+
var Complex128 = require( '@stdlib/complex/float64/ctor' );
128+
129+
var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
130+
131+
var idx = zindexOf.ndarray( 3, new Complex128( 5.0, 6.0 ), x, 1, x.length-3 );
132+
// returns 1
133+
```
134+
135+
</section>
136+
137+
<!-- /.usage -->
138+
139+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
140+
141+
<section class="notes">
142+
143+
## Notes
144+
145+
- When searching for a search element, the function checks for equality of the real and imaginary components using the strict equality operator `===`. As a consequence, `NaN` values are considered distinct, and `-0` and `+0` are considered the same.
146+
147+
</section>
148+
149+
<!-- /.notes -->
150+
151+
<!-- Package usage examples. -->
152+
153+
<section class="examples">
154+
155+
## Examples
156+
157+
<!-- eslint no-undef: "error" -->
158+
159+
```javascript
160+
var uniform = require( '@stdlib/random/array/uniform' );
161+
var Complex128Array = require( '@stdlib/array/complex128' );
162+
var Complex128 = require( '@stdlib/complex/float64/ctor' );
163+
var zindexOf = require( '@stdlib/blas/ext/base/zindex-of' );
164+
165+
var buf = uniform( 10*2, -10, 10, {
166+
'dtype': 'float64'
167+
});
168+
var x = new Complex128Array( buf.buffer );
169+
console.log( x );
170+
171+
var idx = zindexOf( x.length, new Complex128( 5.0, 5.0 ), x, 1 );
172+
console.log( idx );
173+
```
174+
175+
</section>
176+
177+
<!-- /.examples -->
178+
179+
<!-- C interface documentation. -->
180+
181+
* * *
182+
183+
<section class="c">
184+
185+
## C APIs
186+
187+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
188+
189+
<section class="intro">
190+
191+
</section>
192+
193+
<!-- /.intro -->
194+
195+
<!-- C usage documentation. -->
196+
197+
<section class="usage">
198+
199+
### Usage
200+
201+
```c
202+
#include "stdlib/blas/ext/base/zindex_of.h"
203+
```
204+
205+
#### stdlib_strided_zindex_of( N, searchElement, \*X, strideX )
206+
207+
Returns the first index of a specified search element in a double-precision complex floating-point strided array.
208+
209+
```c
210+
#include "stdlib/complex/float64/ctor.h"
211+
212+
const double x[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 };
213+
const stdlib_complex128_t searchElement = stdlib_complex128( 3.0, 4.0 );
214+
215+
int idx = stdlib_strided_zindex_of( 3, searchElement, (const stdlib_complex128_t *)x, 1 );
216+
// returns 1
217+
```
218+
219+
The function accepts the following arguments:
220+
221+
- **N**: `[in] CBLAS_INT` number of indexed elements.
222+
- **searchElement**: `[in] stdlib_complex128_t` search element.
223+
- **X**: `[in] stdlib_complex128_t*` input array.
224+
- **strideX**: `[in] CBLAS_INT` stride length.
225+
226+
```c
227+
CBLAS_INT stdlib_strided_zindex_of( const CBLAS_INT N, const stdlib_complex128_t searchElement, const stdlib_complex128_t *X, const CBLAS_INT strideX );
228+
```
229+
230+
#### stdlib_strided_zindex_of_ndarray( N, searchElement, \*X, strideX, offsetX )
231+
232+
Returns the first index of a specified search element in a double-precision complex floating-point strided array using alternative indexing semantics.
233+
234+
```c
235+
#include "stdlib/complex/float64/ctor.h"
236+
237+
const double x[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 };
238+
const stdlib_complex128_t searchElement = stdlib_complex128( 3.0, 4.0 );
239+
240+
int idx = stdlib_strided_zindex_of_ndarray( 3, searchElement, (const stdlib_complex128_t *)x, 1, 0 );
241+
// returns 1
242+
```
243+
244+
The function accepts the following arguments:
245+
246+
- **N**: `[in] CBLAS_INT` number of indexed elements.
247+
- **searchElement**: `[in] stdlib_complex128_t` search element.
248+
- **X**: `[in] stdlib_complex128_t*` input array.
249+
- **strideX**: `[in] CBLAS_INT` stride length.
250+
- **offsetX**: `[in] CBLAS_INT` starting index.
251+
252+
```c
253+
CBLAS_INT stdlib_strided_zindex_of_ndarray( const CBLAS_INT N, const stdlib_complex128_t searchElement, const stdlib_complex128_t *X, const CBLAS_INT strideX, const CBLAS_INT offsetX );
254+
```
255+
256+
</section>
257+
258+
<!-- /.usage -->
259+
260+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
261+
262+
<section class="notes">
263+
264+
</section>
265+
266+
<!-- /.notes -->
267+
268+
<!-- C API usage examples. -->
269+
270+
<section class="examples">
271+
272+
### Examples
273+
274+
```c
275+
#include "stdlib/blas/ext/base/zindex_of.h"
276+
#include "stdlib/complex/float64/ctor.h"
277+
#include <stdio.h>
278+
279+
int main( void ) {
280+
// Create a strided array (interleaved real and imaginary components):
281+
const double x[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 };
282+
283+
// Specify the number of indexed elements:
284+
const int N = 4;
285+
286+
// Specify a stride:
287+
const int strideX = 1;
288+
289+
// Specify a search element:
290+
const stdlib_complex128_t searchElement = stdlib_complex128( 5.0, 6.0 );
291+
292+
// Perform a search:
293+
int idx = stdlib_strided_zindex_of( N, searchElement, (const stdlib_complex128_t *)x, strideX );
294+
295+
// Print the result:
296+
printf( "index value: %d\n", idx );
297+
}
298+
```
299+
300+
</section>
301+
302+
<!-- /.examples -->
303+
304+
</section>
305+
306+
<!-- /.c -->
307+
308+
<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
309+
310+
<section class="references">
311+
312+
</section>
313+
314+
<!-- /.references -->
315+
316+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
317+
318+
<section class="related">
319+
320+
</section>
321+
322+
<!-- /.related -->
323+
324+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
325+
326+
<section class="links">
327+
328+
[@stdlib/array/complex128]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/complex128
329+
330+
[@stdlib/complex/float64/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/complex/float64/ctor
331+
332+
[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
333+
334+
</section>
335+
336+
<!-- /.links -->

0 commit comments

Comments
 (0)