Zip

Generate array tuples from input arrays.

Usage

var zip = require( '@stdlib/utils/zip' );

zip( arr1, arr2,...[, opts] )

Returns an array of arrays, where the ith element (tuple) in the returned array contains the ith elements of the input arrays.

var zipped = zip( [ 1, 2 ], [ 'a', 'b' ] );
// returns [ [ 1, 'a' ], [ 2, 'b' ] ]

By default, the returned array length is the length of the shortest input array.

var zipped = zip( [ 1, 2, 3 ], [ 'a', 'b' ] );
// returns [ [ 1, 'a' ], [ 2, 'b' ] ]

The function accepts an options object with optional properties:

  • trunc: boolean specifying whether the returned array should truncate arrays longer than the shortest array. Default: true.
  • fill: fill value used for unequal length arrays. Default: null.
  • arrays: boolean specifying whether, when provided a single input array, the function should interpret the argument as a list of arrays to be zipped (i.e., behavior similar to zip.apply(null, arr)). Default: false.

To turn off truncation,

var opts = {
    'trunc': false
};

var zipped = zip( [ 1, 2, 3 ], [ 'a', 'b' ], opts );
// returns [ [ 1, 'a' ], [ 2, 'b' ], [ 3, null ] ]

A fill value is included in each tuple for each array which does not have an element at the ith index. By default, the fill value is null. To specify a different fill value, set the fill option.

var opts = {
    'trunc': false,
    'fill': ''
};

var zipped = zip( [ 1, 2, 3 ], [ 'a', 'b' ], opts );
// returns [ [ 1, 'a' ], [ 2, 'b' ], [ 3, '' ] ]

If the function should interpret a single input array as an array of arrays to be zipped,

var zipped;
var arr = [ [ 1, 2 ], [ 'a', 'b' ] ];

// Default behavior:
zipped = zip( arr );
// returns [ [ [ 1, 2 ] ], [ [ 'a', 'b' ] ] ]

// Array of arrays:
zipped = zip( arr, { 'arrays': true } );
// returns [ [ 1, 'a' ], [ 2, 'b' ] ]

Examples

var randu = require( '@stdlib/random/base/randu' );
var zip = require( '@stdlib/utils/zip' );

var zipped;
var len;
var y1;
var y2;
var y3;
var x;
var i;

// Simulate some data...
x = new Array( 100 );
len = x.length;
y1 = new Array( len );
y2 = new Array( len );
y3 = new Array( len );

for ( i = 0; i < len; i++ ) {
    x[ i ] = Date.now();
    y1[ i ] = randu() * 100;
    y2[ i ] = randu() * 100;
    y3[ i ] = randu();
}

zipped = zip( x, y1, y2, y3 );

console.log( zipped.join( '\n' ) );