# iterator2array
> Create (or fill) an array from an iterator.
## Usage
```javascript
var iterator2array = require( '@stdlib/array/from-iterator' );
```
#### iterator2array( iterator\[, out]\[, mapFcn\[, thisArg]] )
Creates (or fills) an array from an `iterator`.
```javascript
var randu = require( '@stdlib/random/iter/randu' );
var opts = {
'iter': 10
};
var arr = iterator2array( randu( opts ) );
// returns
```
By default, the function creates and fills a generic `array`. To fill an array-like `object`, provide an `out` argument.
```javascript
var Float64Array = require( '@stdlib/array/float64' );
var randu = require( '@stdlib/random/iter/randu' );
var out = new Float64Array( 10 );
var arr = iterator2array( randu(), out );
// returns
var bool = ( out === arr );
// returns true
```
To invoke a function for each iterated value, provide a callback function.
```javascript
var array2iterator = require( '@stdlib/array/to-iterator' );
function fcn( v ) {
return v * 10.0;
}
var arr = iterator2array( array2iterator( [ 1, 2, 3, 4 ] ), fcn );
// returns [ 10.0, 20.0, 30.0, 40.0 ]
```
The invoked function is provided two arguments:
- `value`: iterated value
- `index`: iterated value index
```javascript
var Float64Array = require( '@stdlib/array/float64' );
var randu = require( '@stdlib/random/iter/randu' );
function fcn( v, i ) {
return v * (i+1);
}
var arr = iterator2array( randu(), new Float64Array( 10 ), fcn );
// returns
```
To set the callback function execution context, provide a `thisArg`.
```javascript
var Float64Array = require( '@stdlib/array/float64' );
var randu = require( '@stdlib/random/iter/randu' );
function fcn( v ) {
this.count += 1;
return v * 10.0;
}
var ctx = {
'count': 0
};
var arr = iterator2array( randu(), new Float64Array( 10 ), fcn, ctx );
// returns
var count = ctx.count;
// returns 10
```
## Notes
- If provided an output array, the function fills the output array with iterated values.
- Iteration stops when an output array is full **or** an iterator finishes; whichever comes first.
- By providing an output typed array, one avoids the temporary memory allocation when using the built-in `TypedArray.from`.
## Examples
```javascript
var Float64Array = require( '@stdlib/array/float64' );
var randu = require( '@stdlib/random/iter/randu' );
var iterator2array = require( '@stdlib/array/from-iterator' );
var opts;
var arr;
var it;
var i;
function scale( v, i ) {
return v * (i+1);
}
// Create an iterator for generating uniformly distributed pseudorandom numbers:
opts = {
'iter': 10
};
it = randu( opts );
// Fill an array with scaled iterator values:
arr = iterator2array( it, new Float64Array( opts.iter ), scale );
for ( i = 0; i < arr.length; i++ ) {
console.log( arr[ i ] );
}
```