npm-lodash

1
# Array Processing
2

3
Comprehensive array manipulation functions for chunking, flattening, deduplication, set operations, filtering, and transformations. Lodash provides 63 specialized array functions for efficient array processing.
4

5
## Capabilities
6

7
### Array Chunking
8

9
Creates arrays of elements split into groups of specified sizes.
10

11
```javascript { .api }
12
/**
13
 * Creates an array of elements split into groups the length of `size`.
14
 * If `array` can't be split evenly, the final chunk will be the remaining elements.
15
 * @param {Array} array - The array to process
16
 * @param {number} [size=0] - The length of each chunk
17
 * @returns {Array} Returns the new array containing chunks
18
 */
19
function chunk(array, size);
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
const _ = require('lodash');
26

27
_.chunk(['a', 'b', 'c', 'd'], 2);
28
// => [['a', 'b'], ['c', 'd']]
29

30
_.chunk(['a', 'b', 'c', 'd'], 3);
31
// => [['a', 'b', 'c'], ['d']]
32

33
_.chunk([1, 2, 3, 4, 5], 2);
34
// => [[1, 2], [3, 4], [5]]
35
```
36

37
### Array Compacting
38

39
Removes falsy values from arrays.
40

41
```javascript { .api }
42
/**
43
 * Creates an array with all falsey values removed. The values `false`, `null`,
44
 * `0`, `""`, `undefined`, and `NaN` are falsey.
45
 * @param {Array} array - The array to compact
46
 * @returns {Array} Returns the new array of filtered values
47
 */
48
function compact(array);
49
```
50

51
**Usage Examples:**
52

53
```javascript
54
_.compact([0, 1, false, 2, '', 3]);
55
// => [1, 2, 3]
56

57
_.compact([null, undefined, 'hello', 0, false, 'world']);
58
// => ['hello', 'world']
59
```
60

61
### Array Differences
62

63
Creates arrays of unique values not included in other provided arrays.
64

65
```javascript { .api }
66
/**
67
 * Creates an array of unique `array` values not included in the other provided arrays.
68
 * @param {Array} array - The array to inspect
69
 * @param {...Array} [values] - The values to exclude
70
 * @returns {Array} Returns the new array of filtered values
71
 */
72
function difference(array, ...values);
73

74
/**
75
 * Like `difference` except that it accepts `iteratee` to compute criteria.
76
 * @param {Array} array - The array to inspect
77
 * @param {...Array} [values] - The values to exclude
78
 * @param {Function} iteratee - The iteratee invoked per element
79
 * @returns {Array} Returns the new array of filtered values
80
 */
81
function differenceBy(array, ...values, iteratee);
82

83
/**
84
 * Like `difference` except that it accepts `comparator` for element comparisons.
85
 * @param {Array} array - The array to inspect
86
 * @param {...Array} [values] - The values to exclude
87
 * @param {Function} comparator - The comparator invoked per element
88
 * @returns {Array} Returns the new array of filtered values
89
 */
90
function differenceWith(array, ...values, comparator);
91
```
92

93
**Usage Examples:**
94

95
```javascript
96
_.difference([3, 2, 1], [4, 2]);
97
// => [3, 1]
98

99
_.differenceBy([3.1, 2.2, 1.3], [4.4, 2.5], Math.floor);
100
// => [3.1, 1.3]
101

102
_.differenceWith([{ x: 1 }, { x: 2 }], [{ x: 1 }], _.isEqual);
103
// => [{ x: 2 }]
104
```
105

106
### Array Flattening
107

108
Flattens arrays to specified depth levels.
109

110
```javascript { .api }
111
/**
112
 * Flattens `array` a single level.
113
 * @param {Array} array - The array to flatten
114
 * @returns {Array} Returns the new flattened array
115
 */
116
function flatten(array);
117

118
/**
119
 * Recursively flattens `array`.
120
 * @param {Array} array - The array to flatten
121
 * @returns {Array} Returns the new flattened array
122
 */
123
function flattenDeep(array);
124

125
/**
126
 * Recursively flatten `array` up to `depth` times.
127
 * @param {Array} array - The array to flatten
128
 * @param {number} [depth=1] - The maximum recursion depth
129
 * @returns {Array} Returns the new flattened array
130
 */
131
function flattenDepth(array, depth);
132
```
133

134
**Usage Examples:**
135

