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

Deep Pluck

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

Usage

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

deepPluck( arr, path[, options] )

Extracts a nested property value from each element of an object array based on a key path.

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

var out = deepPluck( arr, 'a.b.c' );
// returns [ 1, 2 ]

A key path may be specified as either a string or as an array.

var arr = [
    { 'a': [ 0, 1, 2 ] },
    { 'a': [ 3, 4, 5 ] }
];

var out = deepPluck( arr, [ 'a', 1 ] );
// returns [ 1, 4 ]

The function accepts the following options:

• copy: boolean indicating whether to return a new data structure. Default: true.
• sep: key path separator. Default: '.'.

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': { 'b': { 'c': 1 } } },
    { 'a': { 'b': { 'c': 2 } } }
];

var out = deepPluck( arr, 'a.b.c', { 'copy': false } );
// returns [ 1, 2 ]

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

The default key path separator is .. To specify an alternative separator, set the sep option.

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

var out = deepPluck( arr, 'a|b|c', { 'sep': '|' } );
// returns [ 1, 2 ]

• If a key path does not exist, the function sets the plucked value as undefined.

  var arr = [
      { 'a': { 'b': { 'c': 1 } } },
      null,
      void 0,
      { 'a': { 'b': { 'c': 2 } } }
  ];
  
  var out = deepPluck( arr, 'a.b.c' );
  // returns [ 1, undefined, undefined, 2 ]
  

• Extracted values are not cloned.

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

  To prevent subsequent unintended mutation, use copy.

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

Examples

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

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

arr = new Array( 100 );
for ( i = 0; i < arr.length; i++ ) {
    tmp = {
        'a': {
            'b': {
                'c': {
                    'd': null
                }
            }
        }
    };
    tmp.a.b.c.d = round( randu()*100.0 );
    arr[ i ] = tmp;
}

// Pluck the deeply nested values:
out = deepPluck( arr, 'a.b.c.d' );
console.log( out );