README.md

fillSliceBy

Fill an input ndarray view according to a callback function.

Usage

var fillSliceBy = require( '@stdlib/ndarray/fill-slice-by' );

fillSliceBy( x, ...s[, options], fcn[, thisArg] )

Fills an input ndarray view according to a callback function.

var zeros = require( '@stdlib/ndarray/zeros' );
var Slice = require( '@stdlib/slice/ctor' );
var MultiSlice = require( '@stdlib/slice/multi' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );

function fcn( value ) {
    return value + 10.0;
}

var x = zeros( [ 3, 4 ], {
    'dtype': 'float64'
});

// Define the slice region:
var s0 = new Slice( 1, 3 );
var s1 = new Slice( 2, 4 );
var s = new MultiSlice( s0, s1 );

var y = fillSliceBy( x, s, fcn );
// returns <ndarray>

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

var arr = ndarray2array( y );
// returns [ [ 0.0, 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 10.0, 10.0 ], [ 0.0, 0.0, 10.0, 10.0 ] ]

The function accepts the following arguments:

• x: array-like object containing an input ndarray.
• s: a MultiSlice instance, an array of slice arguments, or slice arguments as separate arguments.
• options: function options.
• fcn: callback function.
• thisArg: callback function execution context (optional).

The function supports three (mutually exclusive) means for providing slice arguments:

1. providing a single MultiSlice instance.
2. providing a single array of slice arguments.
3. providing slice arguments as separate arguments.

The following example demonstrates each invocation style achieving equivalent results.

var zeros = require( '@stdlib/ndarray/zeros' );
var MultiSlice = require( '@stdlib/slice/multi' );
var Slice = require( '@stdlib/slice/ctor' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );

function clbk() {
    return 5.0;
}

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

// 1. Using a MultiSlice:
var x = zeros( [ 3, 4 ], opts );

var s0 = new Slice( 1, 3 );
var s1 = new Slice( 2, 4 );
var s = new MultiSlice( s0, s1 );

var out = fillSliceBy( x, s, clbk );
// returns <ndarray>

var arr = ndarray2array( out );
// returns [ [ 0.0, 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 5.0, 5.0 ], [ 0.0, 0.0, 5.0, 5.0 ] ]

// 2. Using an array of slice arguments:
x = zeros( [ 3, 4 ], opts );

s0 = new Slice( 1, 3 );
s1 = new Slice( 2, 4 );
s = new MultiSlice( s0, s1 );

out = fillSliceBy( x, [ s0, s1 ], clbk );
// returns <ndarray>

arr = ndarray2array( out );
// returns [ [ 0.0, 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 5.0, 5.0 ], [ 0.0, 0.0, 5.0, 5.0 ] ]

// 3. Providing separate arguments:
x = zeros( [ 3, 4 ], opts );

s0 = new Slice( 1, 3 );
s1 = new Slice( 2, 4 );
s = new MultiSlice( s0, s1 );

out = fillSliceBy( x, s0, s1, clbk );
// returns <ndarray>

arr = ndarray2array( out );
// returns [ [ 0.0, 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 5.0, 5.0 ], [ 0.0, 0.0, 5.0, 5.0 ] ]

The function supports the following options:

• strict: boolean indicating whether to enforce strict bounds checking.

By default, the function throws an error when provided a slice which exceeds array bounds. To ignore slice indices exceeding array bounds, set the strict option to false.

var zeros = require( '@stdlib/ndarray/zeros' );
var MultiSlice = require( '@stdlib/slice/multi' );
var Slice = require( '@stdlib/slice/ctor' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );

function clbk() {
    return 5.0;
}

var x = zeros( [ 3, 4 ], {
    'dtype': 'float64'
});

// Define the fill region:
var s0 = new Slice( 1, null, 1 );
var s1 = new Slice( 10, 20, 1 );
var s = new MultiSlice( s0, s1 );

var opts = {
    'strict': false
};

// Fill the region with a scalar value:
var y = fillSliceBy( x, s, opts, clbk );
// returns <ndarray>

var arr = ndarray2array( x );
// returns [ [ 0.0, 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 0.0, 0.0 ] ]

To set the callback function execution context, provide a thisArg.

var zeros = require( '@stdlib/ndarray/zeros' );
var Slice = require( '@stdlib/slice/ctor' );
var MultiSlice = require( '@stdlib/slice/multi' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );

function fcn( value ) {
    return value + this.factor;
}

var x = zeros( [ 3, 4 ], {
    'dtype': 'float64'
});

var ctx = {
    'factor': 10.0
};

// Define the slice region:
var s0 = new Slice( 1, 3 );
var s1 = new Slice( 2, 4 );
var s = new MultiSlice( s0, s1 );

var y = fillSliceBy( x, s, fcn, ctx );
// returns <ndarray>

var arr = ndarray2array( y );
// returns [ [ 0.0, 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 10.0, 10.0 ], [ 0.0, 0.0, 10.0, 10.0 ] ]

The callback function is provided the following arguments:

• value: current array element.
• indices: current array element indices.
• arr: the input ndarray.

Notes

• An input ndarray must be writable. If provided a read-only ndarray, the function throws an error.
• A slice argument must be either a Slice, an integer, null, or undefined.
• The function mutates the input ndarray.
• The function assumes that each element in the underlying input ndarray data buffer has one, and only one, corresponding element in input ndarray view (i.e., a provided ndarray is not a broadcasted ndarray view).

Examples

var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory;
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var zeros = require( '@stdlib/ndarray/zeros' );
var MultiSlice = require( '@stdlib/slice/multi' );
var Slice = require( '@stdlib/slice/ctor' );
var fillSliceBy = require( '@stdlib/ndarray/fill-slice-by' );

// Create a zero-filled ndarray:
var x = zeros( [ 2, 3, 4 ], {
    'dtype': 'generic'
});
console.log( ndarray2array( x ) );

// Specify the slice region:
var s0 = new Slice( 1, 2 );
var s1 = new Slice( null, null );
var s2 = new Slice( 2, 4 );
var s = new MultiSlice( s0, s1, s2 );

// Fill the slice:
fillSliceBy( x, s, discreteUniform( -100, 100 ) );
console.log( ndarray2array( x ) );