Iterators

Iterator utilities.

Usage

var ns = require( '@stdlib/iter' );

ns

Namespace containing iterator utilities.

var objectKeys = require( '@stdlib/utils/keys' );

var keys = objectKeys( ns );
// e.g., returns [ 'iterAny', 'iterAnyBy', ... ]

iterAdvance( iterator[, n] ): advance an iterator.
iterAnyBy( iterator, predicate[, thisArg] ): test whether at least one iterated value passes a test implemented by a predicate function.
iterAny( iterator ): test whether at least one iterated value is truthy.
iterConcat( iter0, ...iterator ): create an iterator which iterates over the values of two or more iterators.
iterConstant( value[, options] ): create an iterator which always returns the same value.
iterCounter( iterator ): create an iterator which iteratively computes the number of iterated values.
iterDatespace( start, stop[, N][, options] ): create an iterator which returns evenly spaced dates over a specified interval.
iterDedupeBy( iterator, [limit,] fcn ): create an iterator which removes consecutive values that resolve to the same value according to a provided function.
iterDedupe( iterator[, limit] ): create an iterator which removes consecutive duplicated values.
iterEmpty(): create an empty iterator.
iterEveryBy( iterator, predicate[, thisArg] ): test whether every iterated value passes a test implemented by a predicate function.
iterEvery( iterator ): test whether all iterated values are truthy.
iterFill( iterator, value[, begin[, end]] ): create an iterator which replaces all values from a provided iterator from a start index to an end index with a static value.
iterFilterMap( iterator, fcn[, thisArg] ): create an iterator which both filters and maps the values of another iterator.
iterFilter( iterator, predicate[, thisArg] ): create an iterator which filters the values of another iterator according to a predicate function.
iterFirst( iterator ): return the first iterated value.
iterFlow( methods ): create a fluent interface for chaining together iterator methods.
iterForEach( iterator, fcn[, thisArg] ): create an iterator which invokes a function for each iterated value before returning the iterated value.
iterHead( iterator, n ): create an iterator which returns the first n values of a provided iterator.
iterIncrspace( start, stop[, increment] ): create an iterator which returns evenly spaced numbers according to a specified increment.
iterIntersectionByHash( iter0, ...iterator, hashFcn[, thisArg] ): create an iterator which returns the intersection of two or more iterators according to a hash function.
iterIntersection( iter0, ...iterator ): create an iterator which returns the intersection of two or more iterators.
iterLast( iterator ): consume an entire iterator and return the last iterated value.
iterLength( iterator ): return an iterator's length.
iterLinspace( start, stop[, N] ): create an iterator which returns evenly spaced numbers over a specified interval.
iterLogspace( start, stop[, N][, options] ): create an iterator which returns evenly spaced numbers over a specified interval.
iterMap( iterator, fcn[, thisArg] ): create an iterator which invokes a function for each iterated value.
iterMapN( iter0, ...iterator, fcn[, thisArg] ): create an iterator which transforms iterated values from two or more iterators by applying the iterated values as arguments to a provided function.
iterNoneBy( iterator, predicate[, thisArg] ): test whether every iterated value fails a test implemented by a predicate function.
iterNone( iterator ): test whether all iterated values are falsy.
iterNth( iterator, n ): return the nth iterated value.
iterThunk( iterFcn[, ...args] ): create an iterator "thunk".
iterPipeline( iterFcn0[, ...iterFcn] ): create an iterator pipeline.
iterPop( iterator[, clbk[, thisArg]] ): create an iterator which skips the last value of a provided iterator.
iterPush( iterator, ...items ): create an iterator which appends additional values to the end of a provided iterator.
iterReject( iterator, predicate[, thisArg] ): create an iterator which rejects the values of another iterator according to a predicate function.
iterReplicateBy( iterator, fcn[, thisArg] ): create an iterator which replicates each iterated value according to a provided function.
iterReplicate( iterator, n ): create an iterator which replicates each iterated value a specified number of times.
iterShift( iterator[, clbk[, thisArg]] ): create an iterator which skips the first value of a provided iterator.
iterSlice( iterator[, begin[, end]] ): create an iterator which returns a subsequence of iterated values from a provided iterator.
iterSomeBy( iterator, n, predicate[, thisArg] ): test whether at least n iterated values pass a test implemented by a predicate function.
iterSome( iterator, n ): test whether at least n iterated values are truthy.
iterStep( start, increment[, N] ): create an iterator which returns a sequence of numbers according to a specified increment.
iterStridedBy( iterator, fcn[, offset[, eager]][, thisArg] ): create an iterator which steps according to a provided callback function.
iterStrided( iterator, stride[, offset[, eager]] ): create an iterator which steps by a specified amount.
iterator2arrayviewRight( iterator, dest[, begin[, end]][, mapFcn[, thisArg]] ): fill an array-like object view from right to left with values returned from an iterator.
iterator2arrayview( iterator, dest[, begin[, end]][, mapFcn[, thisArg]] ): fill an array-like object view with values returned from an iterator.
iterUnion( iter0, ...iterator ): create an iterator which returns the union of two or more iterators.
iterUniqueByHash( iterator, hashFcn[, thisArg] ): create an iterator which returns unique values according to a hash function.
iterUniqueBy( iterator, predicate[, thisArg] ): create an iterator which returns unique values according to a predicate function.
iterUnique( iterator ): create an iterator which returns unique values.
iterUnitspace( start[, stop] ): create an iterator which returns numbers incremented by 1.
iterUnshift( iterator, ...items ): create an iterator which prepends values to the beginning of a provided iterator.
whileEach( iterator, predicate, fcn[, thisArg] ): create an iterator which, while a test condition is true, invokes a function for each iterated value before returning the iterated value.

Examples

var objectKeys = require( '@stdlib/utils/keys' );
var uncapitalize = require( '@stdlib/string/uncapitalize' );
var replace = require( '@stdlib/string/replace' );
var contains = require( '@stdlib/assert/contains' );
var randu = require( '@stdlib/random/iter/randu' );
var ns = require( '@stdlib/iter' );

// Create a fluent interface for chaining together iterator operations...

// Retrieve all the iterator utility names:
var keys = objectKeys( ns );

// Define a list of utilities to exclude from the fluent API:
var exclude = [ 'iterFlow', 'iterPipeline', 'iterThunk' ];

// Map each utility name to a fluent interface method...
var methods = {};
var key;
var k;
var i;
for ( i = 0; i < keys.length; i++ ) {
    key = keys[ i ];
    if ( contains( exclude, key ) ) {
        continue;
    }
    k = uncapitalize( replace( key, /^iter/, '' ) );
    methods[ k ] = ns[ key ];
}

// Create a fluent interface:
var FluentIterator = ns.iterFlow( methods );

// Create a new fluent interface iterator:
var it1 = new FluentIterator( randu() );

// Define a predicate function for filtering values:
function predicate( v ) {
    return ( v > 0.25 && v < 0.75 );
}

// Define a function which transforms iterated values:
function transform( v ) {
    return v * 10.0;
}

// Define a function to be invoked for each iterated value:
function log( v ) {
    console.log( v );
}

// Chain together a sequence of operations:
var it2 = it1.filter( predicate )
    .map( transform )
    .head( 10 )
    .forEach( log );

// Perform manual iteration...
var v;
while ( true ) {
    v = it2.next();
    if ( v.done ) {
        break;
    }
}