time-to-botec

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

README.md (4510B)

      1 <!--
      2 
      3 @license Apache-2.0
      4 
      5 Copyright (c) 2020 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 # gapx
     22 
     23 > Add a constant to each element in a strided array.
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 ```javascript
     30 var gapx = require( '@stdlib/blas/ext/base/gapx' );
     31 ```
     32 
     33 #### gapx( N, alpha, x, stride )
     34 
     35 Adds a constant `alpha` to each element in a strided array `x`.
     36 
     37 ```javascript
     38 var x = [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ];
     39 
     40 gapx( x.length, 5.0, x, 1 );
     41 // x => [ 3.0, 6.0, 8.0, 0.0, 9.0, 5.0, 4.0, 2.0 ]
     42 ```
     43 
     44 The function has the following parameters:
     45 
     46 -   **N**: number of indexed elements.
     47 -   **alpha**: scalar constant.
     48 -   **x**: input [`Array`][mdn-array] or [`typed array`][mdn-typed-array].
     49 -   **stride**: index increment.
     50 
     51 The `N` and `stride` parameters determine which elements in `x` are accessed at runtime. For example, to add a constant to every other element
     52 
     53 ```javascript
     54 var floor = require( '@stdlib/math/base/special/floor' );
     55 
     56 var x = [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ];
     57 var N = floor( x.length / 2 );
     58 
     59 gapx( N, 5.0, x, 2 );
     60 // x => [ 3.0, 1.0, 8.0, -5.0, 9.0, 0.0, 4.0, -3.0 ]
     61 ```
     62 
     63 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
     64 
     65 ```javascript
     66 var Float64Array = require( '@stdlib/array/float64' );
     67 var floor = require( '@stdlib/math/base/special/floor' );
     68 
     69 // Initial array...
     70 var x0 = new Float64Array( [ 1.0, -2.0, 3.0, -4.0, 5.0, -6.0 ] );
     71 
     72 // Create an offset view...
     73 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
     74 var N = floor( x0.length/2 );
     75 
     76 // Add a constant to every other element...
     77 gapx( N, 5.0, x1, 2 );
     78 // x0 => <Float64Array>[ 1.0, 3.0, 3.0, 1.0, 5.0, -1.0 ]
     79 ```
     80 
     81 #### gapx.ndarray( N, alpha, x, stride, offset )
     82 
     83 Adds a constant `alpha` to each element in a strided array `x` using alternative indexing semantics.
     84 
     85 ```javascript
     86 var x = [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ];
     87 
     88 gapx.ndarray( x.length, 5.0, x, 1, 0 );
     89 // x => [ 3.0, 6.0, 8.0, 0.0, 9.0, 5.0, 4.0, 2.0 ]
     90 ```
     91 
     92 The function has the following additional parameters:
     93 
     94 -   **offset**: starting index.
     95 
     96 While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offset` parameter supports indexing semantics based on a starting index. For example, to access only the last three elements of `x`
     97 
     98 ```javascript
     99 var x = [ 1.0, -2.0, 3.0, -4.0, 5.0, -6.0 ];
    100 
    101 gapx.ndarray( 3, 5.0, x, 1, x.length-3 );
    102 // x => [ 1.0, -2.0, 3.0, 1.0, 10.0, -1.0 ]
    103 ```
    104 
    105 </section>
    106 
    107 <!-- /.usage -->
    108 
    109 <section class="notes">
    110 
    111 ## Notes
    112 
    113 -   If `N <= 0`, both functions return `x` unchanged.
    114 -   Depending on the environment, the typed versions ([`dapx`][@stdlib/blas/ext/base/dapx], [`sapx`][@stdlib/blas/ext/base/sapx], etc.) are likely to be significantly more performant.
    115 
    116 </section>
    117 
    118 <!-- /.notes -->
    119 
    120 <section class="examples">
    121 
    122 ## Examples
    123 
    124 <!-- eslint no-undef: "error" -->
    125 
    126 ```javascript
    127 var round = require( '@stdlib/math/base/special/round' );
    128 var randu = require( '@stdlib/random/base/randu' );
    129 var Float64Array = require( '@stdlib/array/float64' );
    130 var gapx = require( '@stdlib/blas/ext/base/gapx' );
    131 
    132 var rand;
    133 var sign;
    134 var x;
    135 var i;
    136 
    137 x = new Float64Array( 10 );
    138 for ( i = 0; i < x.length; i++ ) {
    139     rand = round( randu()*100.0 );
    140     sign = randu();
    141     if ( sign < 0.5 ) {
    142         sign = -1.0;
    143     } else {
    144         sign = 1.0;
    145     }
    146     x[ i ] = sign * rand;
    147 }
    148 console.log( x );
    149 
    150 gapx( x.length, 5.0, x, 1 );
    151 console.log( x );
    152 ```
    153 
    154 </section>
    155 
    156 <!-- /.examples -->
    157 
    158 <section class="links">
    159 
    160 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
    161 
    162 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
    163 
    164 [@stdlib/blas/ext/base/dapx]: https://www.npmjs.com/package/@stdlib/blas/tree/main/ext/base/dapx
    165 
    166 [@stdlib/blas/ext/base/sapx]: https://www.npmjs.com/package/@stdlib/blas/tree/main/ext/base/sapx
    167 
    168 </section>
    169 
    170 <!-- /.links -->