0
# Array Functions
1

2
Comprehensive array utilities for creation, modification, and analysis including chunking, flattening, set operations, and element manipulation.
3

4
## Capabilities
5

6
### Array Creation and Splitting
7

8
Functions for creating arrays from other arrays or splitting arrays into smaller parts.
9

10
```javascript { .api }
11
/**
12
 * Creates an array of elements split into groups the length of size
13
 * @param {Array} array - The array to process
14
 * @param {number} size - The length of each chunk
15
 * @returns {Array} Returns the new array of chunks
16
 */
17
function chunk(array, size);
18

19
/**
20
 * Creates an array with all falsy values removed
21
 * @param {Array} array - The array to compact
22
 * @returns {Array} Returns the new array of filtered values
23
 */
24
function compact(array);
25

26
/**
27
 * Creates a new array concatenating array with any additional arrays and/or values
28
 * @param {Array} array - The array to concatenate
29
 * @param {...*} values - The values to concatenate
30
 * @returns {Array} Returns the new concatenated array
31
 */
32
function concat(array, ...values);
33
```
34

35
### Array Differences and Intersections
36

37
Set operations for comparing arrays and finding differences or common elements.
38

39
```javascript { .api }
40
/**
41
 * Creates an array of values not included in the other given arrays
42
 * @param {Array} array - The array to inspect
43
 * @param {...Array} values - The values to exclude
44
 * @returns {Array} Returns the new array of filtered values
45
 */
46
function difference(array, ...values);
47

48
/**
49
 * Like difference but accepts iteratee for element comparisons
50
 * @param {Array} array - The array to inspect
51
 * @param {...Array} values - The values to exclude
52
 * @param {Function} iteratee - The iteratee invoked per element
53
 * @returns {Array} Returns the new array of filtered values
54
 */
55
function differenceBy(array, ...values, iteratee);
56

57
/**
58
 * Like difference but accepts comparator for element comparisons
59
 * @param {Array} array - The array to inspect
60
 * @param {...Array} values - The values to exclude
61
 * @param {Function} comparator - The comparator invoked per element
62
 * @returns {Array} Returns the new array of filtered values
63
 */
64
function differenceWith(array, ...values, comparator);
65

66
/**
67
 * Creates an array of unique values present in all given arrays
68
 * @param {...Array} arrays - The arrays to inspect
69
 * @returns {Array} Returns the new array of intersecting values
70
 */
71
function intersection(...arrays);
72

73
/**
74
 * Like intersection but accepts iteratee for element comparisons
75
 * @param {...Array} arrays - The arrays to inspect
76
 * @param {Function} iteratee - The iteratee invoked per element
77
 * @returns {Array} Returns the new array of intersecting values
78
 */
79
function intersectionBy(...arrays, iteratee);
80

81
/**
82
 * Like intersection but accepts comparator for element comparisons
83
 * @param {...Array} arrays - The arrays to inspect
84
 * @param {Function} comparator - The comparator invoked per element
85
 * @returns {Array} Returns the new array of intersecting values
86
 */
87
function intersectionWith(...arrays, comparator);
88
```
89

90
### Array Trimming and Dropping
91

92
Functions for removing elements from the beginning or end of arrays.
93

94
```javascript { .api }
95
/**
96
 * Creates a slice of array with n elements dropped from the beginning
97
 * @param {Array} array - The array to query
98
 * @param {number} n - The number of elements to drop
99
 * @returns {Array} Returns the slice of array
100
 */
101
function drop(array, n);
102

103
/**
104
 * Creates a slice of array with n elements dropped from the end
105
 * @param {Array} array - The array to query
106
 * @param {number} n - The number of elements to drop
107
 * @returns {Array} Returns the slice of array
108
 */
109
function dropRight(array, n);
110

111
/**
112
 * Creates a slice of array excluding elements dropped from the beginning
113
 * @param {Array} array - The array to query
114
 * @param {Function} predicate - The function invoked per iteration
115
 * @returns {Array} Returns the slice of array
116
 */
117
function dropWhile(array, predicate);
118

119
/**
120
 * Creates a slice of array excluding elements dropped from the end
121
 * @param {Array} array - The array to query
122
 * @param {Function} predicate - The function invoked per iteration
123
 * @returns {Array} Returns the slice of array
124
 */
125
function dropRightWhile(array, predicate);
126

127
/**
128
 * Gets all but the last element of array
129
 * @param {Array} array - The array to query
130
 * @returns {Array} Returns the slice of array
131
 */
132
function initial(array);
133

134
/**
135
 * Gets all but the first element of array
136
 * @param {Array} array - The array to query
137
 * @returns {Array} Returns the slice of array
138
 */
139
function tail(array);
140
```
141

