# Find
> Find elements in an array-like object that satisfy a test condition.
## Usage
```javascript
var find = require( '@stdlib/utils/find' );
```
#### find( arr, \[opts,] clbk )
Finds elements in an array-like object that satisfy a test condition. The function accepts two options: `k` and `returns`.
- **k**: an `integer` which limits the number of elements returned and whose sign determines the direction in which to search. If set to a negative `integer`, the function searches from the last element to the first element.
- **returns**: specifies the type of result to return and may be one of three options: `indices`, `values`, `*`.
- **indices**: indicates to return the element indices of those elements satisfying the search condition.
- **values**: indicates to return the element values of those elements satisfying the search condition.
- **\***: indicates to return both the element indices and values of those elements satisfying the search condition. The returned result is an `array` of `arrays`, where each sub-array is an index-value pair.
The `callback` is provided three arguments:
- **element**: the current element
- **index**: the current element's index
- **array**: the input `array`, `typed array` or `string`
By default, `k` is the length of `arr` and `returns` is set to `indices`.
```javascript
var data = [ 30, 20, 50, 60, 10 ];
function greaterThan20( val ) {
return val > 20;
}
var vals = find( data, greaterThan20 );
// returns [ 0, 2, 3 ]
data = 'Hello World';
function isUpperCase( val ) {
return /[A-Z]/.test( val );
}
vals = find( data, isUpperCase );
// returns [ 0, 6 ]
```
To limit the number of results and specify that `values` should be returned,
```javascript
var data = [ 30, 20, 50, 60, 10 ];
var opts = {
'k': 2,
'returns': 'values'
};
function condition( val ) {
return val > 20;
}
var vals = find( data, opts, condition );
// returns [ 30, 50 ]
```
If no `array` elements satisfy the test condition, the function returns an empty `array`.
```javascript
var data = [ 30, 20, 50, 60, 10 ];
var opts = {
'k': 2,
'returns': 'values'
};
function condition( val ) {
return val > 1000;
}
var vals = find( data, opts, condition );
// returns []
```
To find the last two values satisfying a search condition,
```javascript
var data = [ 30, 20, 50, 60, 10 ];
var opts = {
'k': -2,
'returns': 'values'
};
function condition( val ) {
return val > 20;
}
var vals = find( data, opts, condition );
// returns [ 60, 50 ]
```
To explicitly specify that only indices are returned,
```javascript
var data = [ 30, 20, 50, 60, 10 ];
var opts = {
'k': -2,
'returns': 'indices'
};
function condition( val ) {
return val > 20;
}
var vals = find( data, opts, condition );
// returns [ 3, 2 ]
```
And to return both indices and values as index-value pairs,
```javascript
var data = [ 30, 20, 50, 60, 10 ];
var opts = {
'k': -2,
'returns': '*'
};
function condition( val ) {
return val > 20;
}
var vals = find( data, opts, condition );
// returns [ [3, 60], [2, 50] ]
```
## Examples
```javascript
var round = require( '@stdlib/math/base/special/round' );
var randu = require( '@stdlib/random/base/randu' );
var find = require( '@stdlib/utils/find' );
var data;
var opts;
var vals;
var i;
// Simulate the data...
data = new Array( 100 );
for ( i = 0; i < data.length; i++ ) {
data[ i ] = round( randu*100 );
}
// Find the first 10 values greater than 25...
opts = {
'k': 10,
'returns': '*'
};
function condition( val ) {
return val > 25;
}
vals = find( data, opts, condition );
console.log( vals.join( '\n' ) );
```