mskput

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

Usage

var mskput = require( '@stdlib/array/mskput' );

mskput( x, mask, values[, options] )

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

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

var out = mskput( x, [ 1, 0, 1, 0 ], [ 20, 40 ] );
// 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.
options: function options.

The function supports the following options:

mode: string specifying behavior when the number of values does not equal the number of falsy mask values. Default: 'repeat'.

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 falsy 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 falsy 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 falsy values in the mask array.

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

var out = mskput( x, [ 1, 0, 1, 0 ], [ 20 ], {
    'mode': '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 falsy values in the mask array.

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

var out = mskput( x, [ 0, 0, 1, 0 ], [ 20, 40 ], {
    'mode': '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 falsy, the corresponding element in x is replaced; otherwise, the corresponding element in x is "masked" and thus left unchanged.
The values array must have a data type which can be safely cast to the input array data type. Floating-point data types (both real and complex) are allowed to downcast to a lower precision data type of the same kind (e.g., element values from a 'float64' values array can be assigned to corresponding elements in a 'float32' input array).

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 mskput = require( '@stdlib/array/mskput' );

// 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 = mskput( x, mask, values );
console.log( out );