time-to-botec/squiggle/node_modules/@stdlib/ndarray/sub2ind/README.md

sub2ind

Convert subscripts to a linear index.

Usage

var sub2ind = require( '@stdlib/ndarray/sub2ind' );

sub2ind( shape, ...subscripts[, options] )

Converts subscripts to a linear index.

var shape = [ 2, 2 ];

var idx = sub2ind( shape, 1, 0 );
// returns 2

The function supports the following options:

• mode: specifies how to handle subscripts which exceed array dimensions. The following modes are supported:

  • throw: specifies that the function should throw an error when a subscript exceeds array dimensions.
  • wrap: specifies that the function should wrap around subscripts exceeding array dimensions using modulo arithmetic.
  • clamp: specifies that the function should set subscripts exceeding array dimensions to either 0 (minimum index) or the maximum index along a particular dimension.

  If provided a mode array, each array element corresponds to a dimension. If provided fewer modes than dimensions, the function reuses modes using modulo arithmetic. Default: [ 'throw' ].

• order: specifies whether an array is row-major (C-style) or column-major (Fortran-style). Default: 'row-major'.

By default, the function assumes a row-major array. To return a linear index for a column-major array, set the order option.

var shape = [ 2, 2 ];
var opts = {};

opts.order = 'column-major';
var idx = sub2ind( shape, 1, 0, opts );
// returns 1

By default, the function throws an error if provided subscripts which exceed array dimensions. To specify alternative behavior, set the mode option.

var shape = [ 2, 2 ];
var opts = {};

opts.mode = 'wrap';
var idx = sub2ind( shape, -2, 0, opts );
// returns 0

opts.mode = 'clamp';
idx = sub2ind( shape, 10, 10, opts );
// returns 3

To specify separate modes for each dimension, provide a mode array.

var shape = [ 2, 2, 2 ];
var opts = {
    'mode': [
        'wrap',
        'clamp'
    ]
};

var idx = sub2ind( shape, -2, 10, -1, opts );
// returns 3

Examples

var numel = require( '@stdlib/ndarray/base/numel' );
var sub2ind = require( '@stdlib/ndarray/sub2ind' );

var shape = [ 3, 3, 3 ];
var len = numel( shape );

var arr = [];
var i;
for ( i = 0; i < len; i++ ) {
    arr.push( i );
}

var opts = {
    'order': 'column-major'
};

console.log( '' );
console.log( 'Dimensions: %s.', shape.join( 'x' ) );
console.log( 'View:' );
console.log( '' );

var slice;
var idx;
var row;
var j;
var k;
for ( k = 0; k < shape[ 2 ]; k++ ) {
    slice = 'A[:,:,'+k+'] = ';
    console.log( slice );
    for ( i = 0; i < shape[ 0 ]; i++ ) {
        row = '  ';
        for ( j = 0; j < shape[ 1 ]; j++ ) {
            idx = sub2ind( shape, i, j, k, opts );
            row += arr[ idx ];
            if ( j < shape[ 1 ]-1 ) {
                row += ', ';
            }
        }
        console.log( row );
    }
    console.log( '' );
}