ind2sub

ind2sub

Convert a linear index to an array of subscripts.

Usage

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

ind2sub( [out,] shape, strides, offset, order, idx, mode )

Converts a linear index to an array of subscripts.

var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 0;

var subscripts = ind2sub( shape, strides, offset, order, 1, 'throw' );
// returns [ 0, 1 ]

The function supports the following modes:

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

var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 0;

var idx = ind2sub( shape, strides, offset, order, -2, 'wrap' );
// returns [ 1, 0 ]

idx = ind2sub( shape, strides, offset, order, 10, 'clamp' );
// returns [ 1, 1 ]

The order parameter specifies whether an array is row-major (C-style) or column-major (Fortran-style).

var shape = [ 2, 2 ];
var order = 'column-major';
var strides = [ 1, 2 ];
var offset = 0;

var idx = ind2sub( shape, strides, offset, order, 2, 'throw' );
// returns [ 0, 1 ]

By default, the function returns subscripts in a new array. To avoid unnecessary memory allocation, the function supports providing an output (destination) object.

var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 0;

var out = new Array( shape.length );
var subscripts = ind2sub( out, shape, strides, offset, order, 1, 'throw' );
// returns [ 0, 1 ]

var bool = ( subscripts === out );
// returns true

Notes

• When provided a stride array containing negative strides, if an offset is greater than 0, the function interprets the linear index as an index into the underlying data buffer for the array, thus returning subscripts from the perspective of that buffer. If an offset is equal to 0, the function treats the linear index as an index into an array view, thus returning subscripts from the perspective of that view.

  Dims: 2x2
  Buffer: [ 1, 2, 3, 4 ]
  
  View = [ a00, a01,
           a10, a11 ]
  
  Strides: 2,1
  Offset: 0
  
  View = [ 1, 2,
           3, 4 ]
  
  Strides: 2,-1
  Offset: 1
  
  View = [ 2, 1,
           4, 3 ]
  
  Strides: -2,1
  Offset: 2
  
  View = [ 3, 4,
           1, 2 ]
  
  Strides: -2,-1
  Offset: 3
  
  View = [ 4, 3,
           2, 1 ]
  

  var shape = [ 2, 2 ];
  var order = 'row-major';
  var strides = [ -2, 1 ];
  var offset = 2;
  var mode = 'throw';
  
  // From the perspective of a view...
  var s = ind2sub( shape, strides, 0, order, 0, mode );
  // returns [ 0, 0 ]
  
  s = ind2sub( shape, strides, 0, order, 1, mode );
  // returns [ 0, 1 ]
  
  s = ind2sub( shape, strides, 0, order, 2, mode );
  // returns [ 1, 0 ]
  
  s = ind2sub( shape, strides, 0, order, 3, mode );
  // returns [ 1, 1 ]
  
  // From the perspective of an underlying buffer...
  s = ind2sub( shape, strides, offset, order, 0, mode );
  // returns [ 1, 0 ]
  
  s = ind2sub( shape, strides, offset, order, 1, mode );
  // returns [ 1, 1 ]
  
  s = ind2sub( shape, strides, offset, order, 2, mode );
  // returns [ 0, 0 ]
  
  s = ind2sub( shape, strides, offset, order, 3, mode );
  // returns [ 0, 1 ]

  In short, from the perspective of a view, view data is always ordered.

Examples

var discreteUniform = require( '@stdlib/random/base/discrete-uniform' );
var shape2strides = require( '@stdlib/ndarray/base/shape2strides' );
var strides2offset = require( '@stdlib/ndarray/base/strides2offset' );
var numel = require( '@stdlib/ndarray/base/numel' );
var randu = require( '@stdlib/random/base/randu' );
var abs = require( '@stdlib/math/base/special/abs' );
var ind2sub = require( '@stdlib/ndarray/base/ind2sub' );

// Specify array characteristics:
var shape = [ 3, 3, 3 ];
var order = 'row-major';

// Compute array meta data:
var ndims = shape.length;
var strides = shape2strides( shape, order );
var len = numel( shape );

// Determine stride indices to be used for formatting how views are displayed...
var s0;
var s1;
if ( order === 'column-major' ) {
    s0 = ndims - 1;
    s1 = s0 - 1;
} else { // row-major
    s0 = 0;
    s1 = s0 + 1;
}

// Initialize a linear array...
var arr = new Array( len );
var i;
for ( i = 0; i < len; i++ ) {
    arr[ i ] = 0;
}

// Generate random views and display the mapping of elements in the linear array to view subscripts...
var offset;
var row;
var j;
var s;
for ( i = 0; i < 20; i++ ) {
    // Randomly flip the sign of one of the strides...
    j = discreteUniform( 0, ndims-1 );
    strides[ j ] *= ( randu() < 0.5 ) ? -1 : 1;
    offset = strides2offset( shape, strides );

    // Print view meta data...
    console.log( '' );
    console.log( 'Dimensions: %s.', shape.join( 'x' ) );
    console.log( 'Strides: %s.', strides.join( ',' ) );
    console.log( 'View (subscripts):' );

    // Print the mapping of elements in the linear array to view subscripts...
    row = '  ';
    for ( j = 0; j < len; j++ ) {
        s = ind2sub( shape, strides, offset, order, j, 'throw' );
        row += '(' + s.join( ',' ) + ')';
        if ( ndims === 1 && j === len-1 ) {
            console.log( row );
        } else if ( ndims === 2 && (j+1)%abs( strides[ s0 ] ) === 0 ) {
            console.log( row );
            row = '  ';
        } else if ( ndims > 2 && (j+1)%abs( strides[ s1 ] ) === 0 ) {
            console.log( row );
            if ( (j+1)%abs( strides[ s0 ] ) === 0 ) {
                console.log( '' );
            }
            row = '  ';
        } else {
            row += ', ';
        }
    }
}