# sparsearray2iterator > Create an iterator from a sparse array-like object.
## Usage ```javascript var sparsearray2iterator = require( '@stdlib/array/to-sparse-iterator' ); ``` #### sparsearray2iterator( src\[, mapFcn\[, thisArg]] ) Returns an iterator which iterates over each element in a sparse array-like `object`. ```javascript var it = sparsearray2iterator( [ 1, , , 4 ] ); // returns var v = it.next().value; // returns 1 v = it.next().value; // returns 4 var bool = it.next().done; // returns true ``` 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 = sparsearray2iterator( [ 1, , 3, 4 ], fcn ); // returns var v = it.next().value; // returns 10.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 = sparsearray2iterator( [ 1, 2, , 4 ], fcn ); // returns var v = it.next().value; // returns 1 v = it.next().value; // returns 4 v = it.next().value; // returns 16 ``` 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 = sparsearray2iterator( [ 1, , 3, 4 ], fcn, ctx ); // returns var v = it.next().value; // returns 10.0 v = it.next().value; // returns 30.0 var count = ctx.count; // returns 2 ```
## Notes - If an environment supports `Symbol.iterator`, the returned iterator is iterable. - If provided a generic `array`, the returned iterator **ignores** holes (i.e., `undefined` values). To iterate over all generic `array` elements, use [`@stdlib/array/to-iterator`][@stdlib/array/to-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 sparsearray2iterator = require( '@stdlib/array/to-sparse-iterator' ); function scale( v, i ) { return v * (i+1); } // Create an array partially filled with random numbers: var arr = new Array( 100 ); var i; for ( i = 0; i < arr.length; i += 2 ) { arr[ i ] = randu(); } // Create an iterator from the array which scales iterated values: var it = sparsearray2iterator( arr, scale ); // Perform manual iteration... var v; while ( true ) { v = it.next(); if ( v.done ) { break; } console.log( v.value ); } ```
[@stdlib/array/to-iterator]: https://www.npmjs.com/package/@stdlib/array/tree/main/to-iterator