# Deep Pluck
> Extract a nested property value from each element of an object array.
## Usage
```javascript
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`.
```javascript
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`.
```javascript
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][@stdlib/utils/deep-get]. 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`.
```javascript
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.
```javascript
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`.
```javascript
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.
```javascript
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][@stdlib/utils/copy].
```javascript
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
```javascript
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 );
```
[@stdlib/utils/deep-get]: https://www.npmjs.com/package/@stdlib/utils/tree/main/deep-get
[@stdlib/utils/copy]: https://www.npmjs.com/package/@stdlib/utils/tree/main/copy