iterMapN

Create an iterator which transforms iterated values from two or more iterators by applying the iterated values as arguments to a provided function.

Usage

var iterMapN = require( '@stdlib/iter/mapn' );

iterMapN( iter0, ...iterator, fcn[, thisArg] )

Returns an iterator which transforms iterated values from two or more iterators by applying the iterated values as arguments to a provided function.

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

function transform( x, y ) {
    return x + y;
}

var it1 = array2iterator( [ 1.0, 2.0 ] );
var it2 = array2iterator( [ 3.0, 4.0 ] );

var it = iterMapN( it1, it2, transform );
// returns <Object>

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

v = it.next().value;
// returns 6.0

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

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 invoked function is provided N+1 arguments, where N is the number of provided iterators and the last argument is the iteration index:

• ...value: iterated values.
• index: iteration index (zero-based).

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

function transform( x, y, i ) {
    return x + y + i;
}

var it1 = array2iterator( [ 1.0, 2.0 ] );
var it2 = array2iterator( [ 3.0, 4.0 ] );

var it = iterMapN( it1, it2, transform );
// returns <Object>

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

v = it.next().value;
// returns 7.0

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

To set the callback execution context, provide a thisArg.

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

function transform( x, y ) {
    this.count += 1;
    return x + y;
}

var it1 = array2iterator( [ 1.0, 2.0 ] );
var it2 = array2iterator( [ 3.0, 4.0 ] );

var ctx = {
    'count': 0
};
var it = iterMapN( it1, it2, transform, ctx );
// returns <Object>

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

v = it.next().value;
// returns 6.0

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

var count = ctx.count;
// returns 2

Notes

• The length of the returned iterator is equal to the length of the shortest provided iterator. In other words, the returned iterator ends once one of the provided iterators ends.
• If an environment supports Symbol.iterator and provided iterators are iterable, the returned iterator is iterable.

Examples

var iterSineWave = require( '@stdlib/simulate/iter/sine-wave' );
var iterMapN = require( '@stdlib/iter/mapn' );

function add( x, y ) {
    return x + y;
}

// Create an iterator which generates a sine wave:
var sine1 = iterSineWave({
    'period': 50,
    'offset': 0,
    'iter': 100
});

// Create another iterator which generates a higher frequency sine wave:
var sine2 = iterSineWave({
    'period': 10,
    'offset': 0,
    'iter': 100
});

// Create an iterator which adds the two waveforms:
var it = iterMapN( sine1, sine2, add );

// Perform manual iteration...
var v;
while ( true ) {
    v = it.next();
    if ( v.done ) {
        break;
    }
    console.log( v.value );
}

---

See Also

• @stdlib/iter/map: create an iterator which invokes a function for each iterated value.