array2iterator
Create an iterator from an array-like object.
Usage
var array2iterator = require( '@stdlib/array/to-iterator' );
array2iterator( src[, mapFcn[, thisArg]] )
Returns an iterator which iterates over each element in an array-like object.
var it = array2iterator( [ 1, 2, 3, 4 ] );
// returns <Object>
var v = it.next().value;
// returns 1
v = it.next().value;
// returns 2
v = it.next().value;
// returns 3
// ...
The returned iterator protocol-compliant object has the following properties:
- next: function which returns an iterator protocol-compliant object containing the next iterated value (if one exists) assigned to a
valueproperty and adoneproperty having abooleanvalue indicating whether the iterator is finished. - return: function which closes an iterator and returns a single (optional) argument in an iterator protocol-compliant object.
To invoke a function for each src value, provide a callback function.
function fcn( v ) {
return v * 10.0;
}
var it = array2iterator( [ 1, 2, 3, 4 ], fcn );
// returns <Object>
var v = it.next().value;
// returns 10.0
v = it.next().value;
// returns 20.0
v = it.next().value;
// returns 30.0
// ...
The invoked function is provided three arguments:
- value: iterated value.
- index: iterated value index.
- src: source array-like object.
function fcn( v, i ) {
return v * (i+1);
}
var it = array2iterator( [ 1, 2, 3, 4 ], fcn );
// returns <Object>
var v = it.next().value;
// returns 1
v = it.next().value;
// returns 4
v = it.next().value;
// returns 9
// ...
To set the callback function execution context, provide a thisArg.
function fcn( v ) {
this.count += 1;
return v * 10.0;
}
var ctx = {
'count': 0
};
var it = array2iterator( [ 1, 2, 3, 4 ], fcn, ctx );
// returns <Object>
var v = it.next().value;
// returns 10.0
v = it.next().value;
// returns 20.0
v = it.next().value;
// returns 30.0
var count = ctx.count;
// returns 3
Notes
- If an environment supports
Symbol.iterator, the returned iterator is iterable. - If provided a generic
array, the returned iterator does not ignore holes. To achieve greater performance for sparse arrays, use@stdlib/array/to-sparse-iterator. - A returned iterator does not copy a provided array-like
object. To ensure iterable reproducibility, copy a provided array-likeobjectbefore creating an iterator. Otherwise, any changes to the contents of an array-likeobjectwill be reflected in the returned iterator. - In environments supporting
Symbol.iterator, the function explicitly does not invoke an array's@@iteratormethod, regardless of whether this method is defined. To convert an array to an implementation defined iterator, invoke this method directly. - The returned iterator supports array-like objects having getter and setter accessors for array element access (e.g.,
@stdlib/array/complex64).
Examples
var Float64Array = require( '@stdlib/array/float64' );
var inmap = require( '@stdlib/utils/inmap' );
var randu = require( '@stdlib/random/base/randu' );
var array2iterator = require( '@stdlib/array/to-iterator' );
function scale( v, i ) {
return v * (i+1);
}
// Create an array filled with random numbers:
var arr = inmap( new Float64Array( 100 ), randu );
// Create an iterator from the array which scales iterated values:
var it = array2iterator( arr, scale );
// Perform manual iteration...
var v;
while ( true ) {
v = it.next();
if ( v.done ) {
break;
}
console.log( v.value );
}