place

Replace elements of an array with provided values according to a provided mask array.

Usage

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

place( x, mask, values, mode )

Replaces elements of an array with provided values according to a provided mask array.

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

var out = place( x, [ 0, 1, 0, 1 ], [ 20, 40 ], 'strict' );
// returns [ 1, 20, 3, 40 ]

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

The function supports the following parameters:

x: input array.
mask: mask array.
values: values to set.
mode: string specifying behavior when the number of values does not equal the number of truthy mask values.

The function supports the following modes:

'strict': specifies that the function must raise an exception when the number of values does not exactly equal the number of truthy mask values.
'non_strict': specifies that the function must raise an exception when the function is provided insufficient values to satisfy the mask array.
'strict_broadcast': specifies that the function must broadcast a single-element values array and otherwise raise an exception when the number of values does not exactly equal the number of truthy mask values.
'broadcast': specifies that the function must broadcast a single-element values array and otherwise raise an exception when the function is provided insufficient values to satisfy the mask array.
'repeat': specifies that the function must reuse provided values when replacing elements in x in order to satisfy the mask array.

In broadcasting modes, the function supports broadcasting a values array containing a single element against the number of truthy values in the mask array.

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

var out = place( x, [ 0, 1, 0, 1 ], [ 20 ], 'strict_broadcast' );
// returns [ 1, 20, 3, 20 ]

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

In repeat mode, the function supports recycling elements in a values array to satisfy the number of truthy values in the mask array.

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

var out = place( x, [ 1, 1, 0, 1 ], [ 20, 40 ], 'repeat' );
// returns [ 20, 40, 3, 20 ]

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

Notes

The function mutates the input array x.
If a mask array element is truthy, the corresponding element in x is replaced; otherwise, the corresponding element in x is "masked" and thus left unchanged.

Examples

var filledBy = require( '@stdlib/array/base/filled-by' );
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' );
var bernoulli = require( '@stdlib/random/base/bernoulli' );
var linspace = require( '@stdlib/array/base/linspace' );
var place = require( '@stdlib/array/base/place' );

// Generate a linearly spaced array:
var x = linspace( 0, 100, 11 );
console.log( x );

// Generate a random mask array:
var N = discreteUniform( 5, 15 );
var mask = filledBy( N, bernoulli.factory( 0.3 ) );
console.log( mask );

// Generate an array of random values:
var values = filledBy( N, discreteUniform.factory( 1000, 2000 ) );
console.log( values );

// Update a random sample of elements in `x`:
var out = place( x, mask, values, 'non_strict' );
console.log( out );