# iterStridedBy > Create an [iterator][mdn-iterator-protocol] which steps according to a provided callback function.
## Usage ```javascript var iterStridedBy = require( '@stdlib/iter/strided-by' ); ``` #### iterStridedBy( iterator, fcn\[, offset\[, eager]]\[, thisArg] ) Returns an [iterator][mdn-iterator-protocol] which steps according to a provided callback function. ```javascript var array2iterator = require( '@stdlib/array/to-iterator' ); function stride( v, i ) { return (i % 10) + 1; } var arr = array2iterator( [ 1, 2, 3, 4, 5, 6, 7, 8 ] ); var it = iterStridedBy( arr, stride ); // returns var r = it.next().value; // returns 1 r = it.next().value; // returns 2 r = it.next().value; // returns 4 // ... ``` The returned [iterator][mdn-iterator-protocol] protocol-compliant object has the following properties: - **next**: function which returns an [iterator][mdn-iterator-protocol] 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][mdn-iterator-protocol] and returns a single (optional) argument in an [iterator][mdn-iterator-protocol] protocol-compliant object. The callback function is provided four arguments: - **value**: iterated value - **i**: source iteration index (zero-based) - **n**: iteration index (zero-based) - **curr**: current stride To set the callback execution context, provide a `thisArg`. ```javascript var array2iterator = require( '@stdlib/array/to-iterator' ); function stride( v, i ) { this.count += 1; return (i % 10) + 1; } var ctx = { 'count': 0 }; var arr = array2iterator( [ 1, 2, 3, 4, 5, 6, 7, 8 ] ); var it = iterStridedBy( arr, stride, ctx ); // returns var v = it.next().value; // returns 1 v = it.next().value; // returns 2 v = it.next().value; // returns 4 v = it.next().value; // returns 8 var count = ctx.count; // returns 4 ``` To skip the first `N` values of a provided [`iterator`][mdn-iterator-protocol], provide an `offset` argument. ```javascript var array2iterator = require( '@stdlib/array/to-iterator' ); function stride( v, i ) { return (i % 10) + 1; } var arr = array2iterator( [ 1, 2, 3, 4, 5, 6, 7, 8 ] ); var it = iterStridedBy( arr, stride, 1 ); // returns var r = it.next().value; // returns 2 r = it.next().value; // returns 4 r = it.next().value; // returns 8 // ... ``` By default, the returned [iterator][mdn-iterator-protocol] defers consuming the first `N` input [`iterator`][mdn-iterator-protocol] values until the first value of the returned [iterator][mdn-iterator-protocol] is consumed. To eagerly advance the input [`iterator`][mdn-iterator-protocol], set the `eager` argument to `true`. ```javascript var array2iterator = require( '@stdlib/array/to-iterator' ); function stride() { return 1; } var arr = array2iterator( [ 1, 2, 3, 4, 5, 6, 7, 8 ] ); var it = iterStridedBy( arr, stride, 4, true ); // returns var r = it.next().value; // returns 5 r = it.next().value; // returns 6 r = it.next().value; // returns 7 // ... ```
## Notes - A callback function **must** return a **positive integer** value. - If an environment supports `Symbol.iterator` **and** a provided [iterator][mdn-iterator-protocol] is iterable, the returned [iterator][mdn-iterator-protocol] is iterable.
## Examples ```javascript var randu = require( '@stdlib/random/iter/randu' ); var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory; var iterStridedBy = require( '@stdlib/iter/strided-by' ); // Create a seeded iterator for generating pseudorandom numbers: var rand = randu({ 'seed': 1234, 'iter': 10 }); // Create a PRNG for generating pseudorandom integers on the interval [1,10]: var randi = discreteUniform( 1, 10, { 'seed': 4321 }); // Create an iterator which randomly selects input iterator values: var it = iterStridedBy( rand, randi ); // Perform manual iteration... var r; while ( true ) { r = it.next(); if ( r.done ) { break; } console.log( r.value ); } ```
* * * ## See Also - [`@stdlib/iter/advance`][@stdlib/iter/advance]: advances an iterator. - [`@stdlib/iter/nth`][@stdlib/iter/nth]: return the nth iterated value. - [`@stdlib/iter/strided`][@stdlib/iter/strided]: create an iterator which steps by a specified amount.
[mdn-iterator-protocol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol [@stdlib/iter/advance]: https://github.com/stdlib-js/iter/tree/main/advance [@stdlib/iter/nth]: https://github.com/stdlib-js/iter/tree/main/nth [@stdlib/iter/strided]: https://github.com/stdlib-js/iter/tree/main/strided