time-to-botec

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

README.md (4200B)

      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 # Flatten Array
     22 
     23 > Flatten an array.
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 ```javascript
     30 var flattenArray = require( '@stdlib/utils/flatten-array' );
     31 ```
     32 
     33 #### flattenArray( arr\[, options] )
     34 
     35 Flattens an `array`.
     36 
     37 ```javascript
     38 var arr = [ 1, [2, [3, [4, [ 5 ], 6], 7], 8], 9 ];
     39 
     40 var out = flattenArray( arr );
     41 // returns [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
     42 ```
     43 
     44 The function accepts the following `options`:
     45 
     46 -   **depth**: maximum depth to flatten.
     47 -   **copy**: `boolean` indicating whether to deep [copy][@stdlib/utils/copy] `array` elements. Default: `false`.
     48 
     49 To flatten to a specified depth, set the `depth` option.
     50 
     51 ```javascript
     52 var arr = [ 1, [2, [3, [4, [ 5 ], 6], 7], 8], 9 ];
     53 
     54 var out = flattenArray( arr, {
     55     'depth': 2
     56 });
     57 // returns [ 1, 2, 3, [4, [5], 6], 7, 8, 9 ]
     58 
     59 var bool = ( arr[1][1][1] === out[3] );
     60 // returns true
     61 ```
     62 
     63 To deep [copy][@stdlib/utils/copy] `array` elements, set the `copy` option to `true`.
     64 
     65 ```javascript
     66 var arr = [ 1, [2, [3, [4, [ 5 ], 6], 7], 8], 9 ];
     67 
     68 var out = flattenArray( arr, {
     69     'depth': 2,
     70     'copy': true
     71 });
     72 // returns [ 1, 2, 3, [4, [5], 6], 7, 8, 9 ]
     73 
     74 var bool = ( arr[1][1][1] === out[3] );
     75 // returns false
     76 ```
     77 
     78 #### flattenArray.factory( dims\[, options] )
     79 
     80 Returns a `function` optimized for flattening `arrays` having specified dimensions.
     81 
     82 ```javascript
     83 var flatten = flattenArray.factory( [ 3, 3 ] );
     84 
     85 var arr = [
     86     [ 1, 2, 3 ],
     87     [ 4, 5, 6 ],
     88     [ 7, 8, 9 ]
     89 ];
     90 
     91 var out = flatten( arr );
     92 // returns [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
     93 
     94 arr = [
     95     [ 11, 12, 13 ],
     96     [ 14, 15, 16 ],
     97     [ 17, 18, 19 ]
     98 ];
     99 
    100 out = flatten( arr );
    101 // returns [ 11, 12, 13, 14, 15, 16, 17, 18, 19 ]
    102 ```
    103 
    104 The function accepts the following `options`:
    105 
    106 -   **copy**: `boolean` indicating whether to deep [copy][@stdlib/utils/copy] `array` elements. Default: `false`.
    107 
    108 To deep [copy][@stdlib/utils/copy] `array` elements, set the `copy` option to `true`.
    109 
    110 <!-- eslint-disable object-curly-newline -->
    111 
    112 ```javascript
    113 var flatten = flattenArray.factory( [ 3, 3 ], {
    114     'copy': true
    115 });
    116 
    117 var arr = [
    118     [ 1, 2, 3 ],
    119     [ 4, { 'x': 5 }, 6 ],
    120     [ 7, 8, 9 ]
    121 ];
    122 
    123 var out = flatten( arr );
    124 // returns [ 1, 2, 3, 4, {'x':5}, 6, 7, 8, 9 ]
    125 
    126 var bool = ( arr[1][1] === out[4] );
    127 // returns false
    128 ```
    129 
    130 </section>
    131 
    132 <!-- /.usage -->
    133 
    134 <section class="notes">
    135 
    136 ## Notes
    137 
    138 -   A flatten `function` returned by the factory method does **not** validate that input `arrays` actually have the specified dimensions.
    139 
    140 </section>
    141 
    142 <!-- /.notes -->
    143 
    144 <section class="examples">
    145 
    146 ## Examples
    147 
    148 <!-- eslint-disable array-bracket-spacing -->
    149 
    150 <!-- eslint no-undef: "error" -->
    151 
    152 ```javascript
    153 var flattenArray = require( '@stdlib/utils/flatten-array' );
    154 
    155 var xStride;
    156 var yStride;
    157 var zStride;
    158 var bool;
    159 var tmp1;
    160 var tmp2;
    161 var arr;
    162 var val;
    163 var out;
    164 var N;
    165 var M;
    166 var L;
    167 var i;
    168 var j;
    169 var k;
    170 
    171 N = 1000;
    172 M = 100;
    173 L = 10;
    174 
    175 // Create an NxMxL (3D) array...
    176 arr = new Array( N );
    177 for ( i = 0; i < N; i++ ) {
    178     tmp1 = new Array( M );
    179     for ( j = 0; j < M; j++ ) {
    180         tmp2 = new Array( L );
    181         for ( k = 0; k < L; k++ ) {
    182             tmp2[ k ] = (M*L*i) + (j*L) + k + 1;
    183         }
    184         tmp1[ j ] = tmp2;
    185     }
    186     arr[ i ] = tmp1;
    187 }
    188 // Create a flattened (strided) array:
    189 out = flattenArray( arr );
    190 
    191 // To access the arr[4][20][2] element...
    192 xStride = M * L;
    193 yStride = L;
    194 zStride = 1;
    195 val = out[ (4*xStride) + (20*yStride) + (2*zStride) ];
    196 // returns 4203
    197 
    198 bool = ( arr[4][20][2] === val );
    199 // returns true
    200 ```
    201 
    202 </section>
    203 
    204 <!-- /.examples -->
    205 
    206 <section class="links">
    207 
    208 [@stdlib/utils/copy]: https://www.npmjs.com/package/@stdlib/utils/tree/main/copy
    209 
    210 </section>
    211 
    212 <!-- /.links -->