nditerColumnEntries

Create an iterator which returns [index, column] pairs for each column in a matrix (or stack of matrices).

Usage

var nditerColumnEntries = require( '@stdlib/ndarray/iter/column-entries' );

nditerColumnEntries( x[, options] )

Returns an iterator which returns [index, column] pairs for each column in a matrix (or stack of matrices).

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

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

var iter = nditerColumnEntries( x );

var v = iter.next().value;
// returns [...]

var idx = v[ 0 ];
// returns [ 0, null, 0 ]

var col = ndarray2array( v[ 1 ] );
// returns [ 1, 3 ]

v = iter.next().value;
// returns [...]

idx = v[ 0 ];
// returns [ 0, null, 1 ]

col = ndarray2array( v[ 1 ] );
// returns [ 2, 4 ]

// ...

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.

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

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

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

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

var v = iter.next().value;
// returns [...]

var col = ndarray2array( v[ 1 ] );
// returns [ 1, 3 ]

v[ 1 ].set( 0, 10 );

col = ndarray2array( v[ 1 ] );
// returns [ 10, 3 ]

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.

Notes

  • Each returned index is a Cartesian index (i.e., an array of subscripts/dimension indices). A dimension index equal to null indicates that all values along the respective dimension are included in the returned ndarray.
  • If an environment supports Symbol.iterator, the returned iterator is iterable.
  • A returned iterator does not copy a provided ndarray. To ensure iterable reproducibility, copy the input ndarray before creating an iterator. Otherwise, any changes to the contents of input ndarray will be reflected in the returned iterator.
  • In environments supporting Symbol.iterator, the function explicitly does not invoke an ndarray's @@iterator method, regardless of whether this method is defined.

Examples

var ndarray2array = require( '@stdlib/ndarray/to-array' );
var array = require( '@stdlib/ndarray/array' );
var zeroTo = require( '@stdlib/array/base/zero-to' );
var nditerColumnEntries = require( '@stdlib/ndarray/iter/column-entries' );

// Define an input array:
var x = array( zeroTo( 27 ), {
    'shape': [ 3, 3, 3 ]
});

// Create an iterator for returning [index, column] pairs:
var it = nditerColumnEntries( x );

// Perform manual iteration...
var v;
while ( true ) {
    v = it.next();
    if ( v.done ) {
        break;
    }
    console.log( v.value[ 0 ] );
    console.log( ndarray2array( v.value[ 1 ] ) );
}

See Also

Did you find this page helpful?