iterAdvance

Advance an iterator.

Usage

var iterAdvance = require( '@stdlib/iter/advance' );

iterAdvance( iterator[, n] )

Eagerly advances and returns a provided iterator.

var array2iterator = require( '@stdlib/array/to-iterator' );

var arr = array2iterator( [ 0, 0, 0, 0, 1 ] );
var it = iterAdvance( arr );

var bool = ( it === arr );
// returns true

var v = it.next().done;
// returns true

By default, the function eagerly consumes an entire iterator (i.e., n == 1e308). To limit the number of iterations, provide a second argument.

var array2iterator = require( '@stdlib/array/to-iterator' );

var arr = array2iterator( [ 0, 0, 0, 0, 1 ] );
var it = iterAdvance( arr, 4 );

var bool = ( it === arr );
// returns true

var v = it.next().value;
// returns 1

bool = it.next().done;
// returns true

Notes

The function eagerly advances an input iterator n iterations or until the input iterator finishes, whichever comes first.

This function is equivalent to performing manual iteration using a while loop.

var array2iterator = require( '@stdlib/array/to-iterator' );

var arr = array2iterator( [ 0, 0, 0, 0, 1 ] );

var i = 0;
var v;
while ( i < 4 ) {
    v = arr.next();
    if ( v.done ) {
        break;
    }
    i += 1;
}

v = arr.next().value;
// returns 1

var bool = arr.next().done;
// returns true

Examples

var randu = require( '@stdlib/random/iter/randu' );
var iterLength = require( '@stdlib/iter/length' );
var iterAdvance = require( '@stdlib/iter/advance' );

// Create an iterator which generates uniformly distributed pseudorandom numbers:
var opts = {
    'iter': 100
};
var it1 = randu( opts );

// Discard the first 10 values:
var it2 = iterAdvance( it1, 10 );

// Determine the iterator length:
var len = iterLength( it2 );
// returns 90