where

Take elements from either one of two arrays depending on a condition.

Usage

var where = require( '@stdlib/array/base/where' );

where( condition, x, y )

Takes elements from either x or y depending on a condition.

var x = [ 1, 2, 3, 4 ];
var y = [ 5, 6, 7, 8 ];

var condition = [ true, false, true, false ];

var z = where( condition, x, y );
// returns [ 1, 6, 3, 8 ]

The function supports the following parameters:

• condition: array of values indicating whether to take an element from either x or y. If a condition element is truthy, the function takes a respective element from x; otherwise, the function takes a respective element from y. If non-empty, must be broadcast compatible with the resolved output array length.
• x: first input array. If condition is non-empty, must be broadcast compatible with the resolved output array length.
• y: second input array. If condition is non-empty, must be broadcast compatible with the resolved output array length.

When all input arrays are non-empty, the function supports broadcasting single-element arrays to the resolved output array length, which is equal to the maximum length of all provided input arrays.

var x = [ 1, 2, 3, 4 ];
var y = [ 5 ];

var condition = [ true, false, true, false ];

var z = where( condition, x, y );
// returns [ 1, 5, 3, 5 ]

z = where( condition, y, x );
// returns [ 5, 2, 5, 4 ]

z = where( [ true ], x, y );
// returns [ 1, 2, 3, 4 ]

z = where( [ false ], x, y );
// returns [ 5, 5, 5, 5 ]

z = where( condition, [ 1 ], y );
// returns [ 1, 5, 1, 5 ]

If condition is an empty array, the function returns an empty array.

var x = [ 1, 2, 3, 4 ];
var y = [ 5, 6, 7, 8 ];

var condition = [];

var z = where( condition, x, y );
// returns []

where.assign( condition, x, y, out, stride, offset )

Takes elements from either x or y depending on a condition and assigns the values to elements in a provided output array.

var x = [ 1, 2, 3, 4 ];
var y = [ 5, 6, 7, 8 ];

var out = [ 0, 0, 0, 0 ];
var condition = [ true, false, true, false ];

var arr = where.assign( condition, x, y, out, 1, 0 );
// returns [ 1, 6, 3, 8 ]

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

The function supports the following parameters:

• condition: array of values indicating whether to take an element from either x or y. If a condition element is truthy, the function takes a respective element from x; otherwise, the function takes a respective element from y. If non-empty, must be broadcast compatible with the output array.
• x: first input array. If condition is non-empty, must be broadcast compatible with the output array.
• y: second input array. If condition is non-empty, must be broadcast compatible with the output array.
• out: output array.
• stride: output array stride.
• offset: output array offset.

The function supports broadcasting single-element arrays to the output array length.

var x = [ 1, 2, 3, 4 ];
var y = [ 5 ];

var condition = [ true, false, true, false ];

var out = [ 0, 0, 0, 0 ];
var arr = where.assign( condition, x, y, out, 1, 0 );
// returns [ 1, 5, 3, 5 ]

out = [ 0, 0, 0, 0 ];
arr = where.assign( condition, y, x, out, 1, 0 );
// returns [ 5, 2, 5, 4 ]

out = [ 0, 0, 0, 0 ];
arr = where.assign( [ true ], x, y, out, 1, 0 );
// returns [ 1, 2, 3, 4 ]

out = [ 0, 0, 0, 0 ];
arr = where.assign( [ false ], x, y, out, 1, 0 );
// returns [ 5, 5, 5, 5 ]

out = [ 0, 0, 0, 0 ];
arr = where.assign( condition, [ 1 ], y, out, 1, 0 );
// returns [ 1, 5, 1, 5 ]

When condition is an empty array, the function returns the output array unchanged.

var x = [ 1, 2, 3, 4 ];
var y = [ 5, 6, 7, 8 ];

var out = [ 0, 0, 0, 0 ];
var condition = [];

var arr = where.assign( condition, x, y, out, 1, 0 );
// returns [ 0, 0, 0, 0 ]

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

Examples

var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
var bernoulli = require( '@stdlib/random/array/bernoulli' );
var where = require( '@stdlib/array/base/where' );

var opts = {
    'dtype': 'generic'
};

// Generate an array of indicator values:
var condition = bernoulli( 20, 0.9, opts );
console.log( condition );

// Generate an array of random values:
var x = discreteUniform( condition.length, 0, 10, opts );
console.log( x );

// Define an array containing a broadcasted "missing" value:
var y = [ NaN ];

// Return an array with randomly placed missing values:
var z = where( condition, x, y );
console.log( z );