136
```javascript
137
_.flatten([1, [2, 3, [4]]]);
138
// => [1, 2, 3, [4]]
139

140
_.flattenDeep([1, [2, 3, [4, [5]]]]);
141
// => [1, 2, 3, 4, 5]
142

143
_.flattenDepth([1, [2, [3, [4]], 5]], 2);
144
// => [1, 2, 3, [4], 5]
145
```
146

147
### Array Deduplication
148

149
Creates duplicate-free versions of arrays.
150

151
```javascript { .api }
152
/**
153
 * Creates a duplicate-free version of an array.
154
 * @param {Array} array - The array to inspect
155
 * @returns {Array} Returns the new duplicate free array
156
 */
157
function uniq(array);
158

159
/**
160
 * Like `uniq` except that it accepts `iteratee` to compute uniqueness criteria.
161
 * @param {Array} array - The array to inspect
162
 * @param {Function} iteratee - The iteratee invoked per element
163
 * @returns {Array} Returns the new duplicate free array
164
 */
165
function uniqBy(array, iteratee);
166

167
/**
168
 * Like `uniq` except that it accepts `comparator` for element comparisons.
169
 * @param {Array} array - The array to inspect
170
 * @param {Function} comparator - The comparator invoked per element
171
 * @returns {Array} Returns the new duplicate free array
172
 */
173
function uniqWith(array, comparator);
174
```
175

176
**Usage Examples:**
177

178
```javascript
179
_.uniq([2, 1, 2]);
180
// => [2, 1]
181

182
_.uniqBy([2.1, 1.2, 2.3], Math.floor);
183
// => [2.1, 1.2]
184

185
_.uniqWith([{ x: 1 }, { x: 2 }, { x: 1 }], _.isEqual);
186
// => [{ x: 1 }, { x: 2 }]
187
```
188

189
### Array Access and Slicing
190

191
Functions for accessing and extracting portions of arrays.
192

193
```javascript { .api }
194
/**
195
 * Gets the first element of `array`.
196
 * @param {Array} array - The array to query
197
 * @returns {*} Returns the first element of `array`
198
 */
199
function head(array);
200

201
/**
202
 * Gets the last element of `array`.
203
 * @param {Array} array - The array to query
204
 * @returns {*} Returns the last element of `array`
205
 */
206
function last(array);
207

208
/**
209
 * Creates a slice of `array` with `n` elements taken from the beginning.
210
 * @param {Array} array - The array to query
211
 * @param {number} [n=1] - The number of elements to take
212
 * @returns {Array} Returns the slice of `array`
213
 */
214
function take(array, n);
215

216
/**
217
 * Creates a slice of `array` with `n` elements dropped from the beginning.
218
 * @param {Array} array - The array to query
219
 * @param {number} [n=1] - The number of elements to drop
220
 * @returns {Array} Returns the slice of `array`
221
 */
222
function drop(array, n);
223
```
224

225
**Usage Examples:**
226

227
```javascript
228
_.head([1, 2, 3]);
229
// => 1
230

231
_.last([1, 2, 3]);
232
// => 3
233

234
_.take([1, 2, 3, 4, 5], 3);
235
// => [1, 2, 3]
236

237
_.drop([1, 2, 3, 4, 5], 2);
238
// => [3, 4, 5]
239
```
240

241
### Set Operations
242

243
Array functions for intersection, union, and symmetric difference operations.
244

245
```javascript { .api }
246
/**
247
 * Creates an array of unique values that are included in all given arrays.
248
 * @param {...Array} [arrays] - The arrays to inspect
249
 * @returns {Array} Returns the new array of intersecting values
250
 */
251
function intersection(...arrays);
252

253
/**
254
 * Creates an array of unique values from all given arrays.
255
 * @param {...Array} [arrays] - The arrays to inspect
256
 * @returns {Array} Returns the new array of combined values
257
 */
258
function union(...arrays);
259

260
/**
261
 * Creates an array of unique values that is the symmetric difference of the given arrays.
262
 * @param {...Array} [arrays] - The arrays to inspect
263
 * @returns {Array} Returns the new array of values
264
 */
265
function xor(...arrays);
266
```
267

268
**Usage Examples:**
269

270
```javascript
271
_.intersection([2, 1], [4, 2], [1, 2]);
272
// => [2]
273

274
_.union([2], [1, 2]);
275
// => [2, 1]
276

277
_.xor([2, 1], [4, 2]);
278
// => [1, 4]
279
```
280

281
### Array Searching and Indexing
282

