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 );