Name Picker Malfunction
Introducing npm Teams! Private packages + team management tools.Learn more »

utils-pluck

1.0.3 • Public • Published

Pluck

NPM version Build Status Coverage Status Dependencies

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

Installation

$ npm install utils-pluck

Usage

var pluck = require( 'utils-pluck' );

pluck( arr, prop[, opts] )

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,
        undefined,
        {'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 utils-copy.

    var copy = require( '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 round = require( 'math-round' );
var pluck = require( 'utils-pluck' );
 
var arr = new Array( 100 );
var tmp;
var i;
var j;
 
// Generate a 100x5 2d-array...
for ( i = 0; i < arr.length; i++ ) {
    tmp = new Array( 5 );
    for ( j = 0; j < tmp.length; j++ ) {
        tmp[ j ] = round( Math.random()*100*(j+1) );
    }
    arr[ i ] = tmp;
}
 
// Pluck the 3rd column:
var out = pluck( arr, 2 );
 
console.log( out );

To run the example code from the top-level application directory,

$ node ./examples/index.js

Tests

Unit

This repository uses tape for unit tests. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

Browser Support

This repository uses Testling for browser testing. To run the tests in a (headless) local web browser, execute the following command in the top-level application directory:

$ make test-browsers

To view the tests in a local web browser,

$ make view-browser-tests

License

MIT license.

Copyright

Copyright © 2016. Athan Reines.

Install

npm i utils-pluck

DownloadsWeekly Downloads

0

Version

1.0.3

License

MIT

Last publish

Collaborators

  • avatar