nditerSelectDimension

Usage

var nditerSelectDimension = require( '@stdlib/ndarray/iter/select-dimension' );

nditerSelectDimension( x, dim[, options] )

Returns an iterator which iterates over each view along a specified dimension.

var array = require( '@stdlib/ndarray/array' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );

var x = array( [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ] );
// returns <ndarray>

var iter = nditerSelectDimension( x, 0 );

var v = iter.next().value;
// returns <ndarray>

var arr = ndarray2array( v );
// returns [ [ 1, 2 ], [ 3, 4 ] ]

v = iter.next().value;
// returns <ndarray>

arr = ndarray2array( v );
// returns [ [ 5, 6 ], [ 7, 8 ] ]

// ...

The function accepts the following options:

• readonly: boolean indicating whether returned ndarray views should be read-only. In order to return writable ndarray views, the input ndarray must be writable. If the input ndarray is read-only, setting this option to false raises an exception. Default: true.
• keepdim: boolean indicating whether returned ndarray views should include the selected dimension as a singleton dimension. If true, each returned view has the same number of dimensions as the input ndarray. Otherwise, each returned view has one fewer dimensions than the input ndarray. Default: false.

By default, the iterator returns ndarray views which are read-only. To return writable views, set the readonly option to false.

var array = require( '@stdlib/ndarray/array' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );

var x = array( [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ] );
// returns <ndarray>

var iter = nditerSelectDimension( x, 0, {
    'readonly': false
});

var v = iter.next().value;
// returns <ndarray>

var arr = ndarray2array( v );
// returns [ [ 1, 2 ], [ 3, 4 ] ]

v.set( 0, 0, 10 );

arr = ndarray2array( v );
// returns [ [ 10, 2 ], [ 3, 4 ] ]

By default, the iterator returns ndarray views which omit the selected dimension, resulting in ndarray views having one fewer dimensions than the provided input ndarray. To include the selected dimension as a singleton dimension in the returned ndarray views, set the keepdim option to true.

var array = require( '@stdlib/ndarray/array' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );

var x = array( [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ] );
// returns <ndarray>

var iter = nditerSelectDimension( x, 0, {
    'keepdim': true
});

var v = iter.next().value;
// returns <ndarray>

var arr = ndarray2array( v );
// returns [ [ [ 1, 2 ], [ 3, 4 ] ] ]

v = iter.next().value;
// returns <ndarray>

arr = ndarray2array( v );
// returns [ [ [ 5, 6 ], [ 7, 8 ] ] ]

// ...

The returned iterator protocol-compliant object has the following properties:

• next: function which returns an iterator protocol-compliant object containing the next iterated value (if one exists) assigned to a value property and a done property having a boolean value indicating whether the iterator is finished.
• return: function which closes an iterator and returns a single (optional) argument in an iterator protocol-compliant object.