# iterSlice > Create an [iterator][mdn-iterator-protocol] which returns a subsequence of iterated values from a provided [iterator][mdn-iterator-protocol].
## Usage ```javascript var iterSlice = require( '@stdlib/iter/slice' ); ``` #### iterSlice( iterator\[, begin\[, end]] ) Returns an [iterator][mdn-iterator-protocol] which returns a subsequence of iterated values from a provided [iterator][mdn-iterator-protocol]. ```javascript var array2iterator = require( '@stdlib/array/to-iterator' ); var it = iterSlice( 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][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][mdn-iterator-protocol] 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. By default, the returned [iterator][mdn-iterator-protocol] returns a provided [iterator's][mdn-iterator-protocol] first iterated value through an [iterator's][mdn-iterator-protocol] last iterated value. To specify an alternative start iteration index (zero-based and **inclusive**), provide a `begin` argument. ```javascript var array2iterator = require( '@stdlib/array/to-iterator' ); var it = iterSlice( array2iterator( [ 1, 2, 3, 4 ] ), 2 ); // returns var v = it.next().value; // returns 3 v = it.next().value; // returns 4 var bool = it.next().done; // returns true ``` By default, the returned [iterator][mdn-iterator-protocol] continues iterating until it consumes all of a provided [iterator's][mdn-iterator-protocol] iterated values. To specify an end iteration index (zero-based and **non-inclusive**), provide an `end` argument. ```javascript var array2iterator = require( '@stdlib/array/to-iterator' ); var it = iterSlice( array2iterator( [ 1, 2, 3, 4 ] ), 1, 3 ); // returns var v = it.next().value; // returns 2 v = it.next().value; // returns 3 var bool = it.next().done; // returns true ``` If `begin` is greater than or equal to `end`, the returned [iterator][mdn-iterator-protocol] does not return any iterated values. ```javascript var array2iterator = require( '@stdlib/array/to-iterator' ); var it = iterSlice( array2iterator( [ 1, 2, 3, 4 ] ), 3, 1 ); // returns var bool = it.next().done; // returns true ```
## Notes - 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 iterSlice = require( '@stdlib/iter/slice' ); // Create a seeded iterator for generating pseudorandom numbers: var rand = randu({ 'seed': 1234 }); // Create an iterator which returns a subsequence of 10 generated numbers: var it = iterSlice( rand, 10, 20 ); // Perform manual iteration... var r; while ( true ) { r = it.next(); if ( r.done ) { break; } console.log( r.value ); } ```
* * * ## See Also - [`@stdlib/iter/first`][@stdlib/iter/first]: return the first iterated value. - [`@stdlib/iter/head`][@stdlib/iter/head]: create an iterator which returns the first `n` values of a provided iterator.
[mdn-iterator-protocol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol [@stdlib/iter/first]: https://github.com/stdlib-js/iter/tree/main/first [@stdlib/iter/head]: https://github.com/stdlib-js/iter/tree/main/head