time-to-botec

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

assign.js (3907B)

      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' ).assign;
     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 and assigns results to a provided output array.
     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 * @param {(Array|TypedArray|Object)} out - output array
     51 * @throws {TypeError} output argument must be either an array, typed array, or an object
     52 * @throws {TypeError} shape argument must be an array-like object containing nonnegative integers
     53 * @throws {TypeError} linear index argument must be integer valued
     54 * @throws {TypeError} options argument must be an object
     55 * @throws {TypeError} must provide valid options
     56 * @throws {RangeError} must provide a linear index which does not exceed array dimensions
     57 * @returns {NonNegativeIntegerArray} subscripts
     58 *
     59 * @example
     60 * var shape = [ 3, 3, 3 ];
     61 * var out = [ 0, 0, 0 ];
     62 *
     63 * var s = ind2sub( shape, 17, out );
     64 * // returns [ 1, 2, 2 ]
     65 *
     66 * var bool = ( s === out );
     67 * // returns true
     68 */
     69 function ind2sub( shape, idx, options, out ) {
     70 	var opts;
     71 	var dest;
     72 	var err;
     73 
     74 	opts = {};
     75 	opts.mode = defaults.mode;
     76 	opts.order = defaults.order;
     77 	if ( arguments.length === 4 ) {
     78 		err = validate( opts, arguments[ 2 ] );
     79 		if ( err ) {
     80 			throw err;
     81 		}
     82 		if ( typeof out !== 'object' || out === null ) {
     83 			throw new TypeError( 'invalid argument. Output argument must be either an array, typed array, or object. Value: `' + out + '`.' );
     84 		}
     85 		dest = out;
     86 	} else {
     87 		dest = options;
     88 		if ( typeof dest !== 'object' || dest === null ) {
     89 			throw new TypeError( 'invalid argument. Output argument must be either an array, typed array, or object. Value: `' + dest + '`.' );
     90 		}
     91 	}
     92 	if ( !isNonNegativeIntegerArray( shape ) ) {
     93 		throw new TypeError( 'invalid argument. Shape argument must be an array-like object containing nonnegative integers. Value: `' + shape + '`.' );
     94 	}
     95 	if ( !isInteger( idx ) ) {
     96 		throw new TypeError( 'invalid argument. Linear index argument must be integer valued. Value: `' + idx + '`.' );
     97 	}
     98 	// Note: strides are positive, so offset is always zero
     99 	return getSubscripts( shape, shape2strides( shape, opts.order ), 0, opts.order, idx, opts.mode, dest ); // eslint-disable-line max-len
    100 }
    101 
    102 
    103 // EXPORTS //
    104 
    105 module.exports = ind2sub;