# array2iterator > Create an iterator from an array-like object.
## Usage ```javascript var array2iterator = require( '@stdlib/array/to-iterator' ); ``` #### array2iterator( src\[, mapFcn\[, thisArg]] ) Returns an iterator which iterates over each element in an array-like `object`. ```javascript var it = array2iterator( [ 1, 2, 3, 4 ] ); // returns 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 `value` property and a `done` property having a `boolean` value 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. ```javascript function fcn( v ) { return v * 10.0; } var it = array2iterator( [ 1, 2, 3, 4 ], fcn ); // returns 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 ```javascript function fcn( v, i ) { return v * (i+1); } var it = array2iterator( [ 1, 2, 3, 4 ], fcn ); // returns 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`. ```javascript function fcn( v ) { this.count += 1; return v * 10.0; } var ctx = { 'count': 0 }; var it = array2iterator( [ 1, 2, 3, 4 ], fcn, ctx ); // returns 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`][@stdlib/array/to-sparse-iterator]. - A returned iterator does **not** copy a provided array-like `object`. To ensure iterable reproducibility, copy a provided array-like `object` **before** creating an iterator. Otherwise, any changes to the contents of an array-like `object` will be reflected in the returned iterator. - In environments supporting `Symbol.iterator`, the function **explicitly** does **not** invoke an array's `@@iterator` method, regardless of whether this method is defined. To convert an array to an implementation defined iterator, invoke this method directly.
## Examples ```javascript 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 ); } ```
[@stdlib/array/to-sparse-iterator]: https://www.npmjs.com/package/@stdlib/array/tree/main/to-sparse-iterator