# iterFirst
> Return the first [iterated][mdn-iterator-protocol] value.
## Usage
```javascript
var iterFirst = require( '@stdlib/iter/first' );
```
#### iterFirst( iterator )
Returns the first [iterated][mdn-iterator-protocol] value.
```javascript
var array2iterator = require( '@stdlib/array/to-iterator' );
var arr = array2iterator( [ 1, 0, 0, 0, 0 ] );
var v = iterFirst( arr );
// returns 1
```
If a provided [`iterator`][mdn-iterator-protocol] does not return any [iterated][mdn-iterator-protocol] values, the function returns `undefined`.
```javascript
var iterEmpty = require( '@stdlib/iter/empty' );
var v = iterFirst( iterEmpty() );
// returns undefined
```
## Notes
- The function does **not** consume an entire [iterator][mdn-iterator-protocol] before returning.
## Examples
```javascript
var randu = require( '@stdlib/random/iter/randu' );
var iterMap = require( '@stdlib/iter/map' );
var iterFirst = require( '@stdlib/iter/first' );
function threshold( r ) {
return ( r > 0.95 );
}
// Create an iterator which generates uniformly distributed pseudorandom numbers:
var opts = {
'iter': 100
};
var riter = randu( opts );
// Create an iterator which applies a threshold to generated numbers:
var miter = iterMap( riter, threshold );
// Return the first threshold result:
var bool = iterFirst( miter );
// returns
console.log( bool );
```
[mdn-iterator-protocol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol
[@stdlib/iter/head]: https://github.com/stdlib-js/iter/tree/main/head
[@stdlib/iter/last]: https://github.com/stdlib-js/iter/tree/main/last
[@stdlib/iter/nth]: https://github.com/stdlib-js/iter/tree/main/nth