142
### Array Taking
143

144
Functions for extracting elements from arrays.
145

146
```javascript { .api }
147
/**
148
 * Creates a slice of array with n elements taken from the beginning
149
 * @param {Array} array - The array to query
150
 * @param {number} n - The number of elements to take
151
 * @returns {Array} Returns the slice of array
152
 */
153
function take(array, n);
154

155
/**
156
 * Creates a slice of array with n elements taken from the end
157
 * @param {Array} array - The array to query
158
 * @param {number} n - The number of elements to take
159
 * @returns {Array} Returns the slice of array
160
 */
161
function takeRight(array, n);
162

163
/**
164
 * Creates a slice of array with elements taken from the beginning
165
 * @param {Array} array - The array to query
166
 * @param {Function} predicate - The function invoked per iteration
167
 * @returns {Array} Returns the slice of array
168
 */
169
function takeWhile(array, predicate);
170

171
/**
172
 * Creates a slice of array with elements taken from the end
173
 * @param {Array} array - The array to query
174
 * @param {Function} predicate - The function invoked per iteration
175
 * @returns {Array} Returns the slice of array
176
 */
177
function takeRightWhile(array, predicate);
178
```
179

180
### Array Flattening
181

182
Functions for flattening nested arrays to various depths.
183

184
```javascript { .api }
185
/**
186
 * Flattens array a single level deep
187
 * @param {Array} array - The array to flatten
188
 * @returns {Array} Returns the new flattened array
189
 */
190
function flatten(array);
191

192
/**
193
 * Recursively flattens array
194
 * @param {Array} array - The array to flatten
195
 * @returns {Array} Returns the new flattened array
196
 */
197
function flattenDeep(array);
198

199
/**
200
 * Recursively flattens array up to depth times
201
 * @param {Array} array - The array to flatten
202
 * @param {number} depth - The maximum recursion depth
203
 * @returns {Array} Returns the new flattened array
204
 */
205
function flattenDepth(array, depth);
206
```
207

208
### Element Access and Search
209

210
Functions for accessing and finding elements within arrays.
211

212
```javascript { .api }
213
/**
214
 * Gets the first element of array
215
 * @param {Array} array - The array to query
216
 * @returns {*} Returns the first element of array
217
 */
218
function head(array);
219

220
/**
221
 * Gets the first element of array (alias for head)
222
 * @param {Array} array - The array to query
223
 * @returns {*} Returns the first element of array
224
 */
225
function first(array);
226

227
/**
228
 * Gets the last element of array
229
 * @param {Array} array - The array to query
230
 * @returns {*} Returns the last element of array
231
 */
232
function last(array);
233

234
/**
235
 * Gets the element at index n of array
236
 * @param {Array} array - The array to query
237
 * @param {number} n - The index of the element to return
238
 * @returns {*} Returns the nth element of array
239
 */
240
function nth(array, n);
241

242
/**
243
 * Gets the index at which the first occurrence of value is found in array
244
 * @param {Array} array - The array to inspect
245
 * @param {*} value - The value to search for
246
 * @param {number} fromIndex - The index to search from
247
 * @returns {number} Returns the index of the matched value, else -1
248
 */
249
function indexOf(array, value, fromIndex);
250

251
/**
252
 * Gets the index at which the last occurrence of value is found in array
253
 * @param {Array} array - The array to inspect
254
 * @param {*} value - The value to search for
255
 * @param {number} fromIndex - The index to search from
256
 * @returns {number} Returns the index of the matched value, else -1
257
 */
258
function lastIndexOf(array, value, fromIndex);
259

260
/**
261
 * Returns the index of the first element predicate returns truthy for
262
 * @param {Array} array - The array to inspect
263
 * @param {Function} predicate - The function invoked per iteration
264
 * @param {number} fromIndex - The index to search from
265
 * @returns {number} Returns the index of the found element, else -1
266
 */
267
function findIndex(array, predicate, fromIndex);
268

269
/**
270
 * Like findIndex but iterates over elements from right to left
271
 * @param {Array} array - The array to inspect
272
 * @param {Function} predicate - The function invoked per iteration
273
 * @param {number} fromIndex - The index to search from
274
 * @returns {number} Returns the index of the found element, else -1
275
 */
276
function findLastIndex(array, predicate, fromIndex);
277
```
278

