time-to-botec

Benchmark sampling in different programming languages
Log | Files | Refs | README

main.js (4099B)

      1 /**
      2 * @license Apache-2.0
      3 *
      4 * Copyright (c) 2018 The Stdlib Authors.
      5 *
      6 * Licensed under the Apache License, Version 2.0 (the "License");
      7 * you may not use this file except in compliance with the License.
      8 * You may obtain a copy of the License at
      9 *
     10 *    http://www.apache.org/licenses/LICENSE-2.0
     11 *
     12 * Unless required by applicable law or agreed to in writing, software
     13 * distributed under the License is distributed on an "AS IS" BASIS,
     14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     15 * See the License for the specific language governing permissions and
     16 * limitations under the License.
     17 */
     18 
     19 'use strict';
     20 
     21 // MODULES //
     22 
     23 var getSubscripts = require( './assign.js' );
     24 
     25 
     26 // MAIN //
     27 
     28 /**
     29 * Converts a linear index to an array of subscripts.
     30 *
     31 * ## Notes
     32 *
     33 * -   The function accepts the following "modes":
     34 *
     35 *     -   `throw`: throws an error when a linear index exceeds array dimensions.
     36 *     -   `wrap`: wrap around a linear index exceeding array dimensions using modulo arithmetic.
     37 *     -   `clamp`: set a linear index exceeding array dimensions to either `0` (minimum linear index) or the maximum linear index.
     38 *
     39 * -   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.
     40 *
     41 *     ```text
     42 *     Dims: 2x2
     43 *     Buffer: [ 1, 2, 3, 4 ]
     44 *
     45 *     View = [ a00, a01,
     46 *              a10, a11 ]
     47 *
     48 *     Strides: 2,1
     49 *     Offset: 0
     50 *
     51 *     View = [ 1, 2,
     52 *              3, 4 ]
     53 *
     54 *     Strides: 2,-1
     55 *     Offset: 1
     56 *
     57 *     View = [ 2, 1,
     58 *              4, 3 ]
     59 *
     60 *     Strides: -2,1
     61 *     Offset: 2
     62 *
     63 *     View = [ 3, 4,
     64 *              1, 2 ]
     65 *
     66 *     Strides: -2,-1
     67 *     Offset: 3
     68 *
     69 *     View = [ 4, 3,
     70 *              2, 1 ]
     71 *     ```
     72 *
     73 *     ```javascript
     74 *     var shape = [ 2, 2 ];
     75 *     var order = 'row-major';
     76 *     var strides = [ -2, 1 ];
     77 *     var offset = 2;
     78 *     var mode = 'throw';
     79 *
     80 *     // From the perspective of a view...
     81 *     var s = ind2sub( shape, strides, 0, order, 0, mode );
     82 *     // returns [ 0, 0 ]
     83 *
     84 *     s = ind2sub( shape, strides, 0, order, 1, mode );
     85 *     // returns [ 0, 1 ]
     86 *
     87 *     s = ind2sub( shape, strides, 0, order, 2, mode );
     88 *     // returns [ 1, 0 ]
     89 *
     90 *     s = ind2sub( shape, strides, 0, order, 3, mode );
     91 *     // returns [ 1, 1 ]
     92 *
     93 *     // From the perspective of an underlying buffer...
     94 *     s = ind2sub( shape, strides, offset, order, 0, mode );
     95 *     // returns [ 1, 0 ]
     96 *
     97 *     s = ind2sub( shape, strides, offset, order, 1, mode );
     98 *     // returns [ 1, 1 ]
     99 *
    100 *     s = ind2sub( shape, strides, offset, order, 2, mode );
    101 *     // returns [ 0, 0 ]
    102 *
    103 *     s = ind2sub( shape, strides, offset, order, 3, mode );
    104 *     // returns [ 0, 1 ]
    105 *     ```
    106 *
    107 *     In short, from the perspective of a view, view data is always ordered.
    108 *
    109 *
    110 * @param {NonNegativeIntegerArray} shape - array shape
    111 * @param {IntegerArray} strides - stride array
    112 * @param {NonNegativeInteger} offset - location of the first indexed value **based** on the stride array
    113 * @param {string} order - specifies whether an array is row-major (C-style) or column-major (Fortran-style)
    114 * @param {integer} idx - linear index
    115 * @param {string} mode - specifies how to handle a linear index which exceeds array dimensions
    116 * @throws {RangeError} linear index must not exceed array dimensions
    117 * @returns {Array} subscripts
    118 *
    119 * @example
    120 * var shape = [ 3, 3, 3 ];
    121 * var strides = [ 9, 6, 1 ];
    122 * var offset = 0;
    123 * var order = 'row-major';
    124 *
    125 * var s = ind2sub( shape, strides, offset, order, 17, 'throw' );
    126 * // returns [ 1, 2, 2 ]
    127 */
    128 function ind2sub( shape, strides, offset, order, idx, mode ) {
    129 	var out;
    130 	var i;
    131 
    132 	out = [];
    133 	for ( i = 0; i < shape.length; i++ ) {
    134 		out.push( 0 );
    135 	}
    136 	return getSubscripts( shape, strides, offset, order, idx, mode, out );
    137 }
    138 
    139 
    140 // EXPORTS //
    141 
    142 module.exports = ind2sub;