time-to-botec

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

main.js (3153B)

      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 isNonNegativeIntegerArray = require( '@stdlib/assert/is-nonnegative-integer-array' ).primitives;
     24 var isInteger = require( '@stdlib/assert/is-integer' ).isPrimitive;
     25 var shape2strides = require( './../../base/shape2strides' );
     26 var getSubscripts = require( './../../base/ind2sub' );
     27 var defaults = require( './defaults.json' );
     28 var validate = require( './validate.js' );
     29 
     30 
     31 // MAIN //
     32 
     33 /**
     34 * Converts a linear index to an array of subscripts.
     35 *
     36 * ## Notes
     37 *
     38 * -   The function accepts the following "modes":
     39 *
     40 *     -   `throw`: throws an error when a linear index exceeds array dimensions.
     41 *     -   `wrap`: wrap around a linear index exceeding array dimensions using modulo arithmetic.
     42 *     -   `clamp`: set a linear index exceeding array dimensions to either `0` (minimum linear index) or the maximum linear index.
     43 *
     44 *
     45 * @param {NonNegativeIntegerArray} shape - array shape
     46 * @param {integer} idx - linear index
     47 * @param {Options} [options] - function options
     48 * @param {string} [options.mode="throw"] - specifies how to handle a linear index which exceeds array dimensions
     49 * @param {string} [options.order="row-major"] - specifies whether an array is row-major (C-style) or column-major (Fortran-style)
     50 * @throws {TypeError} shape argument must be an array-like object containing nonnegative integers
     51 * @throws {TypeError} linear index argument must be integer valued
     52 * @throws {TypeError} options argument must be an object
     53 * @throws {TypeError} must provide valid options
     54 * @throws {RangeError} must provide a linear index which does not exceed array dimensions
     55 * @returns {NonNegativeIntegerArray} subscripts
     56 *
     57 * @example
     58 * var s = ind2sub( [ 3, 3, 3 ], 17 );
     59 * // returns [ 1, 2, 2 ]
     60 */
     61 function ind2sub( shape, idx, options ) {
     62 	var opts;
     63 	var err;
     64 
     65 	opts = {};
     66 	opts.mode = defaults.mode;
     67 	opts.order = defaults.order;
     68 	if ( arguments.length > 2 ) {
     69 		err = validate( opts, options );
     70 		if ( err ) {
     71 			throw err;
     72 		}
     73 	}
     74 	if ( !isNonNegativeIntegerArray( shape ) ) {
     75 		throw new TypeError( 'invalid argument. Shape argument must be an array-like object containing nonnegative integers. Value: `' + shape + '`.' );
     76 	}
     77 	if ( !isInteger( idx ) ) {
     78 		throw new TypeError( 'invalid argument. Linear index argument must be integer valued. Value: `' + idx + '`.' );
     79 	}
     80 	// Note: strides are positive, so offset is always zero
     81 	return getSubscripts( shape, shape2strides( shape, opts.order ), 0, opts.order, idx, opts.mode ); // eslint-disable-line max-len
     82 }
     83 
     84 
     85 // EXPORTS //
     86 
     87 module.exports = ind2sub;