279
### Array Modification
280

281
Functions for modifying arrays by adding, removing, or changing elements.
282

283
```javascript { .api }
284
/**
285
 * Fills elements of array with value from start up to, but not including, end
286
 * @param {Array} array - The array to fill
287
 * @param {*} value - The value to fill array with
288
 * @param {number} start - The start position
289
 * @param {number} end - The end position
290
 * @returns {Array} Returns array
291
 */
292
function fill(array, value, start, end);
293

294
/**
295
 * Removes all given values from array using SameValueZero
296
 * @param {Array} array - The array to modify
297
 * @param {...*} values - The values to remove
298
 * @returns {Array} Returns array
299
 */
300
function pull(array, ...values);
301

302
/**
303
 * Like pull but accepts an array of values to remove
304
 * @param {Array} array - The array to modify
305
 * @param {Array} values - The values to remove
306
 * @returns {Array} Returns array
307
 */
308
function pullAll(array, values);
309

310
/**
311
 * Like pullAll but accepts iteratee for element comparisons
312
 * @param {Array} array - The array to modify
313
 * @param {Array} values - The values to remove
314
 * @param {Function} iteratee - The iteratee invoked per element
315
 * @returns {Array} Returns array
316
 */
317
function pullAllBy(array, values, iteratee);
318

319
/**
320
 * Like pullAll but accepts comparator for element comparisons
321
 * @param {Array} array - The array to modify
322
 * @param {Array} values - The values to remove
323
 * @param {Function} comparator - The comparator invoked per element
324
 * @returns {Array} Returns array
325
 */
326
function pullAllWith(array, values, comparator);
327

328
/**
329
 * Removes elements from array corresponding to indexes and returns them
330
 * @param {Array} array - The array to modify
331
 * @param {...number} indexes - The indexes of elements to remove
332
 * @returns {Array} Returns the new array of removed elements
333
 */
334
function pullAt(array, ...indexes);
335

336
/**
337
 * Removes all elements from array that predicate returns truthy for
338
 * @param {Array} array - The array to modify
339
 * @param {Function} predicate - The function invoked per iteration
340
 * @returns {Array} Returns the array of removed elements
341
 */
342
function remove(array, predicate);
343

344
/**
345
 * Reverses array so that the first element becomes the last
346
 * @param {Array} array - The array to modify
347
 * @returns {Array} Returns array
348
 */
349
function reverse(array);
350
```
351

352
### Array Slicing and Joining
353

354
Functions for creating subarrays and converting arrays to strings.
355

356
```javascript { .api }
357
/**
358
 * Creates a slice of array from start up to, but not including, end
359
 * @param {Array} array - The array to slice
360
 * @param {number} start - The start position
361
 * @param {number} end - The end position
362
 * @returns {Array} Returns the slice of array
363
 */
364
function slice(array, start, end);
365

366
/**
367
 * Converts all elements in array into a string separated by separator
368
 * @param {Array} array - The array to convert
369
 * @param {string} separator - The element separator
370
 * @returns {string} Returns the joined string
371
 */
372
function join(array, separator);
373
```
374

375
### Array Union and Uniqueness
376

377
Functions for combining arrays and removing duplicates.
378

379
```javascript { .api }
380
/**
381
 * Creates an array of unique values, in order, from all given arrays
382
 * @param {...Array} arrays - The arrays to inspect
383
 * @returns {Array} Returns the new array of combined values
384
 */
385
function union(...arrays);
386

387
/**
388
 * Like union but accepts iteratee for element comparisons
389
 * @param {...Array} arrays - The arrays to inspect
390
 * @param {Function} iteratee - The iteratee invoked per element
391
 * @returns {Array} Returns the new array of combined values
392
 */
393
function unionBy(...arrays, iteratee);
394

395
/**
396
 * Like union but accepts comparator for element comparisons
397
 * @param {...Array} arrays - The arrays to inspect
398
 * @param {Function} comparator - The comparator invoked per element
399
 * @returns {Array} Returns the new array of combined values
400
 */
401
function unionWith(...arrays, comparator);
402

403
/**
404
 * Creates a duplicate-free version of an array
405
 * @param {Array} array - The array to inspect
406
 * @returns {Array} Returns the new duplicate free array
407
 */
408
function uniq(array);
409

410
/**
411
 * Like uniq but accepts iteratee for element comparisons
412
 * @param {Array} array - The array to inspect
413
 * @param {Function} iteratee - The iteratee invoked per element
414
 * @returns {Array} Returns the new duplicate free array
415
 */
416
function uniqBy(array, iteratee);
417

418
/**
419
 * Like uniq but accepts comparator for element comparisons
420
 * @param {Array} array - The array to inspect
421
 * @param {Function} comparator - The comparator invoked per element
422
 * @returns {Array} Returns the new duplicate free array
423
 */
424
function uniqWith(array, comparator);
425
```
426