283
Functions for finding elements and their positions in arrays.
284

285
```javascript { .api }
286
/**
287
 * Gets the index at which the first occurrence of `value` is found in `array`.
288
 * @param {Array} array - The array to search
289
 * @param {*} value - The value to search for
290
 * @param {number} [fromIndex=0] - The index to search from
291
 * @returns {number} Returns the index of the matched value, else -1
292
 */
293
function indexOf(array, value, fromIndex);
294

295
/**
296
 * This method is like `indexOf` except that it searches from right to left.
297
 * @param {Array} array - The array to search
298
 * @param {*} value - The value to search for
299
 * @param {number} [fromIndex=array.length-1] - The index to search from
300
 * @returns {number} Returns the index of the matched value, else -1
301
 */
302
function lastIndexOf(array, value, fromIndex);
303

304
/**
305
 * Returns the index of the first element `predicate` returns truthy for.
306
 * @param {Array} array - The array to search
307
 * @param {Function} predicate - The function invoked per iteration
308
 * @param {number} [fromIndex=0] - The index to search from
309
 * @returns {number} Returns the index of the found element, else -1
310
 */
311
function findIndex(array, predicate, fromIndex);
312
```
313

314
**Usage Examples:**
315

316
```javascript
317
_.indexOf([1, 2, 1, 2], 2);
318
// => 1
319

320
_.lastIndexOf([1, 2, 1, 2], 2);
321
// => 3
322

323
_.findIndex([{ user: 'fred' }, { user: 'barney' }], { user: 'barney' });
324
// => 1
325
```
326

327
### Array Zipping and Unzipping
328

329
Functions for combining and separating arrays.
330

331
```javascript { .api }
332
/**
333
 * Creates an array of grouped elements.
334
 * @param {...Array} [arrays] - The arrays to process
335
 * @returns {Array} Returns the new array of grouped elements
336
 */
337
function zip(...arrays);
338

339
/**
340
 * This method is like `zip` except that it accepts an array of grouped elements.
341
 * @param {Array} array - The array of grouped elements to process
342
 * @returns {Array} Returns the new array of regrouped elements
343
 */
344
function unzip(array);
345

346
/**
347
 * Like `zip` except that it accepts `iteratee` to specify how grouped values should be combined.
348
 * @param {...Array} [arrays] - The arrays to process
349
 * @param {Function} iteratee - The function to combine grouped values
350
 * @returns {Array} Returns the new array of combined values
351
 */
352
function zipWith(...arrays, iteratee);
353
```
354

355
**Usage Examples:**
356

357
```javascript
358
_.zip(['fred', 'barney'], [30, 40], [true, false]);
359
// => [['fred', 30, true], ['barney', 40, false]]
360

361
_.unzip([['fred', 30, true], ['barney', 40, false]]);
362
// => [['fred', 'barney'], [30, 40], [true, false]]
363

364
_.zipWith([1, 2], [10, 20], [100, 200], (a, b, c) => a + b + c);
365
// => [111, 222]
366
```
367

368
## Complete Array Function List
369

370
Lodash provides these 63 array functions:
371

372
**Core Functions:** `chunk`, `compact`, `concat`, `difference`, `differenceBy`, `differenceWith`, `drop`, `dropRight`, `dropRightWhile`, `dropWhile`, `fill`, `findIndex`, `findLastIndex`, `flatten`, `flattenDeep`, `flattenDepth`, `fromPairs`, `head`, `indexOf`, `initial`, `intersection`, `intersectionBy`, `intersectionWith`, `join`, `last`, `lastIndexOf`, `nth`, `pull`, `pullAll`, `pullAllBy`, `pullAllWith`, `pullAt`, `remove`, `reverse`, `slice`, `sortedIndex`, `sortedIndexBy`, `sortedIndexOf`, `sortedLastIndex`, `sortedLastIndexBy`, `sortedLastIndexOf`, `sortedUniq`, `sortedUniqBy`, `tail`, `take`, `takeRight`, `takeRightWhile`, `takeWhile`, `union`, `unionBy`, `unionWith`, `uniq`, `uniqBy`, `uniqWith`, `unzip`, `unzipWith`, `without`, `xor`, `xorBy`, `xorWith`, `zip`, `zipObject`, `zipObjectDeep`, `zipWith`
373

374
**Aliases:** `first` (alias for `head`)
375

376
Each function includes comprehensive parameter validation, optional iteratee support, and optimized performance for large arrays.