Skip to content

feat!: add fromIndex support #14411

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kgryte merged 1 commit into from
Aug 19, 2026
Merged

feat!: add fromIndex support #14411

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 22 additions & 3 deletions lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-less-than/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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( [ 0.0, 0.0, 0.0, 0.0 ] );
var y = new Float64Vector( [ 0.0, 0.0, 1.0, 0.0 ] );

var idx = dfirstIndexLessThan( [ x, y ] );
var fromIndex = scalar2ndarray( 0, {
'dtype': 'generic'
});

var idx = dfirstIndexLessThan( [ x, y, fromIndex ] );
// returns 2
```

Expand All @@ -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 which is less than 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( [ 5.0, 6.0, 7.0, 8.0 ] );
var y = new Float64Vector( [ 1.0, 2.0, 3.0, 4.0 ] );

var idx = dfirstIndexLessThan( [ x, y ] );
var fromIndex = scalar2ndarray( 0, {
'dtype': 'generic'
});

var idx = dfirstIndexLessThan( [ x, y, fromIndex ] );
// returns -1
```

Expand All @@ -77,6 +88,7 @@ var idx = dfirstIndexLessThan( [ 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 whether an element in the first one-dimensional input ndarray is less than a corresponding element in the second one-dimensional input ndarray using the less-than operator `<`. As a consequence, comparisons involving `NaN` always evaluate to `false`.

</section>
Expand All @@ -91,7 +103,9 @@ var idx = dfirstIndexLessThan( [ 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 dfirstIndexLessThan = require( '@stdlib/blas/ext/base/ndarray/dfirst-index-less-than' );

var opts = {
Expand All @@ -103,7 +117,12 @@ console.log( ndarray2array( x ) );
var y = discreteUniform( [ 10 ], 0, 10, opts );
console.log( ndarray2array( y ) );

var idx = dfirstIndexLessThan( [ x, y ] );
var fromIndex = scalar2ndarray( 0, {
'dtype': 'generic'
});
console.log( 'From Index:', ndarraylike2scalar( fromIndex ) );

var idx = dfirstIndexLessThan( [ x, y, fromIndex ] );
console.log( idx );
```

Expand Down
17 changes: 12 additions & 5 deletions lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-less-than/benchmark/benchmark.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,10 @@
// MODULES //

var bench = require( '@stdlib/bench' );
var ones = require( '@stdlib/ndarray/ones' );
var isInteger = require( '@stdlib/assert/is-integer' ).isPrimitive;
var pow = require( '@stdlib/math/base/special/pow' );
var Float64Vector = require( '@stdlib/ndarray/vector/float64' );
var ones = require( '@stdlib/array/ones' );
var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
var format = require( '@stdlib/string/format' );
var pkg = require( './../package.json' ).name;
var dfirstIndexLessThan = require( './../lib' );
Expand All @@ -47,8 +47,15 @@ var options = {
* @returns {Function} benchmark function
*/
function createBenchmark( len ) {
var x = new Float64Vector( ones( len, options.dtype ) );
var y = new Float64Vector( ones( len, options.dtype ) );
var fromIndex;
var x;
var y;

x = ones( [ len ], options );
y = ones( [ len ], options );
fromIndex = scalar2ndarray( 0, {
'dtype': 'generic'
});
return benchmark;

/**
Expand All @@ -63,7 +70,7 @@ function createBenchmark( len ) {

b.tic();
for ( i = 0; i < b.iterations; i++ ) {
out = dfirstIndexLessThan( [ x, y ] );
out = dfirstIndexLessThan( [ x, y, fromIndex ] );
if ( out !== out ) {
b.fail( 'should return an integer' );
}
Expand Down
9 changes: 8 additions & 1 deletion lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-less-than/docs/repl.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@
precision floating-point ndarray which is less than 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 whether an element in the first
one-dimensional input ndarray is less than a corresponding element in the
second one-dimensional input ndarray using the less-than operator `<`. As a
Expand All @@ -16,6 +20,8 @@

- first one-dimensional input ndarray.
- second one-dimensional input ndarray.
- a zero-dimensional ndarray containing the index from which to begin
searching.

Returns
-------
Expand All @@ -26,7 +32,8 @@
--------
> var x = new {{alias:@stdlib/ndarray/vector/float64}}( [ 0.0, 0.0, 0.0, 0.0 ] );
> var y = new {{alias:@stdlib/ndarray/vector/float64}}( [ 0.0, 0.0, 1.0, 0.0 ] );
> {{alias}}( [ x, y ] )
> var i = {{alias:@stdlib/ndarray/from-scalar}}( 0, { 'dtype': 'generic' } );
> {{alias}}( [ x, y, i ] )
2

See Also
Expand Down
12 changes: 9 additions & 3 deletions lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-less-than/docs/types/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 which is less than a corresponding element in another one-dimensional double-precision floating-point ndarray.
Expand All @@ -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 whether an element in the first one-dimensional input ndarray is less than a corresponding element in the second one-dimensional input ndarray using the less-than operator `<`. As a consequence, comparisons involving `NaN` always evaluate to `false`.
*
Expand All @@ -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( [ 0.0, 0.0, 0.0, 0.0 ] );
* var y = new Float64Vector( [ 0.0, 0.0, 1.0, 0.0 ] );
*
* var idx = dfirstIndexLessThan( [ x, y ] );
* var fromIndex = scalar2ndarray( 0, {
* 'dtype': 'generic'
* });
*
* var idx = dfirstIndexLessThan( [ x, y, fromIndex ] );
* // returns 2
*/
declare function dfirstIndexLessThan( arrays: [ float64ndarray, float64ndarray ] ): number;
declare function dfirstIndexLessThan( arrays: [ float64ndarray, float64ndarray, typedndarray<number> ] ): number;


// EXPORTS //
Expand Down
11 changes: 9 additions & 2 deletions lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-less-than/docs/types/test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
/* eslint-disable space-in-parens */

import zeros = require( '@stdlib/ndarray/zeros' );
import scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
import dfirstIndexLessThan = require( './index' );


Expand All @@ -32,8 +33,11 @@ import dfirstIndexLessThan = require( './index' );
const y = zeros( [ 10 ], {
'dtype': 'float64'
});
const fromIndex = scalar2ndarray( 0, {
'dtype': 'generic'
});

dfirstIndexLessThan( [ x, y ] ); // $ExpectType number
dfirstIndexLessThan( [ 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...
Expand All @@ -57,7 +61,10 @@ import dfirstIndexLessThan = require( './index' );
const y = zeros( [ 10 ], {
'dtype': 'float64'
});
const fromIndex = scalar2ndarray( 0, {
'dtype': 'generic'
});

dfirstIndexLessThan(); // $ExpectError
dfirstIndexLessThan( [ x, y ], {} ); // $ExpectError
dfirstIndexLessThan( [ x, y, fromIndex ], {} ); // $ExpectError
}
9 changes: 8 additions & 1 deletion lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-less-than/examples/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 dfirstIndexLessThan = require( './../lib' );

var opts = {
Expand All @@ -31,5 +33,10 @@ console.log( ndarray2array( x ) );
var y = discreteUniform( [ 10 ], 0, 10, opts );
console.log( ndarray2array( y ) );

var idx = dfirstIndexLessThan( [ x, y ] );
var fromIndex = scalar2ndarray( 0, {
'dtype': 'generic'
});
console.log( 'From Index:', ndarraylike2scalar( fromIndex ) );

var idx = dfirstIndexLessThan( [ x, y, fromIndex ] );
console.log( idx );
7 changes: 6 additions & 1 deletion lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-less-than/lib/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,17 @@
*
* @example
* var Float64Vector = require( '@stdlib/ndarray/vector/float64' );
* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
* var dfirstIndexLessThan = require( '@stdlib/blas/ext/base/ndarray/dfirst-index-less-than' );
*
* var x = new Float64Vector( [ 0.0, 0.0, 0.0, 0.0 ] );
* var y = new Float64Vector( [ 0.0, 0.0, 1.0, 0.0 ] );
*
* var idx = dfirstIndexLessThan( [ x, y ] );
* var fromIndex = scalar2ndarray( 0, {
* 'dtype': 'generic'
* });
*
* var idx = dfirstIndexLessThan( [ x, y, fromIndex ] );
* // returns 2
*/

Expand Down
46 changes: 42 additions & 4 deletions lib/node_modules/@stdlib/blas/ext/base/ndarray/dfirst-index-less-than/lib/main.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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-less-than' ).ndarray;
var ndarraylike2scalar = require( '@stdlib/ndarray/base/ndarraylike2scalar' );


// MAIN //
Expand All @@ -38,6 +39,7 @@ var strided = require( '@stdlib/blas/ext/base/dfirst-index-less-than' ).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 whether an element in the first one-dimensional input ndarray is less than a corresponding element in the second one-dimensional input ndarray using the less-than operator `<`. As a consequence, comparisons involving `NaN` always evaluate to `false`.
*
Expand All @@ -46,17 +48,53 @@ var strided = require( '@stdlib/blas/ext/base/dfirst-index-less-than' ).ndarray;
*
* @example
* var Float64Vector = require( '@stdlib/ndarray/vector/float64' );
* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
*
* var x = new Float64Vector( [ 0.0, 0.0, 0.0, 0.0 ] );
* var y = new Float64Vector( [ 0.0, 0.0, 1.0, 0.0 ] );
*
* var idx = dfirstIndexLessThan( [ x, y ] );
* var fromIndex = scalar2ndarray( 0, {
* 'dtype': 'generic'
* });
*
* var idx = dfirstIndexLessThan( [ x, y, fromIndex ] );
* // returns 2
*/
function dfirstIndexLessThan( 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 idx;
var ox;
var oy;
var sx;
var sy;
var N;
var x;
var y;

x = arrays[ 0 ];
y = arrays[ 1 ];
N = numelDimension( x, 0 );
fromIndex = ndarraylike2scalar( arrays[ 2 ] );

if ( fromIndex < 0 ) {

@kgryte kgryte Aug 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We will end up repeating this logic a lot across different packages needing to support a fromIndex.

In which case, if we have clip-index which normalizes and clamps both ends, maybe we should create a separate package: clip-lower-index. This would do exactly as we do here. And this naming convention would leave open the door for a future clip-upper-index should a need ever arise.

We can merge this as is and then refactor this logic across multiple packages in a separate PR.

Work for you?

fromIndex += N;
if ( fromIndex < 0 ) {
fromIndex = 0;
}
} else if ( fromIndex >= N ) {
return -1;
}
N -= fromIndex;
sx = getStride( x, 0 );
sy = getStride( y, 0 );
ox = getOffset( x ) + ( sx*fromIndex );
oy = getOffset( y ) + ( sy*fromIndex );

idx = strided( N, getData( x ), sx, ox, getData( y ), sy, oy );
if ( idx >= 0 ) {
idx += fromIndex;
}
return idx;
}


Expand Down
Loading