427
### Array Exclusion and Symmetric Difference
428

429
Functions for excluding values and finding symmetric differences.
430

431
```javascript { .api }
432
/**
433
 * Creates an array excluding all given values using SameValueZero
434
 * @param {Array} array - The array to inspect
435
 * @param {...*} values - The values to exclude
436
 * @returns {Array} Returns the new array of filtered values
437
 */
438
function without(array, ...values);
439

440
/**
441
 * Creates an array of unique values that is the symmetric difference
442
 * @param {...Array} arrays - The arrays to inspect
443
 * @returns {Array} Returns the new array of filtered values
444
 */
445
function xor(...arrays);
446

447
/**
448
 * Like xor but accepts iteratee for element comparisons
449
 * @param {...Array} arrays - The arrays to inspect
450
 * @param {Function} iteratee - The iteratee invoked per element
451
 * @returns {Array} Returns the new array of filtered values
452
 */
453
function xorBy(...arrays, iteratee);
454

455
/**
456
 * Like xor but accepts comparator for element comparisons
457
 * @param {...Array} arrays - The arrays to inspect
458
 * @param {Function} comparator - The comparator invoked per element
459
 * @returns {Array} Returns the new array of filtered values
460
 */
461
function xorWith(...arrays, comparator);
462
```
463

464
### Sorted Array Operations
465

466
Specialized functions for working with sorted arrays.
467

468
```javascript { .api }
469
/**
470
 * Uses binary search to determine the lowest index at which value should be inserted
471
 * @param {Array} array - The sorted array to inspect
472
 * @param {*} value - The value to evaluate
473
 * @returns {number} Returns the index at which value should be inserted
474
 */
475
function sortedIndex(array, value);
476

477
/**
478
 * Like sortedIndex but accepts iteratee for value comparison
479
 * @param {Array} array - The sorted array to inspect
480
 * @param {*} value - The value to evaluate
481
 * @param {Function} iteratee - The iteratee invoked per element
482
 * @returns {number} Returns the index at which value should be inserted
483
 */
484
function sortedIndexBy(array, value, iteratee);
485

486
/**
487
 * Like indexOf but for sorted arrays
488
 * @param {Array} array - The array to inspect
489
 * @param {*} value - The value to search for
490
 * @returns {number} Returns the index of the matched value, else -1
491
 */
492
function sortedIndexOf(array, value);
493

494
/**
495
 * Like sortedIndex but returns the highest index at which value should be inserted
496
 * @param {Array} array - The sorted array to inspect
497
 * @param {*} value - The value to evaluate
498
 * @returns {number} Returns the index at which value should be inserted
499
 */
500
function sortedLastIndex(array, value);
501

502
/**
503
 * Like sortedLastIndex but accepts iteratee for value comparison
504
 * @param {Array} array - The sorted array to inspect
505
 * @param {*} value - The value to evaluate
506
 * @param {Function} iteratee - The iteratee invoked per element
507
 * @returns {number} Returns the index at which value should be inserted
508
 */
509
function sortedLastIndexBy(array, value, iteratee);
510

511
/**
512
 * Like lastIndexOf but for sorted arrays
513
 * @param {Array} array - The array to inspect
514
 * @param {*} value - The value to search for
515
 * @returns {number} Returns the index of the matched value, else -1
516
 */
517
function sortedLastIndexOf(array, value);
518

519
/**
520
 * Like uniq but for sorted arrays
521
 * @param {Array} array - The array to inspect
522
 * @returns {Array} Returns the new duplicate free array
523
 */
524
function sortedUniq(array);
525

526
/**
527
 * Like uniqBy but for sorted arrays
528
 * @param {Array} array - The array to inspect
529
 * @param {Function} iteratee - The iteratee invoked per element
530
 * @returns {Array} Returns the new duplicate free array
531
 */
532
function sortedUniqBy(array, iteratee);
533
```
534

