time-to-botec

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

README.md (6809B)

      1 <!--
      2 
      3 @license Apache-2.0
      4 
      5 Copyright (c) 2021 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 <!-- lint disable maximum-heading-length -->
     22 
     23 # atanhBy
     24 
     25 > Compute the [hyperbolic arctangent][@stdlib/math/base/special/atanh] of each element retrieved from an input strided array via a callback function.
     26 
     27 <section class="intro">
     28 
     29 </section>
     30 
     31 <!-- /.intro -->
     32 
     33 <section class="usage">
     34 
     35 ## Usage
     36 
     37 ```javascript
     38 var atanhBy = require( '@stdlib/math/strided/special/atanh-by' );
     39 ```
     40 
     41 #### atanhBy( N, x, strideX, y, strideY, clbk\[, thisArg] )
     42 
     43 Computes the [hyperbolic arctangent][@stdlib/math/base/special/atanh] of each element retrieved from an input strided array `x` via a callback function and assigns each result to an element in an output strided array `y`.
     44 
     45 ```javascript
     46 function accessor( v ) {
     47     return v;
     48 }
     49 
     50 var x = [ 0.0, -0.5, 1.0, -0.25, 0.75 ];
     51 var y = [ 0.0, 0.0, 0.0, 0.0, 0.0 ];
     52 
     53 atanhBy( x.length, x, 1, y, 1, accessor );
     54 // y => [ 0.0, ~-0.549, Infinity, ~-0.255, ~0.973 ]
     55 ```
     56 
     57 The function accepts the following arguments:
     58 
     59 -   **N**: number of indexed elements.
     60 -   **x**: input [`Array`][mdn-array], [`typed array`][mdn-typed-array], or an array-like object (excluding strings and functions).
     61 -   **strideX**: index increment for `x`.
     62 -   **y**: output [`Array`][mdn-array], [`typed array`][mdn-typed-array], or an array-like object (excluding strings and functions).
     63 -   **strideY**: index increment for `y`.
     64 -   **clbk**: callback function.
     65 -   **thisArg**: execution context (_optional_).
     66 
     67 The invoked callback function is provided six arguments:
     68 
     69 -   **value**: input array element.
     70 -   **idx**: iteration index (zero-based).
     71 -   **xi**: input array strided index (`offsetX + idx*strideX`).
     72 -   **yi**: output array strided index (`offsetY + idx*strideY`).
     73 -   **x**: input array/collection.
     74 -   **y**: output array/collection.
     75 
     76 To set the callback execution context, provide a `thisArg`.
     77 
     78 ```javascript
     79 function accessor( v ) {
     80     this.count += 1;
     81     return v;
     82 }
     83 
     84 var context = {
     85     'count': 0
     86 };
     87 
     88 var x = [ 0.0, -0.5, 1.0, -0.25, 0.75 ];
     89 var y = [ 0.0, 0.0, 0.0, 0.0, 0.0 ];
     90 
     91 atanhBy( x.length, x, 1, y, 1, accessor, context );
     92 // y => [ 0.0, ~-0.549, Infinity, ~-0.255, ~0.973 ]
     93 
     94 var cnt = context.count;
     95 // returns 8
     96 ```
     97 
     98 The `N` and `stride` parameters determine which elements in `x` and `y` are accessed at runtime. For example, to index every other value in `x` and to index the first `N` elements of `y` in reverse order,
     99 
    100 ```javascript
    101 function accessor( v ) {
    102     return v;
    103 }
    104 
    105 var x = [ 0.0, -0.5, 1.0, -0.25, 0.75, -0.68 ];
    106 var y = [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ];
    107 
    108 atanhBy( 3, x, 2, y, -1, accessor );
    109 // y => [ ~0.973, Infinity, 0.0, 0.0, 0.0, 0.0 ]
    110 ```
    111 
    112 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
    113 
    114 ```javascript
    115 var Float64Array = require( '@stdlib/array/float64' );
    116 
    117 function accessor( v ) {
    118     return v;
    119 }
    120 
    121 // Initial arrays...
    122 var x0 = new Float64Array( [ 0.0, -0.5, 1.0, -0.25, 0.75, -0.68 ] );
    123 var y0 = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] );
    124 
    125 // Create offset views...
    126 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
    127 var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*3 ); // start at 4th element
    128 
    129 atanhBy( 3, x1, -2, y1, 1, accessor );
    130 // y0 => <Float64Array>[ 0.0, 0.0, 0.0, ~-0.829, ~-0.255, ~-0.549 ]
    131 ```
    132 
    133 #### atanhBy.ndarray( N, x, strideX, offsetX, y, strideY, offsetY, clbk\[, thisArg] )
    134 
    135 Computes the [hyperbolic arctangent][@stdlib/math/base/special/atanh] of each element retrieved from an input strided array `x` via a callback function and assigns each result to an element in an output strided array `y` using alternative indexing semantics.
    136 
    137 ```javascript
    138 function accessor( v ) {
    139     return v;
    140 }
    141 
    142 var x = [ 0.0, -0.5, 1.0, -0.25, 0.75 ];
    143 var y = [ 0.0, 0.0, 0.0, 0.0, 0.0 ];
    144 
    145 atanhBy.ndarray( x.length, x, 1, 0, y, 1, 0, accessor );
    146 // y => [ 0.0, ~-0.549, Infinity, ~-0.255, ~0.973 ]
    147 ```
    148 
    149 The function accepts the following additional arguments:
    150 
    151 -   **offsetX**: starting index for `x`.
    152 -   **offsetY**: starting index for `y`.
    153 
    154 While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offsetX` and `offsetY` parameters support indexing semantics based on starting indices. For example, to index every other value in `x` starting from the second value and to index the last `N` elements in `y`,
    155 
    156 ```javascript
    157 function accessor( v ) {
    158     return v;
    159 }
    160 
    161 var x = [ 0.0, -0.5, 1.0, -0.25, 0.75, -0.68 ];
    162 var y = [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ];
    163 
    164 atanhBy.ndarray( 3, x, 2, 1, y, -1, y.length-1, accessor );
    165 // y => [ 0.0, 0.0, 0.0, ~-0.829, ~-0.255, ~-0.549 ]
    166 ```
    167 
    168 </section>
    169 
    170 <!-- /.usage -->
    171 
    172 <section class="notes">
    173 
    174 ## Notes
    175 
    176 -   If a provided callback function does not return any value (or equivalently, explicitly returns `undefined`), the value is **ignored**.
    177 
    178     ```javascript
    179     function accessor() {
    180         // No-op...
    181     }
    182 
    183     var x = [ 0.0, -0.5, 1.0, -0.25, 0.75 ];
    184     var y = [ 0.0, 0.0, 0.0, 0.0, 0.0 ];
    185 
    186     atanhBy( x.length, x, 1, y, 1, accessor );
    187     // y => [ 0.0, 0.0, 0.0, 0.0, 0.0 ]
    188     ```
    189 
    190 </section>
    191 
    192 <!-- /.notes -->
    193 
    194 <section class="examples">
    195 
    196 ## Examples
    197 
    198 <!-- eslint no-undef: "error" -->
    199 
    200 ```javascript
    201 var uniform = require( '@stdlib/random/base/uniform' );
    202 var filledarray = require( '@stdlib/array/filled' );
    203 var atanhBy = require( '@stdlib/math/strided/special/atanh-by' );
    204 
    205 function accessor( v, i ) {
    206     if ( (i%3) === 0 ) {
    207         // Simulate a "missing" value...
    208         return;
    209     }
    210     return v;
    211 }
    212 
    213 var x = filledarray( 0.0, 10, 'generic' );
    214 var y = filledarray( null, 10, 'generic' );
    215 
    216 var i;
    217 for ( i = 0; i < x.length; i++ ) {
    218     x[ i ] = uniform( -1.0, 1.0 );
    219 }
    220 console.log( x );
    221 console.log( y );
    222 
    223 atanhBy.ndarray( x.length, x, 1, 0, y, -1, y.length-1, accessor );
    224 console.log( y );
    225 ```
    226 
    227 </section>
    228 
    229 <!-- /.examples -->
    230 
    231 <section class="links">
    232 
    233 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
    234 
    235 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
    236 
    237 [@stdlib/math/base/special/atanh]: https://www.npmjs.com/package/@stdlib/math/tree/main/base/special/atanh
    238 
    239 </section>
    240 
    241 <!-- /.links -->