External module "ndarray/base/sub2ind/docs/types/index.d"

Export assignment sub2ind

• sub2ind(shape: ArrayLike<number>, strides: ArrayLike<number>, offset: number, ...args: Array<number | Array<string>>): number

• Converts subscripts to a linear index.

  Notes

  • The function accepts the following "modes":

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

  • When provided fewer modes than dimensions, the function recycles modes using modulo arithmetic.

  • When provided a stride array containing negative strides, if an offset is greater than 0, the function treats subscripts as mapping to a linear index in an underlying data buffer for the array, thus returning a linear index from the perspective of that buffer. If an offset is equal to 0, the function treats subscripts as mapping to a linear index in an array view, thus returning a linear index 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 strides = [ -2, 1 ];
    var offset = 2;
    var mode = [ 'throw' ];
    
    // From the perspective of a view...
    var idx = sub2ind( shape, strides, 0, 0, 0, mode );
    // returns 0
    
    idx = sub2ind( shape, strides, 0, 0, 1, mode );
    // returns 1
    
    idx = sub2ind( shape, strides, 0, 1, 0, mode );
    // returns 2
    
    idx = sub2ind( shape, strides, 0, 1, 1, mode );
    // returns 3
    
    // From the perspective of an underlying buffer...
    idx = sub2ind( shape, strides, offset, 0, 0, mode );
    // returns 2
    
    idx = sub2ind( shape, strides, offset, 0, 1, mode );
    // returns 3
    
    idx = sub2ind( shape, strides, offset, 1, 0, mode );
    // returns 0
    
    idx = sub2ind( shape, strides, offset, 1, 1, mode );
    // returns 1

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

  throws

  must provide subscripts which do not exceed array dimensions

  Parameters

  • shape: ArrayLike<number>

    array shape

  • strides: ArrayLike<number>

    stride array

  • offset: number

    location of the first indexed value based on the stride array

  • Rest ...args: Array<number | Array<string>>

    subscripts followed by a mode specifying how to handle subscripts which exceed array dimensions

  Returns number

  linear index

  Example

  var shape = [ 3, 3, 3 ];
  var strides = [ 9, 3, 1 ];
  var offset = 0;
  var mode = [ 'throw' ]
  
  var idx = sub2ind( shape, strides, offset, 1, 2, 2, mode );
  // returns 17