535
### Array Zipping and Unzipping
536

537
Functions for combining and separating arrays.
538

539
```javascript { .api }
540
/**
541
 * Creates an array of grouped elements
542
 * @param {...Array} arrays - The arrays to process
543
 * @returns {Array} Returns the new array of grouped elements
544
 */
545
function zip(...arrays);
546

547
/**
548
 * Like zip but accepts an iteratee to specify how grouped values should be combined
549
 * @param {...Array} arrays - The arrays to process
550
 * @param {Function} iteratee - The function to combine grouped values
551
 * @returns {Array} Returns the new array of grouped elements
552
 */
553
function zipWith(...arrays, iteratee);
554

555
/**
556
 * Creates an object composed from arrays of property paths and values
557
 * @param {Array} props - The property paths
558
 * @param {Array} values - The property values
559
 * @returns {Object} Returns the new object
560
 */
561
function zipObject(props, values);
562

563
/**
564
 * Like zipObject but supports property paths
565
 * @param {Array} paths - The property paths
566
 * @param {Array} values - The property values
567
 * @returns {Object} Returns the new object
568
 */
569
function zipObjectDeep(paths, values);
570

571
/**
572
 * Creates an array of regrouped elements
573
 * @param {Array} array - The array of grouped elements to process
574
 * @returns {Array} Returns the new array of regrouped elements
575
 */
576
function unzip(array);
577

578
/**
579
 * Like unzip but accepts an iteratee to specify how regrouped values should be combined
580
 * @param {Array} array - The array of grouped elements to process
581
 * @param {Function} iteratee - The function to combine regrouped values
582
 * @returns {Array} Returns the new array of regrouped elements
583
 */
584
function unzipWith(array, iteratee);
585
```
586

587
### Array Conversion
588

589
Functions for converting arrays to other data structures.
590

591
```javascript { .api }
592
/**
593
 * Creates an object composed from key-value pairs
594
 * @param {Array} pairs - The key-value pairs
595
 * @returns {Object} Returns the new object
596
 */
597
function fromPairs(pairs);
598
```
599

600
## Usage Examples
601

602
### Basic Array Operations
603

604
```javascript
605
import { chunk, compact, difference, flatten } from "lodash-es";
606

607
// Split array into chunks
608
const numbers = [1, 2, 3, 4, 5, 6, 7, 8];
609
const chunks = chunk(numbers, 3); // [[1, 2, 3], [4, 5, 6], [7, 8]]
610

611
// Remove falsy values
612
const mixed = [0, 1, false, 2, '', 3, null, 4, undefined, 5, NaN];
613
const truthy = compact(mixed); // [1, 2, 3, 4, 5]
614

615
// Find differences between arrays
616
const arr1 = [1, 2, 3, 4, 5];
617
const arr2 = [3, 4, 5, 6, 7];
618
const diff = difference(arr1, arr2); // [1, 2]
619

620
// Flatten nested arrays
621
const nested = [1, [2, [3, [4]], 5]];
622
const flat = flatten(nested); // [1, 2, [3, [4]], 5]
623
const deepFlat = flattenDeep(nested); // [1, 2, 3, 4, 5]
624
```
625

626
### Array Searching and Filtering
627

628
```javascript
629
import { findIndex, pull, without, uniq } from "lodash-es";
630

631
const users = [
632
  { name: "Alice", age: 25 },
633
  { name: "Bob", age: 30 },
634
  { name: "Charlie", age: 25 }
635
];
636

637
// Find index of first match
638
const index = findIndex(users, { age: 25 }); // 0
639

640
// Remove values from array (mutates original)
641
const nums = [1, 2, 3, 4, 5, 2, 3];
642
pull(nums, 2, 3); // nums is now [1, 4, 5]
643

644
// Create new array without values
645
const filtered = without([1, 2, 3, 4, 5], 2, 3); // [1, 4, 5]
646

647
// Remove duplicates
648
const duplicates = [1, 2, 2, 3, 3, 4];
649
const unique = uniq(duplicates); // [1, 2, 3, 4]
650
```