time-to-botec

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

README.md (4580B)

      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 # broadcastArray
     22 
     23 > Broadcast an [ndarray][@stdlib/ndarray/base/ctor] to a specified shape.
     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 broadcastArray = require( '@stdlib/ndarray/base/broadcast-array' );
     41 ```
     42 
     43 #### broadcastArray( arr, shape )
     44 
     45 Broadcasts an [ndarray][@stdlib/ndarray/base/ctor] to a specified `shape`.
     46 
     47 ```javascript
     48 var array = require( '@stdlib/ndarray/array' );
     49 
     50 // Create a 2x2 ndarray:
     51 var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
     52 // returns <ndarray>
     53 
     54 // Broadcast to a 2x2x2 ndarray:
     55 var y = broadcastArray( x, [ 2, 2, 2 ] );
     56 // returns <ndarray>
     57 ```
     58 
     59 </section>
     60 
     61 <!-- /.usage -->
     62 
     63 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
     64 
     65 <section class="notes">
     66 
     67 ## Notes
     68 
     69 -   The function throws an error if a provided [ndarray][@stdlib/ndarray/base/ctor] is [incompatible][@stdlib/ndarray/base/broadcast-shapes] with a provided shape.
     70 -   The returned [ndarray][@stdlib/ndarray/base/ctor] is a view on the input [ndarray][@stdlib/ndarray/base/ctor] data buffer. The view is typically **not** contiguous. As more than one element of a returned view may refer to the same memory location, writing to the view may affect multiple elements. If you need to write to the returned [ndarray][@stdlib/ndarray/base/ctor], copy the [ndarray][@stdlib/ndarray/base/ctor] **before** performing operations which may mutate elements.
     71 -   The returned [ndarray][@stdlib/ndarray/base/ctor] is a "base" [ndarray][@stdlib/ndarray/base/ctor], and, thus, the returned [ndarray][@stdlib/ndarray/base/ctor] does not perform bounds checking or afford any of the guarantees of the non-base [ndarray][@stdlib/ndarray/ctor] constructor. The primary intent of this function is to broadcast an ndarray-like object within internal implementations and to do so with minimal overhead.
     72 -   The function always returns a new [ndarray][@stdlib/ndarray/base/ctor] instance even if the input [ndarray][@stdlib/ndarray/base/ctor] shape and the desired shape are the same.
     73 
     74 </section>
     75 
     76 <!-- /.notes -->
     77 
     78 <!-- Package usage examples. -->
     79 
     80 <section class="examples">
     81 
     82 ## Examples
     83 
     84 <!-- eslint no-undef: "error" -->
     85 
     86 ```javascript
     87 var array = require( '@stdlib/ndarray/array' );
     88 var numel = require( '@stdlib/ndarray/base/numel' );
     89 var ind2sub = require( '@stdlib/ndarray/ind2sub' );
     90 var broadcastArray = require( '@stdlib/ndarray/base/broadcast-array' );
     91 
     92 // Create a 2x2 array:
     93 var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
     94 // returns <ndarray>
     95 
     96 // Broadcast the array to 3x2x2:
     97 var y = broadcastArray( x, [ 3, 2, 2 ] );
     98 // returns <ndarray>
     99 
    100 // Retrieve the shape:
    101 var sh = y.shape;
    102 // returns [ 3, 2, 2 ]
    103 
    104 // Retrieve the number of elements:
    105 var N = numel( sh );
    106 
    107 // Loop through the array elements...
    108 var sub;
    109 var v;
    110 var i;
    111 for ( i = 0; i < N; i++ ) {
    112     v = y.iget( i );
    113     sub = ind2sub( sh, i );
    114     console.log( 'Y[%s] = %d', sub.join( ', ' ), v );
    115 }
    116 ```
    117 
    118 </section>
    119 
    120 <!-- /.examples -->
    121 
    122 <!-- 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. -->
    123 
    124 <section class="references">
    125 
    126 </section>
    127 
    128 <!-- /.references -->
    129 
    130 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
    131 
    132 <section class="links">
    133 
    134 [@stdlib/ndarray/ctor]: https://www.npmjs.com/package/@stdlib/ndarray/tree/main/ctor
    135 
    136 [@stdlib/ndarray/base/ctor]: https://www.npmjs.com/package/@stdlib/ndarray/tree/main/base/ctor
    137 
    138 [@stdlib/ndarray/base/broadcast-shapes]: https://www.npmjs.com/package/@stdlib/ndarray/tree/main/base/broadcast-shapes
    139 
    140 </section>
    141 
    142 <!-- /.links -->