time-to-botec/js/node_modules/@stdlib/utils/pluck/README.md

Pluck

Extract a property value from each element of an object array.

Usage

var pluck = require( '@stdlib/utils/pluck' );

pluck( arr, prop[, options] )

Extracts a property value from each element of an object array.

var arr = [
    { 'a': 1, 'b': 2 },
    { 'a': 0.5, 'b': 3 }
];

var out = pluck( arr, 'a' );
// returns [ 1, 0.5 ]

The function accepts the following options:

• copy: boolean indicating whether to return a new data structure. Default: true.

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.

var arr = [
    { 'a': 1, 'b': 2 },
    { 'a': 0.5, 'b': 3 }
];

var out = pluck( arr, 'a', { 'copy': false } );
// returns [ 1, 0.5 ]

var bool = ( arr[ 0 ] === out[ 0 ] );
// returns true

Notes

• The function skips null and undefined array elements.

  var arr = [
      { 'a': 1, 'b': 2 },
      null,
      void 0,
      { 'a': 0.5, 'b': 3 }
  ];
  
  var out = pluck( arr, 'a' );
  // returns [ 1, , , 0.5 ]
  

• Extracted values are not cloned.

  var arr = [
      { 'a': { 'b': 2 } },
      { 'a': { 'b': 3 } }
  ];
  
  var out = pluck( arr, 'a' );
  // returns [ { 'b': 2 }, { 'b': 3 } ]
  
  var bool = ( arr[ 0 ].a === out[ 0 ] );
  // returns true
  

  To prevent unintended mutation, use copy.

  var copy = require( '@stdlib/utils/copy' );
  
  var arr = [
      { 'a': { 'b': 2 } },
      { 'a': { 'b': 3 } }
  ];
  
  var out = pluck( arr, 'a' );
  // returns [ { 'b': 2 }, { 'b': 3 } ]
  
  // Perform a deep copy:
  out = copy( out );
  
  var bool = ( arr[ 0 ].a === out[ 0 ] );
  // returns false
  

Examples

var randu = require( '@stdlib/random/base/randu' );
var round = require( '@stdlib/math/base/special/round' );
var pluck = require( '@stdlib/utils/pluck' );

var arr;
var tmp;
var out;
var i;
var j;

// Generate a 100x5 2d-array...
arr = new Array( 100 );
for ( i = 0; i < arr.length; i++ ) {
    tmp = new Array( 5 );
    for ( j = 0; j < tmp.length; j++ ) {
        tmp[ j ] = round( randu()*100.0*(j+1.0) );
    }
    arr[ i ] = tmp;
}
// Pluck the 3rd column:
out = pluck( arr, 2 );
console.log( out );