# circarray2iterator > Create an iterator which repeatedly iterates over the elements of an array-like object.
## Usage ```javascript var circarray2iterator = require( '@stdlib/array/to-circular-iterator' ); ``` #### circarray2iterator( src\[, options]\[, mapFcn\[, thisArg]] ) Returns an iterator which repeatedly iterates over each element in an array-like `object`. ```javascript var it = circarray2iterator( [ 1, 2, 3, 4 ] ); // returns var v = it.next().value; // returns 1 v = it.next().value; // returns 2 v = it.next().value; // returns 3 v = it.next().value; // returns 4 v = it.next().value; // returns 1 v = it.next().value; // returns 2 v = it.next().value; // returns 3 v = it.next().value; // returns 4 // ... ``` 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. The function accepts the following `options`: - **iter**: number of iterations. Default: `1e308`. - **dir**: iteration direction. If set to `-1`, the iterator iterates over elements from right-to-left. Default: `1`. To limit the number of iterations, set the `iter` option. ```javascript var opts = { 'iter': 5 }; var it = circarray2iterator( [ 1, 2, 3, 4 ], opts ); // returns var v = it.next().value; // returns 1 v = it.next().value; // returns 2 v = it.next().value; // returns 3 v = it.next().value; // returns 4 v = it.next().value; // returns 1 var bool = it.next().done; // returns true ``` To iterate over elements from right to left, set the `dir` option to `-1`. ```javascript var opts = { 'dir': -1 }; var it = circarray2iterator( [ 1, 2, 3, 4 ], opts ); // returns var v = it.next().value; // returns 4 v = it.next().value; // returns 3 v = it.next().value; // returns 2 v = it.next().value; // returns 1 v = it.next().value; // returns 4 v = it.next().value; // returns 3 // ... ``` To invoke a function for each `src` value, provide a callback function. ```javascript function fcn( v ) { return v * 10.0; } var it = circarray2iterator( [ 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 four arguments: - `value`: iterated value - `index`: iterated value index - `n`: iteration count - `src`: source array-like object ```javascript function fcn( v, i ) { return v * (i+1); } var it = circarray2iterator( [ 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 = circarray2iterator( [ 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 a custom 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 circarray2iterator = require( '@stdlib/array/to-circular-iterator' ); function scale( v, i, n ) { return v * n; } // Create an array filled with random numbers: var arr = inmap( new Float64Array( 10 ), randu ); // Create an iterator from the array which scales iterated values: var opts = { 'iter': arr.length * 10 }; var it = circarray2iterator( arr, opts, scale ); // Perform manual iteration... var v; while ( true ) { v = it.next(); if ( v.done ) { break; } console.log( v.value ); } ```