time-to-botec

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

README.md (3814B)

      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 # Pluck
     22 
     23 > Extract a property value from each element of an object array.
     24 
     25 <section class="intro">
     26 
     27 </section>
     28 
     29 <!-- /.intro -->
     30 
     31 <section class="usage">
     32 
     33 ## Usage
     34 
     35 ```javascript
     36 var pluck = require( '@stdlib/utils/pluck' );
     37 ```
     38 
     39 #### pluck( arr, prop\[, options] )
     40 
     41 Extracts a property value from each element of an object `array`.
     42 
     43 <!-- eslint-disable object-curly-newline, object-property-newline -->
     44 
     45 ```javascript
     46 var arr = [
     47     { 'a': 1, 'b': 2 },
     48     { 'a': 0.5, 'b': 3 }
     49 ];
     50 
     51 var out = pluck( arr, 'a' );
     52 // returns [ 1, 0.5 ]
     53 ```
     54 
     55 The function accepts the following `options`:
     56 
     57 -   **copy**: `boolean` indicating whether to return a new data structure. Default: `true`.
     58 
     59 By default, the function returns a new data structure. To mutate the input data structure (e.g., when input values can be discarded or when optimizing memory usage), set the `copy` option to `false`.
     60 
     61 <!-- eslint-disable object-curly-newline, object-property-newline -->
     62 
     63 ```javascript
     64 var arr = [
     65     { 'a': 1, 'b': 2 },
     66     { 'a': 0.5, 'b': 3 }
     67 ];
     68 
     69 var out = pluck( arr, 'a', { 'copy': false } );
     70 // returns [ 1, 0.5 ]
     71 
     72 var bool = ( arr[ 0 ] === out[ 0 ] );
     73 // returns true
     74 ```
     75 
     76 </section>
     77 
     78 <!-- /.usage -->
     79 
     80 <section class="notes">
     81 
     82 ## Notes
     83 
     84 -   The function skips `null` and `undefined` array elements.
     85 
     86     <!-- eslint-disable object-curly-newline, object-property-newline -->
     87 
     88     ```javascript
     89     var arr = [
     90         { 'a': 1, 'b': 2 },
     91         null,
     92         void 0,
     93         { 'a': 0.5, 'b': 3 }
     94     ];
     95 
     96     var out = pluck( arr, 'a' );
     97     // returns [ 1, , , 0.5 ]
     98     ```
     99 
    100 -   Extracted values are **not** cloned.
    101 
    102     <!-- eslint-disable object-curly-newline, object-curly-spacing -->
    103 
    104     ```javascript
    105     var arr = [
    106         { 'a': { 'b': 2 } },
    107         { 'a': { 'b': 3 } }
    108     ];
    109 
    110     var out = pluck( arr, 'a' );
    111     // returns [ { 'b': 2 }, { 'b': 3 } ]
    112 
    113     var bool = ( arr[ 0 ].a === out[ 0 ] );
    114     // returns true
    115     ```
    116 
    117     To prevent unintended mutation, use [copy][@stdlib/utils/copy].
    118 
    119     <!-- eslint-disable object-curly-newline, object-curly-spacing -->
    120 
    121     ```javascript
    122     var copy = require( '@stdlib/utils/copy' );
    123 
    124     var arr = [
    125         { 'a': { 'b': 2 } },
    126         { 'a': { 'b': 3 } }
    127     ];
    128 
    129     var out = pluck( arr, 'a' );
    130     // returns [ { 'b': 2 }, { 'b': 3 } ]
    131 
    132     // Perform a deep copy:
    133     out = copy( out );
    134 
    135     var bool = ( arr[ 0 ].a === out[ 0 ] );
    136     // returns false
    137     ```
    138 
    139 </section>
    140 
    141 <!-- /.notes -->
    142 
    143 <section class="examples">
    144 
    145 ## Examples
    146 
    147 <!-- eslint no-undef: "error" -->
    148 
    149 ```javascript
    150 var randu = require( '@stdlib/random/base/randu' );
    151 var round = require( '@stdlib/math/base/special/round' );
    152 var pluck = require( '@stdlib/utils/pluck' );
    153 
    154 var arr;
    155 var tmp;
    156 var out;
    157 var i;
    158 var j;
    159 
    160 // Generate a 100x5 2d-array...
    161 arr = new Array( 100 );
    162 for ( i = 0; i < arr.length; i++ ) {
    163     tmp = new Array( 5 );
    164     for ( j = 0; j < tmp.length; j++ ) {
    165         tmp[ j ] = round( randu()*100.0*(j+1.0) );
    166     }
    167     arr[ i ] = tmp;
    168 }
    169 // Pluck the 3rd column:
    170 out = pluck( arr, 2 );
    171 console.log( out );
    172 ```
    173 
    174 </section>
    175 
    176 <!-- /.examples -->
    177 
    178 <section class="links">
    179 
    180 [@stdlib/utils/copy]: https://www.npmjs.com/package/@stdlib/utils/tree/main/copy
    181 
    182 </section>
    183 
    184 <!-- /.links -->