time-to-botec

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

README.md (4411B)

      1 <!--
      2 
      3 @license Apache-2.0
      4 
      5 Copyright (c) 2018 The Stdlib Authors.
      6 
      7 Licensed under the Apache License, Version 2.0 (the "License");
      8 you may not use this file except in compliance with the License.
      9 You may obtain a copy of the License at
     10 
     11    http://www.apache.org/licenses/LICENSE-2.0
     12 
     13 Unless required by applicable law or agreed to in writing, software
     14 distributed under the License is distributed on an "AS IS" BASIS,
     15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     16 See the License for the specific language governing permissions and
     17 limitations under the License.
     18 
     19 -->
     20 
     21 # vind2bind
     22 
     23 > Convert a linear index in an array view to a linear index in an underlying data buffer.
     24 
     25 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
     26 
     27 <section class="intro">
     28 
     29 </section>
     30 
     31 <!-- /.intro -->
     32 
     33 <!-- Package usage documentation. -->
     34 
     35 <section class="usage">
     36 
     37 ## Usage
     38 
     39 ```javascript
     40 var vind2bind = require( '@stdlib/ndarray/base/vind2bind' );
     41 ```
     42 
     43 #### vind2bind( shape, strides, offset, order, idx, mode )
     44 
     45 Converts a linear index in an array view to a linear index in an underlying data buffer.
     46 
     47 ```javascript
     48 var shape = [ 3, 3 ];
     49 var order = 'row-major';
     50 var strides = [ -3, 1 ];
     51 var offset = 6;
     52 
     53 var idx = vind2bind( shape, strides, offset, order, 1, 'throw' );
     54 // returns 7
     55 ```
     56 
     57 The function supports the following `modes`:
     58 
     59 -   `throw`: specifies that the function should throw an error when a linear index exceeds array dimensions.
     60 -   `wrap`: specifies that the function should wrap around a linear index exceeding array dimensions using modulo arithmetic.
     61 -   `clamp`: specifies that the function should set a linear index exceeding array dimensions to either `0` (minimum linear index) or the maximum linear index.
     62 
     63 ```javascript
     64 var shape = [ 2, 2 ];
     65 var order = 'row-major';
     66 var strides = [ -2, 1 ];
     67 var offset = 2;
     68 
     69 var idx = vind2bind( shape, strides, offset, order, -2, 'wrap' );
     70 // returns 0
     71 
     72 idx = vind2bind( shape, strides, offset, order, 10, 'clamp' );
     73 // returns 1
     74 ```
     75 
     76 The `order` parameter specifies whether an array is `row-major` (C-style) or `column-major` (Fortran-style).
     77 
     78 ```javascript
     79 var shape = [ 2, 2 ];
     80 var order = 'column-major';
     81 var strides = [ 1, -2 ];
     82 var offset = 2;
     83 
     84 var idx = vind2bind( shape, strides, offset, order, 2, 'throw' );
     85 // returns 0
     86 ```
     87 
     88 </section>
     89 
     90 <!-- /.usage -->
     91 
     92 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
     93 
     94 <section class="notes">
     95 
     96 </section>
     97 
     98 <!-- /.notes -->
     99 
    100 <!-- Package usage examples. -->
    101 
    102 <section class="examples">
    103 
    104 ## Examples
    105 
    106 <!-- eslint no-undef: "error" -->
    107 
    108 ```javascript
    109 var shape2strides = require( '@stdlib/ndarray/base/shape2strides' );
    110 var strides2offset = require( '@stdlib/ndarray/base/strides2offset' );
    111 var numel = require( '@stdlib/ndarray/base/numel' );
    112 var randu = require( '@stdlib/random/base/randu' );
    113 var vind2bind = require( '@stdlib/ndarray/base/vind2bind' );
    114 
    115 // Specify array meta data:
    116 var shape = [ 3, 3, 3 ];
    117 var order = 'row-major';
    118 
    119 // Compute array meta data:
    120 var len = numel( shape );
    121 var strides = shape2strides( shape, order );
    122 
    123 // Randomly flip the sign of strides...
    124 var i;
    125 for ( i = 0; i < shape.length; i++ ) {
    126     if ( randu() < 0.5 ) {
    127         strides[ i ] *= -1;
    128     }
    129 }
    130 
    131 // Compute the underlying data buffer index offset:
    132 var offset = strides2offset( shape, strides );
    133 
    134 // Print array info:
    135 console.log( 'Dims: %s', shape.join( 'x' ) );
    136 console.log( 'Strides: %s', strides.join( ',' ) );
    137 console.log( 'Offset: %d', offset );
    138 
    139 // For each view index, determine the corresponding index into an array's underlying data buffer...
    140 var ind;
    141 for ( i = 0; i < len; i++ ) {
    142     ind = vind2bind( shape, strides, offset, order, i, 'throw' );
    143     console.log( 'view[%d] => buffer[%d]', i, ind );
    144 }
    145 ```
    146 
    147 </section>
    148 
    149 <!-- /.examples -->
    150 
    151 <!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
    152 
    153 <section class="references">
    154 
    155 </section>
    156 
    157 <!-- /.references -->
    158 
    159 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
    160 
    161 <section class="links">
    162 
    163 </section>
    164 
    165 <!-- /.links -->