take3d

Take elements from a three-dimensional nested array.

Usage

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

take3d( x, indices, dimension, mode )

Takes elements along a specified dimension from a three-dimensional nested array according to a specified index mode.

var x = [ [ [ 1, 2 ], [ 3, 4 ] ] ];
var indices = [ 1, 1, 0, 0, -1, -1 ];

var y = take3d( x, indices, 2, 'normalize' );
// returns [ [ [ 2, 2, 1, 1, 2, 2 ], [ 4, 4, 3, 3, 4, 4 ] ] ]

The function accepts the following arguments:

x: input nested array.
indices: list of indices.
dimension: dimension along which to take elements. If provided a negative integer, the dimension is resolved relative to the last dimension, with the last dimension being -1.
mode: index mode specifying how to handle an index which is out-of-bounds.

If indices is an empty array, the function returns empty arrays along the specified dimension.

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

var y = take3d( x, [], 0, 'throw' );
// returns []

var z = take3d( x, [], 1, 'throw' );
// returns [ [] ]

var w = take3d( x, [], 2, 'throw' );
// returns [ [ [], [] ] ]

Notes

The function does not deep copy nested array elements.

Examples

var filled3dBy = require( '@stdlib/array/base/filled3d-by' );
var filledBy = require( '@stdlib/array/base/filled-by' );
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' );
var take3d = require( '@stdlib/array/base/take3d' );

// Generate a random array:
var shape = [ 3, 3, 3 ];
var x = filled3dBy( shape, discreteUniform.factory( 0, 100 ) );
console.log( x );

// Generate an array of random indices:
var N = discreteUniform( 1, 5 );
var indices = filledBy( N, discreteUniform.factory( 0, shape[2]-1 ) );
console.log( indices );

// Take a random sample of elements from `x`:
var y = take3d( x, indices, 2, 'throw' );
console.log( y );