Skip to content

find

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

find

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
benchmark
benchmark
 
 
docs
docs
 
 
examples
examples
 
 
lib
lib
 
 
test
test
 
 
README.md
README.md
 
 
package.json
package.json
 
 

README.md

find

Return a new ndarray containing the first elements which pass a test implemented by a predicate function along one or more ndarray dimensions.

Usage

var find = require( '@stdlib/ndarray/find' );

find( x[, options], predicate[, thisArg] )

Returns a new ndarray containing the first elements which pass a test implemented by a predicate function along one or more ndarray dimensions.

var array = require( '@stdlib/ndarray/array' );

function isEven( value ) {
    return value % 2.0 === 0.0;
}

// Create an input ndarray:
var x = array( [ [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ] ] );
// returns <ndarray>

// Perform reduction:
var out = find( x, isEven );
// returns <ndarray>[ 2.0 ]

The function accepts the following arguments:

  • x: input ndarray.
  • options: function options (optional).
  • predicate: predicate function.
  • thisArg: predicate function execution context (optional).

The function accepts the following options:

  • dims: list of dimensions over which to perform a reduction.
  • keepdims: boolean indicating whether the reduced dimensions should be included in the returned ndarray as singleton dimensions. Default: false.
  • sentinel: value to return when no element passes the test. May be either a scalar value or a zero-dimensional ndarray.

By default, the function performs reduction over all elements in a provided ndarray. To reduce specific dimensions, set the dims option.

var array = require( '@stdlib/ndarray/array' );

function isEven( value ) {
    return value % 2.0 === 0.0;
}

// Create an input ndarray:
var x = array( [ [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ] ] );
// returns <ndarray>

var opts = {
    'dims': [ 0 ]
};

// Perform reduction:
var out = find( x, opts, isEven );
// returns <ndarray>[ [ NaN, 2.0 ], [ NaN, 6.0 ] ]

By default, the function returns an ndarray having a shape matching only the non-reduced dimensions of the input ndarray (i.e., the reduced dimensions are dropped). To include the reduced dimensions as singleton dimensions in the output ndarray, set the keepdims option to true.

var array = require( '@stdlib/ndarray/array' );

function isEven( value ) {
    return value % 2.0 === 0.0;
}

// Create an input ndarray:
var x = array( [ [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ] ] );
// returns <ndarray>

var opts = {
    'dims': [ 0 ],
    'keepdims': true
};

// Perform reduction:
var out = find( x, opts, isEven );
// returns <ndarray>[ [ [ NaN, 2.0 ] ], [ [ NaN, 6.0 ] ] ]

To specify a custom sentinel value to return when no element passes the test, set the sentinel option.

var array = require( '@stdlib/ndarray/array' );

function isEven( value ) {
    return value % 2.0 === 0.0;
}

// Create an input ndarray:
var x = array( [ [ [ 1.0, 3.0 ], [ 5.0, 7.0 ] ], [ [ 9.0, 11.0 ], [ 13.0, 15.0 ] ] ] );
// returns <ndarray>

var opts = {
    'sentinel': -999
};

// Perform reduction:
var out = find( x, opts, isEven );
// returns <ndarray>[ -999 ]

To set the predicate function execution context, provide a thisArg.

var array = require( '@stdlib/ndarray/array' );

function isEven( value ) {
    this.count += 1;
    return value % 2.0 === 0.0;
}

// Create an input ndarray:
var x = array( [ [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ] ] );
// returns <ndarray>

var ctx = {
    'count': 0
};

// Perform reduction:
var out = find( x, isEven, ctx );
// returns <ndarray>[ 2.0 ]

var count = ctx.count;
// returns 2

find.assign( x, out[, options], predicate[, thisArg] )

Finds the first elements which pass a test implemented by a predicate function along one or more ndarray dimensions and assigns results to a provided output ndarray.

var array = require( '@stdlib/ndarray/array' );
var empty = require( '@stdlib/ndarray/empty' );
var getDType = require( '@stdlib/ndarray/dtype' );

function isEven( value ) {
    return value % 2.0 === 0.0;
}

// Create an input ndarray:
var x = array( [ [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ] ] );
// returns <ndarray>

// Create an output ndarray:
var y = empty( [], {
    'dtype': getDType( x )
});

// Perform reduction:
var out = find.assign( x, y, isEven );
// returns <ndarray>[ 2.0 ]

var bool = ( out === y );
// returns true

The function accepts the following arguments:

  • x: input ndarray.
  • out: output ndarray.
  • options: function options (optional).
  • predicate: predicate function.
  • thisArg: predicate function execution context (optional).

The function accepts the following options:

  • dims: list of dimensions over which to perform a reduction.
  • sentinel: value to return when no element passes the test. May be either a scalar value or a zero-dimensional ndarray.
var array = require( '@stdlib/ndarray/array' );
var empty = require( '@stdlib/ndarray/empty' );
var getDType = require( '@stdlib/ndarray/dtype' );

function isEven( value ) {
    return value % 2.0 === 0.0;
}

// Create an input ndarray:
var x = array( [ [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ] ] );
// returns <ndarray>

// Create an output ndarray:
var y = empty( [ 2, 2 ], {
    'dtype': getDType( x )
});

var opts = {
    'dims': [ 0 ]
};

// Perform reduction:
var out = find.assign( x, y, opts, isEven );
// returns <ndarray>[ [ NaN, 2.0 ], [ NaN, 6.0 ] ]

var bool = ( out === y );
// returns true

Notes

  • By default, when no sentinel is provided, the function returns a default sentinel value based on the input ndarray data-type:

    • real-valued floating-point data types: NaN.
    • complex-valued floating-point data types: NaN + NaNj.
    • integer data types: maximum value.
    • boolean data types: false.

  • The predicate function is provided the following arguments:

    • value: current array element.
    • indices: current array element indices.
    • arr: the input ndarray.

Examples

var uniform = require( '@stdlib/random/uniform' );
var isPositive = require( '@stdlib/assert/is-positive-number' ).isPrimitive;
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var find = require( '@stdlib/ndarray/find' );

var x = uniform( [ 2, 4, 5 ], -10.0, 10.0, {
    'dtype': 'float64'
});
console.log( ndarray2array( x ) );

var y = find( x, isPositive );
console.log( y.get() );