0
# Arrays Module
1

2
The Arrays module provides 75 functions for manipulating arrays and sequences. These functions cover chunking, filtering, set operations, transformations, and various array utilities.
3

4
## Core Array Functions
5

6
### chunk
7

8
```python { .api }
9
def chunk(array: Sequence[T], size: int = 1) -> List[Sequence[T]]
10
```
11

12
Creates a list of elements split into groups the length of `size`. If `array` can't be split evenly, the final chunk will be the remaining elements.
13

14
**Parameters:**
15
- `array` (`Sequence[T]`): List to chunk.
16
- `size` (`int`): Chunk size. Defaults to `1`.
17

18
**Returns:**
19
- `List[Sequence[T]]`: New list containing chunks of `array`.
20

21
**Example:**
22
```python { .api }
23
from pydash import chunk
24

25
chunk([1, 2, 3, 4, 5], 2)
26
# [[1, 2], [3, 4], [5]]
27

28
chunk([1, 2, 3, 4, 5, 6], 3)
29
# [[1, 2, 3], [4, 5, 6]]
30
```
31

32
### compact
33

34
```python { .api }
35
def compact(array: Iterable[Union[T, None]]) -> List[T]
36
```
37

38
Creates a list with all falsey values of array removed.
39

40
**Parameters:**
41
- `array` (`Iterable[Union[T, None]]`): List to compact.
42

43
**Returns:**
44
- `List[T]`: Compacted list.
45

46
**Example:**
47
```python { .api }
48
from pydash import compact
49

50
compact(["", 1, 0, True, False, None])
51
# [1, True]
52

53
compact([0, 1, False, 2, '', 3, None])
54
# [1, 2, 3]
55
```
56

57
### concat
58

59
```python { .api }
60
def concat(*arrays: Iterable[T]) -> List[T]
61
```
62

63
Concatenates zero or more lists into one.
64

65
**Parameters:**
66
- `arrays` (`*Iterable[T]`): Lists to concatenate.
67

68
**Returns:**
69
- `List[T]`: Concatenated list.
70

71
**Example:**
72
```python { .api }
73
from pydash import concat
74

75
concat([1, 2], [3, 4], [[5], [6]])
76
# [1, 2, 3, 4, [5], [6]]
77
```
78

79
### difference
80

81
```python { .api }
82
def difference(array: Iterable[T], *others: Iterable[T]) -> List[T]
83
```
84

85
Creates a list of list elements not present in others.
86

87
**Parameters:**
88
- `array` (`Iterable[T]`): List to process.
89
- `others` (`*Iterable[T]`): Lists to check.
90

91
**Returns:**
92
- `List[T]`: Difference between `others`.
93

94
**Example:**
95
```python { .api }
96
from pydash import difference
97

98
difference([1, 2, 3], [1], [2])
99
# [3]
100

101
difference([1, 2, 3, 4], [2, 3])
102
# [1, 4]
103
```
104

105
### difference_by
106

107
```python { .api }
108
def difference_by(array: Iterable[T], *others, iteratee=None) -> List[T]
109
```
110

111
Like `difference` except that it accepts an iteratee which is invoked for each element of each array to generate the criterion by which they're compared.
112

113
**Parameters:**
114
- `array` (`Iterable[T]`): The array to find the difference of.
115
- `others` (`*Iterable[T]`): Lists to check for difference with `array`.
116
- `iteratee` (`Callable`, optional): Function to transform the elements.
117

118
**Returns:**
119
- `List[T]`: Difference between `others`.
120

121
**Example:**
122
```python { .api }
123
from pydash import difference_by
124

125
difference_by([1.2, 1.5, 1.7, 2.8], [0.9, 3.2], round)
126
# [1.5, 1.7]
127
```
128

129
### difference_with
130

131
```python { .api }
132
def difference_with(array: Iterable[T], *others, comparator=None) -> List[T]
133
```
134

135
Like `difference` except that it accepts a comparator which is invoked to compare the elements of all arrays.
136

137
**Parameters:**
138
- `array` (`Iterable[T]`): The array to find the difference of.
139
- `others` (`*Iterable[T]`): Lists to check for difference with `array`.
140
- `comparator` (`Callable`, optional): Function to compare elements.
141

142
**Returns:**
143
- `List[T]`: Difference between `others`.
144

145
**Example:**
146
```python { .api }
147
from pydash import difference_with
148

149
array = ["apple", "banana", "pear"]
150
others = (["avocado", "pumpkin"], ["peach"])
151
comparator = lambda a, b: a[0] == b[0]
152
difference_with(array, *others, comparator=comparator)
153
# ['banana']
154
```
155

156
## Array Slice Operations
157

158
### drop
159

160
```python { .api }
161
def drop(array: Sequence[T], n: int = 1) -> List[T]
162
```
163

164
Creates a slice with `n` elements dropped from the beginning.
165

166
**Parameters:**
167
- `array` (`Sequence[T]`): Array to process.
168
- `n` (`int`): Number of elements to drop. Defaults to `1`.
169

170
**Returns:**
171
- `List[T]`: Slice of `array` with `n` elements dropped from beginning.
172

173
**Example:**
174
```python { .api }
175
from pydash import drop
176

177
drop([1, 2, 3, 4])
178
# [2, 3, 4]
179

180
drop([1, 2, 3, 4], 2)
181
# [3, 4]
182
```
183

184
### drop_right
185

186
```python { .api }
187
def drop_right(array: Sequence[T], n: int = 1) -> List[T]
188
```
189

190
Creates a slice with `n` elements dropped from the end.
191

192
**Parameters:**
193
- `array` (`Sequence[T]`): Array to process.
194
- `n` (`int`): Number of elements to drop. Defaults to `1`.
195

196
**Returns:**
197
- `List[T]`: Slice of `array` with `n` elements dropped from end.
198

199
**Example:**
200
```python { .api }
201
from pydash import drop_right
202

203
drop_right([1, 2, 3, 4])
204
# [1, 2, 3]
205

206
drop_right([1, 2, 3, 4], 2)
207
# [1, 2]
208
```
209

210
### drop_right_while
211

212
```python { .api }
213
def drop_right_while(array: Sequence[T], predicate=None) -> List[T]
214
```
215

216
Creates a slice of array excluding elements dropped from the end while predicate returns truthy.
217

218
**Parameters:**
219
- `array` (`Sequence[T]`): Array to process.
220
- `predicate` (`Callable`, optional): Function invoked per iteration.
221

222
**Returns:**
223
- `List[T]`: Slice of array.
224

225
**Example:**
226
```python { .api }
227
from pydash import drop_right_while
228

229
drop_right_while([1, 2, 3, 4], lambda x: x > 2)
230
# [1, 2]
231
```
232

233
### drop_while
234

235
```python { .api }
236
def drop_while(array: Sequence[T], predicate=None) -> List[T]
237
```
238

239
Creates a slice of array excluding elements dropped from the beginning while predicate returns truthy.
240

241
**Parameters:**
242
- `array` (`Sequence[T]`): Array to process.
243
- `predicate` (`Callable`, optional): Function invoked per iteration.
244

245
**Returns:**
246
- `List[T]`: Slice of array.
247

248
**Example:**
249
```python { .api }
250
from pydash import drop_while
251

252
drop_while([1, 2, 3, 4], lambda x: x < 3)
253
# [3, 4]
254
```
255

256
### take
257

258
```python { .api }
259
def take(array: Sequence[T], n: int = 1) -> Sequence[T]
260
```
261

262
Creates a slice with `n` elements taken from the beginning.
263

264
**Parameters:**
265
- `array` (`Sequence[T]`): Array to process.
266
- `n` (`int`): Number of elements to take. Defaults to `1`.
267

268
**Returns:**
269
- `Sequence[T]`: Slice of `array` with `n` elements taken from beginning.
270

271
**Example:**
272
```python { .api }
273
from pydash import take
274

275
take([1, 2, 3, 4])
276
# [1]
277

278
take([1, 2, 3, 4], 2)
279
# [1, 2]
280
```
281

282
### take_right
283

284
```python { .api }
285
def take_right(array: Sequence[T], n: int = 1) -> Sequence[T]
286
```
287

288
Creates a slice with `n` elements taken from the end.
289

290
**Parameters:**
291
- `array` (`Sequence[T]`): Array to process.
292
- `n` (`int`): Number of elements to take. Defaults to `1`.
293

294
**Returns:**
295
- `Sequence[T]`: Slice of `array` with `n` elements taken from end.
296

297
**Example:**
298
```python { .api }
299
from pydash import take_right
300

301
take_right([1, 2, 3, 4])
302
# [4]
303

304
take_right([1, 2, 3, 4], 2)
305
# [3, 4]
306
```
307

308
### take_right_while
309

310
```python { .api }
311
def take_right_while(array: Sequence[T], predicate=None) -> Sequence[T]
312
```
313

314
Creates a slice of array with elements taken from the end while predicate returns truthy.
315

316
**Parameters:**
317
- `array` (`Sequence[T]`): Array to process.
318
- `predicate` (`Callable`, optional): Function invoked per iteration.
319

320
**Returns:**
321
- `Sequence[T]`: Slice of array.
322

323
**Example:**
324
```python { .api }
325
from pydash import take_right_while
326

327
take_right_while([1, 2, 3, 4], lambda x: x > 2)
328
# [3, 4]
329
```
330

331
### take_while
332

333
```python { .api }
334
def take_while(array: Sequence[T], predicate=None) -> List[T]
335
```
336

337
Creates a slice of array with elements taken from the beginning while predicate returns truthy.
338

339
**Parameters:**
340
- `array` (`Sequence[T]`): Array to process.
341
- `predicate` (`Callable`, optional): Function invoked per iteration.
342

343
**Returns:**
344
- `List[T]`: Slice of array.
345

346
**Example:**
347
```python { .api }
348
from pydash import take_while
349

350
take_while([1, 2, 3, 4], lambda x: x < 3)
351
# [1, 2]
352
```
353

354
## Array Element Access
355

356
### head
357

358
```python { .api }
359
def head(array: Sequence[T]) -> Union[T, None]
360
```
361

362
Gets the first element of array.
363

364
**Parameters:**
365
- `array` (`Sequence[T]`): Array to get first element of.
366

367
**Returns:**
368
- `Union[T, None]`: First element of array.
369

370
**Example:**
371
```python { .api }
372
from pydash import head
373

374
head([1, 2, 3, 4])
375
# 1
376

377
head([])
378
# None
379
```
380

381
### last
382

383
```python { .api }
384
def last(array: Sequence[T]) -> Union[T, None]
385
```
386

387
Gets the last element of array.
388

389
**Parameters:**
390
- `array` (`Sequence[T]`): Array to get last element of.
391

392
**Returns:**
393
- `Union[T, None]`: Last element of array.
394

395
**Example:**
396
```python { .api }
397
from pydash import last
398

399
last([1, 2, 3, 4])
400
# 4
401

402
last([])
403
# None
404
```
405

406
### nth
407

408
```python { .api }
409
def nth(array: Iterable[T], pos: int = 0) -> Union[T, None]
410
```
411

412
Gets the element at index `pos` of array. If `pos` is negative, the nth element from the end is returned.
413

414
**Parameters:**
415
- `array` (`Iterable[T]`): Array to get element from.
416
- `pos` (`int`): Index of element to get. Defaults to `0`.
417

418
**Returns:**
419
- `Union[T, None]`: Element at index `pos`.
420

421
**Example:**
422
```python { .api }
423
from pydash import nth
424

425
nth([1, 2, 3, 4], 1)
426
# 2
427

428
nth([1, 2, 3, 4], -1)
429
# 4
430
```
431

432
### initial
433

434
```python { .api }
435
def initial(array: Sequence[T]) -> Sequence[T]
436
```
437

438
Gets all but the last element of array.
439

440
**Parameters:**
441
- `array` (`Sequence[T]`): Array to process.
442

443
**Returns:**
444
- `Sequence[T]`: All but the last element of array.
445

446
**Example:**
447
```python { .api }
448
from pydash import initial
449

450
initial([1, 2, 3, 4])
451
# [1, 2, 3]
452
```
453

454
### tail
455

456
```python { .api }
457
def tail(array: Sequence[T]) -> Sequence[T]
458
```
459

460
Gets all but the first element of array.
461

462
**Parameters:**
463
- `array` (`Sequence[T]`): Array to process.
464

465
**Returns:**
466
- `Sequence[T]`: All but the first element of array.
467

468
**Example:**
469
```python { .api }
470
from pydash import tail
471

472
tail([1, 2, 3, 4])
473
# [2, 3, 4]
474
```
475

476
## Array Search Functions
477

478
### find_index
479

480
```python { .api }
481
def find_index(array: Iterable[T], predicate=None) -> int
482
```
483

484
Returns the index of the first element that passes the predicate check, else -1.
485

486
**Parameters:**
487
- `array` (`Iterable[T]`): Array to search.
488
- `predicate` (`Callable`, optional): Function invoked per iteration.
489

490
**Returns:**
491
- `int`: Index of found element, else -1.
492

493
**Example:**
494
```python { .api }
495
from pydash import find_index
496

497
find_index([1, 2, 3, 4], lambda x: x > 2)
498
# 2
499

500
find_index([{'a': 1}, {'a': 2}], {'a': 1})
501
# 0
502
```
503

504
### find_last_index
505

506
```python { .api }
507
def find_last_index(array: Iterable[T], predicate=None) -> int
508
```
509

510
Like `find_index` except that it iterates from right to left.
511

512
**Parameters:**
513
- `array` (`Iterable[T]`): Array to search.
514
- `predicate` (`Callable`, optional): Function invoked per iteration.
515

516
**Returns:**
517
- `int`: Index of found element, else -1.
518

519
**Example:**
520
```python { .api }
521
from pydash import find_last_index
522

523
find_last_index([1, 2, 3, 4], lambda x: x > 2)
524
# 3
525
```
526

527
### index_of
528

529
```python { .api }
530
def index_of(array: Sequence[T], value: T, from_index: int = 0) -> int
531
```
532

533
Gets the index at which the first occurrence of `value` is found in array using SameValueZero for equality comparisons.
534

535
**Parameters:**
536
- `array` (`Sequence[T]`): Array to search.
537
- `value` (`T`): Value to search for.
538
- `from_index` (`int`): Index to search from. Defaults to `0`.
539

540
**Returns:**
541
- `int`: Index of `value` in array, else -1.
542

543
**Example:**
544
```python { .api }
545
from pydash import index_of
546

547
index_of([1, 2, 1, 2], 2)
548
# 1
549

550
index_of([1, 2, 1, 2], 2, 2)
551
# 3
552
```
553

554
### last_index_of
555

556
```python { .api }
557
def last_index_of(array: Sequence[T], value: T, from_index: int = None) -> int
558
```
559

560
Gets the index at which the last occurrence of `value` is found in array using SameValueZero for equality comparisons.
561

562
**Parameters:**
563
- `array` (`Sequence[T]`): Array to search.
564
- `value` (`T`): Value to search for.
565
- `from_index` (`int`, optional): Index to search from.
566

567
**Returns:**
568
- `int`: Index of `value` in array, else -1.
569

570
**Example:**
571
```python { .api }
572
from pydash import last_index_of
573

574
last_index_of([1, 2, 1, 2], 2)
575
# 3
576
```
577

578
## Array Flattening
579

580
### flatten
581

582
```python { .api }
583
def flatten(array: Iterable[Any]) -> List[Any]
584
```
585

586
Flattens array a single level deep.
587

588
**Parameters:**
589
- `array` (`Iterable[Any]`): Array to flatten.
590

591
**Returns:**
592
- `List[Any]`: Flattened array.
593

594
**Example:**
595
```python { .api }
596
from pydash import flatten
597

598
flatten([1, [2, [3, [4]], 5]])
599
# [1, 2, [3, [4]], 5]
600
```
601

602
### flatten_deep
603

604
```python { .api }
605
def flatten_deep(array: Iterable[Any]) -> List[Any]
606
```
607

608
Recursively flattens array.
609

610
**Parameters:**
611
- `array` (`Iterable[Any]`): Array to flatten.
612

613
**Returns:**
614
- `List[Any]`: Flattened array.
615

616
**Example:**
617
```python { .api }
618
from pydash import flatten_deep
619

620
flatten_deep([1, [2, [3, [4]], 5]])
621
# [1, 2, 3, 4, 5]
622
```
623

624
### flatten_depth
625

626
```python { .api }
627
def flatten_depth(array: Iterable[Any], depth: int = 1) -> List[Any]
628
```
629

630
Recursively flatten array up to depth times.
631

632
**Parameters:**
633
- `array` (`Iterable[Any]`): Array to flatten.
634
- `depth` (`int`): Maximum recursion depth. Defaults to `1`.
635

636
**Returns:**
637
- `List[Any]`: Flattened array.
638

639
**Example:**
640
```python { .api }
641
from pydash import flatten_depth
642

643
flatten_depth([1, [2, [3, [4]], 5]], 1)
644
# [1, 2, [3, [4]], 5]
645

646
flatten_depth([1, [2, [3, [4]], 5]], 2)
647
# [1, 2, 3, [4], 5]
648
```
649

650
## Set Operations
651

652
### intersection
653

654
```python { .api }
655
def intersection(array: Sequence[T], *others: Iterable[Any]) -> List[T]
656
```
657

658
Creates a list of unique values that are included in all given arrays using SameValueZero for equality comparisons.
659

660
**Parameters:**
661
- `array` (`Sequence[T]`): Array to inspect.
662
- `others` (`*Iterable[Any]`): Arrays to include values from.
663

664
**Returns:**
665
- `List[T]`: New array of intersecting values.
666

667
**Example:**
668
```python { .api }
669
from pydash import intersection
670

671
intersection([2, 1], [2, 3])
672
# [2]
673

674
intersection([2, 1], [4, 2], [1, 2])
675
# [2]
676
```
677

678
### intersection_by
679

680
```python { .api }
681
def intersection_by(array: Sequence[T], *others, iteratee=None) -> List[T]
682
```
683

684
Like `intersection` except that it accepts an iteratee which is invoked for each element of each array.
685

686
**Parameters:**
687
- `array` (`Sequence[T]`): Array to inspect.
688
- `others` (`*Iterable[Any]`): Arrays to include values from.
689
- `iteratee` (`Callable`, optional): Function to transform elements.
690

691
**Returns:**
692
- `List[T]`: New array of intersecting values.
693

694
**Example:**
695
```python { .api }
696
from pydash import intersection_by
697
import math
698

699
intersection_by([2.1, 1.2], [2.3, 3.4], math.floor)
700
# [2.1]
701
```
702

703
### intersection_with
704

705
```python { .api }
706
def intersection_with(array: Sequence[T], *others, comparator=None) -> List[T]
707
```
708

709
Like `intersection` except that it accepts a comparator which is invoked to compare elements.
710

711
**Parameters:**
712
- `array` (`Sequence[T]`): Array to inspect.
713
- `others` (`*Iterable[Any]`): Arrays to include values from.
714
- `comparator` (`Callable`, optional): Function to compare elements.
715

716
**Returns:**
717
- `List[T]`: New array of intersecting values.
718

719
### union
720

721
```python { .api }
722
def union(array: Sequence[T], *others: Sequence[T]) -> List[Union[T, T2]]
723
```
724

725
Creates a list of unique values from all given arrays using SameValueZero for equality comparisons.
726

727
**Parameters:**
728
- `array` (`Sequence[T]`): Array to inspect.
729
- `others` (`*Sequence[T]`): Arrays to include values from.
730

731
**Returns:**
732
- `List[Union[T, T2]]`: New array of combined values.
733

734
**Example:**
735
```python { .api }
736
from pydash import union
737

738
union([2], [1, 2])
739
# [2, 1]
740
```
741

742
### union_by
743

744
```python { .api }
745
def union_by(array: Sequence[T], *others, iteratee=None) -> List[T]
746
```
747

748
Like `union` except that it accepts an iteratee which is invoked for each element of each array.
749

750
**Parameters:**
751
- `array` (`Sequence[T]`): Array to inspect.
752
- `others` (`*Sequence[T]`): Arrays to include values from.
753
- `iteratee` (`Callable`, optional): Function to transform elements.
754

755
**Returns:**
756
- `List[T]`: New array of combined values.
757

758
### union_with
759

760
```python { .api }
761
def union_with(array: Sequence[T], *others, comparator=None) -> List[T]
762
```
763

764
Like `union` except that it accepts a comparator which is invoked to compare elements.
765

766
**Parameters:**
767
- `array` (`Sequence[T]`): Array to inspect.
768
- `others` (`*Sequence[T]`): Arrays to include values from.
769
- `comparator` (`Callable`, optional): Function to compare elements.
770

771
**Returns:**
772
- `List[T]`: New array of combined values.
773

774
### xor
775

776
```python { .api }
777
def xor(array: Iterable[T], *lists: Iterable[T]) -> List[T]
778
```
779

780
Creates a list of unique values that is the symmetric difference of the given arrays.
781

782
**Parameters:**
783
- `array` (`Iterable[T]`): Array to inspect.
784
- `lists` (`*Iterable[T]`): Arrays to find symmetric difference with.
785

786
**Returns:**
787
- `List[T]`: New array of symmetric differences.
788

789
**Example:**
790
```python { .api }
791
from pydash import xor
792

793
xor([2, 1], [2, 3])
794
# [1, 3]
795
```
796

797
### xor_by
798

799
```python { .api }
800
def xor_by(array: Iterable[T], *lists, iteratee=None) -> List[T]
801
```
802

803
Like `xor` except that it accepts an iteratee which is invoked for each element.
804

805
**Parameters:**
806
- `array` (`Iterable[T]`): Array to inspect.
807
- `lists` (`*Iterable[T]`): Arrays to find symmetric difference with.
808
- `iteratee` (`Callable`, optional): Function to transform elements.
809

810
**Returns:**
811
- `List[T]`: New array of symmetric differences.
812

813
### xor_with
814

815
```python { .api }
816
def xor_with(array: Iterable[T], *lists, comparator=None) -> List[T]
817
```
818

819
Like `xor` except that it accepts a comparator which is invoked to compare elements.
820

821
**Parameters:**
822
- `array` (`Iterable[T]`): Array to inspect.
823
- `lists` (`*Iterable[T]`): Arrays to find symmetric difference with.
824
- `comparator` (`Callable`, optional): Function to compare elements.
825

826
**Returns:**
827
- `List[T]`: New array of symmetric differences.
828

829
## Array Transformation
830

831
### zip_
832

833
```python { .api }
834
def zip_(*arrays: Iterable[Any]) -> List[Tuple[Any, ...]]
835
```
836

837
Creates a list of grouped elements, the first of which contains the first elements of the given arrays.
838

839
**Parameters:**
840
- `arrays` (`*Iterable[Any]`): Arrays to process.
841

842
**Returns:**
843
- `List[Tuple[Any, ...]]`: New array of grouped elements.
844

845
**Example:**
846
```python { .api }
847
from pydash import zip_
848

849
zip_(['a', 'b'], [1, 2], [True, False])
850
# [('a', 1, True), ('b', 2, False)]
851
```
852

853
### zip_object
854

855
```python { .api }
856
def zip_object(keys: Iterable[T], values: List[T2] = None) -> Dict[T, T2]
857
```
858

859
Creates a dictionary composed from arrays of keys and values.
860

861
**Parameters:**
862
- `keys` (`Iterable[T]`): Keys array.
863
- `values` (`List[T2]`, optional): Values array.
864

865
**Returns:**
866
- `Dict[T, T2]`: New dictionary.
867

868
**Example:**
869
```python { .api }
870
from pydash import zip_object
871

872
zip_object(['a', 'b'], [1, 2])
873
# {'a': 1, 'b': 2}
874
```
875

876
### zip_object_deep
877

878
```python { .api }
879
def zip_object_deep(keys: Iterable[Any], values: List[Any] = None) -> Dict[Any, Any]
880
```
881

882
Like `zip_object` except that it supports property paths.
883

884
**Parameters:**
885
- `keys` (`Iterable[Any]`): Keys array (can be property paths).
886
- `values` (`List[Any]`, optional): Values array.
887

888
**Returns:**
889
- `Dict[Any, Any]`: New dictionary.
890

891
**Example:**
892
```python { .api }
893
from pydash import zip_object_deep
894

895
zip_object_deep(['a.b[0].c', 'a.b[1].d'], [1, 2])
896
# {'a': {'b': [{'c': 1}, {'d': 2}]}}
897
```
898

899
### zip_with
900

901
```python { .api }
902
def zip_with(*arrays, iteratee=None) -> List[Any]
903
```
904

905
Like `zip_` except that it accepts an iteratee to specify how grouped values should be combined.
906

907
**Parameters:**
908
- `arrays` (`*Iterable[Any]`): Arrays to process.
909
- `iteratee` (`Callable`, optional): Function to combine grouped values.
910

911
**Returns:**
912
- `List[Any]`: New array of grouped elements.
913

914
**Example:**
915
```python { .api }
916
from pydash import zip_with
917

918
zip_with([1, 2], [10, 20], [100, 200], lambda a, b, c: a + b + c)
919
# [111, 222]
920
```
921

922
### from_pairs
923

924
```python { .api }
925
def from_pairs(pairs: Iterable[Tuple[T, T2]]) -> Dict[T, T2]
926
```
927

928
Creates a dictionary from a list of key-value pairs.
929

930
**Parameters:**
931
- `pairs` (`Iterable[Tuple[T, T2]]`): Key-value pairs.
932

933
**Returns:**
934
- `Dict[T, T2]`: New dictionary.
935

936
**Example:**
937
```python { .api }
938
from pydash import from_pairs
939

940
from_pairs([['a', 1], ['b', 2]])
941
# {'a': 1, 'b': 2}
942
```
943

944
### unzip
945

946
```python { .api }
947
def unzip(array: Iterable[Iterable[Any]]) -> List[Tuple[Any, ...]]
948
```
949

950
The inverse of `zip_`. Creates a list of arrays regrouping the elements to their pre-zip configuration.
951

952
**Parameters:**
953
- `array` (`Iterable[Iterable[Any]]`): Array of grouped elements.
954

955
**Returns:**
956
- `List[Tuple[Any, ...]]`: New array of regrouped elements.
957

958
**Example:**
959
```python { .api }
960
from pydash import unzip
961

962
unzip([('a', 1, True), ('b', 2, False)])
963
# [('a', 'b'), (1, 2), (True, False)]
964
```
965

966
### unzip_with
967

968
```python { .api }
969
def unzip_with(array: Iterable[Iterable[Any]], iteratee=None) -> List[Any]
970
```
971

972
Like `unzip` except that it accepts an iteratee to specify how regrouped values should be combined.
973

974
**Parameters:**
975
- `array` (`Iterable[Iterable[Any]]`): Array of grouped elements.
976
- `iteratee` (`Callable`, optional): Function to combine regrouped values.
977

978
**Returns:**
979
- `List[Any]`: New array of regrouped elements.
980

981
## Array Modification
982

983
### fill
984

985
```python { .api }
986
def fill(array: MutableSequence[Any], value: Any, start: int = 0, end: int = None) -> MutableSequence[Any]
987
```
988

989
Fills elements of array with `value` from `start` up to, but not including, `end`.
990

991
**Parameters:**
992
- `array` (`MutableSequence[Any]`): Array to fill.
993
- `value` (`Any`): Value to fill array with.
994
- `start` (`int`): Start position. Defaults to `0`.
995
- `end` (`int`, optional): End position.
996

997
**Returns:**
998
- `MutableSequence[Any]`: `array`.
999

1000
**Example:**
1001
```python { .api }
1002
from pydash import fill
1003

1004
array = [1, 2, 3]
1005
fill(array, 'a')
1006
# ['a', 'a', 'a']
1007

1008
array = [1, 2, 3]
1009
fill(array, '*', 1, 3)
1010
# [1, '*', '*']
1011
```
1012

1013
### pull
1014

1015
```python { .api }
1016
def pull(array: List[T], *values: T) -> List[T]
1017
```
1018

1019
Removes all provided values from array using SameValueZero for equality comparisons.
1020

1021
**Parameters:**
1022
- `array` (`List[T]`): Array to modify.
1023
- `values` (`*T`): Values to remove.
1024

1025
**Returns:**
1026
- `List[T]`: `array`.
1027

1028
**Example:**
1029
```python { .api }
1030
from pydash import pull
1031

1032
array = ['a', 'b', 'c', 'a', 'b', 'c']
1033
pull(array, 'a', 'c')
1034
# ['b', 'b']
1035
```
1036

1037
### pull_all
1038

1039
```python { .api }
1040
def pull_all(array: List[T], values: Iterable[T]) -> List[T]
1041
```
1042

1043
Like `pull` except that it accepts an array of values to remove.
1044

1045
**Parameters:**
1046
- `array` (`List[T]`): Array to modify.
1047
- `values` (`Iterable[T]`): Values to remove.
1048

1049
**Returns:**
1050
- `List[T]`: `array`.
1051

1052
**Example:**
1053
```python { .api }
1054
from pydash import pull_all
1055

1056
array = ['a', 'b', 'c', 'a', 'b', 'c']
1057
pull_all(array, ['a', 'c'])
1058
# ['b', 'b']
1059
```
1060

1061
### pull_all_by
1062

1063
```python { .api }
1064
def pull_all_by(array: List[T], values: Iterable[T], iteratee=None) -> List[T]
1065
```
1066

1067
Like `pull_all` except that it accepts an iteratee which is invoked for each element of array and values to generate the criterion by which they're compared.
1068

1069
**Parameters:**
1070
- `array` (`List[T]`): Array to modify.
1071
- `values` (`Iterable[T]`): Values to remove.
1072
- `iteratee` (`Callable`, optional): Function to transform elements.
1073

1074
**Returns:**
1075
- `List[T]`: `array`.
1076

1077
### pull_all_with
1078

1079
```python { .api }
1080
def pull_all_with(array: List[T], values: Iterable[T], comparator=None) -> List[T]
1081
```
1082

1083
Like `pull_all` except that it accepts a comparator which is invoked to compare elements of array to values.
1084

1085
**Parameters:**
1086
- `array` (`List[T]`): Array to modify.
1087
- `values` (`Iterable[T]`): Values to remove.
1088
- `comparator` (`Callable`, optional): Function to compare elements.
1089

1090
**Returns:**
1091
- `List[T]`: `array`.
1092

1093
### pull_at
1094

1095
```python { .api }
1096
def pull_at(array: List[T], *indexes: int) -> List[T]
1097
```
1098

1099
Removes elements from array corresponding to the given indexes and returns a list of the removed elements.
1100

1101
**Parameters:**
1102
- `array` (`List[T]`): Array to modify.
1103
- `indexes` (`*int`): Indexes of elements to remove.
1104

1105
**Returns:**
1106
- `List[T]`: New array of removed elements.
1107

1108
**Example:**
1109
```python { .api }
1110
from pydash import pull_at
1111

1112
array = ['a', 'b', 'c', 'd']
1113
pulled = pull_at(array, 1, 3)
1114
# array is now ['a', 'c']
1115
# pulled is ['b', 'd']
1116
```
1117

1118
### push
1119

1120
```python { .api }
1121
def push(array: List[T], *items: T2) -> List[Union[T, T2]]
1122
```
1123

1124
Appends `items` to `array`.
1125

1126
**Parameters:**
1127
- `array` (`List[T]`): Array to modify.
1128
- `items` (`*T2`): Items to append.
1129

1130
**Returns:**
1131
- `List[Union[T, T2]]`: `array`.
1132

1133
**Example:**
1134
```python { .api }
1135
from pydash import push
1136

1137
array = [1, 2]
1138
push(array, 3, 4)
1139
# [1, 2, 3, 4]
1140
```
1141

1142
### pop
1143

1144
```python { .api }
1145
def pop(array: List[T], index: int = -1) -> T
1146
```
1147

1148
Removes and returns the element at `index` from `array`.
1149

1150
**Parameters:**
1151
- `array` (`List[T]`): Array to modify.
1152
- `index` (`int`): Index of element to remove. Defaults to `-1`.
1153

1154
**Returns:**
1155
- `T`: Removed element.
1156

1157
**Example:**
1158
```python { .api }
1159
from pydash import pop
1160

1161
array = [1, 2, 3]
1162
pop(array)
1163
# 3
1164
# array is now [1, 2]
1165
```
1166

1167
### shift
1168

1169
```python { .api }
1170
def shift(array: List[T]) -> T
1171
```
1172

1173
Removes and returns the first element from `array`.
1174

1175
**Parameters:**
1176
- `array` (`List[T]`): Array to modify.
1177

1178
**Returns:**
1179
- `T`: Removed element.
1180

1181
**Example:**
1182
```python { .api }
1183
from pydash import shift
1184

1185
array = [1, 2, 3]
1186
shift(array)
1187
# 1
1188
# array is now [2, 3]
1189
```
1190

1191
### unshift
1192

1193
```python { .api }
1194
def unshift(array: List[T], *items: T2) -> List[Union[T, T2]]
1195
```
1196

1197
Prepends `items` to the front of `array`.
1198

1199
**Parameters:**
1200
- `array` (`List[T]`): Array to modify.
1201
- `items` (`*T2`): Items to prepend.
1202

1203
**Returns:**
1204
- `List[Union[T, T2]]`: `array`.
1205

1206
**Example:**
1207
```python { .api }
1208
from pydash import unshift
1209

1210
array = [3, 4]
1211
unshift(array, 1, 2)
1212
# [1, 2, 3, 4]
1213
```
1214

1215
### remove
1216

1217
```python { .api }
1218
def remove(array: List[T], predicate=None) -> List[T]
1219
```
1220

1221
Removes all elements from array that predicate returns truthy for and returns a list of the removed elements.
1222

1223
**Parameters:**
1224
- `array` (`List[T]`): Array to modify.
1225
- `predicate` (`Callable`, optional): Function invoked per iteration.
1226

1227
**Returns:**
1228
- `List[T]`: New array of removed elements.
1229

1230
**Example:**
1231
```python { .api }
1232
from pydash import remove
1233

1234
array = [1, 2, 3, 4]
1235
evens = remove(array, lambda x: x % 2 == 0)
1236
# array is now [1, 3]
1237
# evens is [2, 4]
1238
```
1239

1240
### reverse
1241

1242
```python { .api }
1243
def reverse(array: SequenceT) -> SequenceT
1244
```
1245

1246
Reverses array so that the first element becomes the last, the second element becomes the second to last, and so on.
1247

1248
**Parameters:**
1249
- `array` (`SequenceT`): Array to reverse.
1250

1251
**Returns:**
1252
- `SequenceT`: `array`.
1253

1254
**Example:**
1255
```python { .api }
1256
from pydash import reverse
1257

1258
array = [1, 2, 3]
1259
reverse(array)
1260
# [3, 2, 1]
1261
```
1262

1263
### slice_
1264

1265
```python { .api }
1266
def slice_(array: SequenceT, start: int = 0, end: Union[int, None] = None) -> SequenceT
1267
```
1268

1269
Creates a slice of array from `start` up to, but not including, `end`.
1270

1271
**Parameters:**
1272
- `array` (`SequenceT`): Array to slice.
1273
- `start` (`int`): Start position. Defaults to `0`.
1274
- `end` (`Union[int, None]`): End position.
1275

1276
**Returns:**
1277
- `SequenceT`: Slice of array.
1278

1279
**Example:**
1280
```python { .api }
1281
from pydash import slice_
1282

1283
slice_([1, 2, 3, 4], 2)
1284
# [3, 4]
1285

1286
slice_([1, 2, 3, 4], 1, 3)
1287
# [2, 3]
1288
```
1289

1290
### splice
1291

1292
```python { .api }
1293
def splice(array: List[T], start: int, count: int = None, *items: T2) -> List[T]
1294
```
1295

1296
Changes the contents of array by removing existing elements and/or adding new elements.
1297

1298
**Parameters:**
1299
- `array` (`List[T]`): Array to modify.
1300
- `start` (`int`): Start index.
1301
- `count` (`int`, optional): Number of elements to remove.
1302
- `items` (`*T2`): Items to insert.
1303

1304
**Returns:**
1305
- `List[T]`: List of removed elements.
1306

1307
**Example:**
1308
```python { .api }
1309
from pydash import splice
1310

1311
array = [1, 2, 3, 4]
1312
removed = splice(array, 1, 2, 'a', 'b')
1313
# array is now [1, 'a', 'b', 4]
1314
# removed is [2, 3]
1315
```
1316

1317
## Array Utilities
1318

1319
### duplicates
1320

1321
```python { .api }
1322
def duplicates(array: Iterable[T]) -> List[T]
1323
```
1324

1325
Creates a unique list of duplicate values from array.
1326

1327
**Parameters:**
1328
- `array` (`Iterable[T]`): Array to inspect.
1329

1330
**Returns:**
1331
- `List[T]`: New array of duplicate values.
1332

1333
**Example:**
1334
```python { .api }
1335
from pydash import duplicates
1336

1337
duplicates([0, 1, 3, 2, 3, 1])
1338
# [3, 1]
1339
```
1340

1341
### mapcat
1342

1343
```python { .api }
1344
def mapcat(array: Iterable[T], iteratee=None) -> List[T2]
1345
```
1346

1347
Maps `iteratee` over `array` and concatenates/flattens the result.
1348

1349
**Parameters:**
1350
- `array` (`Iterable[T]`): Array to iterate over.
1351
- `iteratee` (`Callable`, optional): Function invoked per iteration.
1352

1353
**Returns:**
1354
- `List[T2]`: New concatenated array.
1355

1356
**Example:**
1357
```python { .api }
1358
from pydash import mapcat
1359

1360
mapcat([1, 2], lambda x: [x, x])
1361
# [1, 1, 2, 2]
1362
```
1363

1364
### sort
1365

1366
```python { .api }
1367
def sort(array: List[T], comparator=None, key=None, reverse=False) -> List[T]
1368
```
1369

1370
Sorts array in-place using optional comparator, key function, or reverse flag.
1371

1372
**Parameters:**
1373
- `array` (`List[T]`): Array to sort.
1374
- `comparator` (`Callable`, optional): Comparison function.
1375
- `key` (`Callable`, optional): Key function.
1376
- `reverse` (`bool`): Whether to reverse sort order. Defaults to `False`.
1377

1378
**Returns:**
1379
- `List[T]`: `array`.
1380

1381
**Example:**
1382
```python { .api }
1383
from pydash import sort
1384

1385
array = [3, 1, 2]
1386
sort(array)
1387
# [1, 2, 3]
1388
```
1389

1390
### split_at
1391

1392
```python { .api }
1393
def split_at(array: Sequence[T], index: int) -> List[Sequence[T]]
1394
```
1395

1396
Splits `array` into two arrays: one with elements up to but not including `index` and another with the remaining elements.
1397

1398
**Parameters:**
1399
- `array` (`Sequence[T]`): Array to split.
1400
- `index` (`int`): Index to split at.
1401

1402
**Returns:**
1403
- `List[Sequence[T]]`: List of two split arrays.
1404

1405
**Example:**
1406
```python { .api }
1407
from pydash import split_at
1408

1409
split_at([1, 2, 3, 4], 2)
1410
# [[1, 2], [3, 4]]
1411
```
1412

1413
### uniq
1414

1415
```python { .api }
1416
def uniq(array: Iterable[T]) -> List[T]
1417
```
1418

1419
Creates a duplicate-free version of an array using SameValueZero for equality comparisons.
1420

1421
**Parameters:**
1422
- `array` (`Iterable[T]`): Array to inspect.
1423

1424
**Returns:**
1425
- `List[T]`: New duplicate free array.
1426

1427
**Example:**
1428
```python { .api }
1429
from pydash import uniq
1430

1431
uniq([2, 1, 2])
1432
# [2, 1]
1433
```
1434

1435
### uniq_by
1436

1437
```python { .api }
1438
def uniq_by(array: Iterable[T], iteratee=None) -> List[T]
1439
```
1440

1441
Like `uniq` except that it accepts an iteratee which is invoked for each element in array to generate the criterion by which uniqueness is computed.
1442

1443
**Parameters:**
1444
- `array` (`Iterable[T]`): Array to inspect.
1445
- `iteratee` (`Callable`, optional): Function to transform elements.
1446

1447
**Returns:**
1448
- `List[T]`: New duplicate free array.
1449

1450
**Example:**
1451
```python { .api }
1452
from pydash import uniq_by
1453
import math
1454

1455
uniq_by([2.1, 1.2, 2.3], math.floor)
1456
# [2.1, 1.2]
1457
```
1458

1459
### uniq_with
1460

1461
```python { .api }
1462
def uniq_with(array: Iterable[T], comparator=None) -> List[T]
1463
```
1464

1465
Like `uniq` except that it accepts a comparator which is invoked to compare elements of array.
1466

1467
**Parameters:**
1468
- `array` (`Iterable[T]`): Array to inspect.
1469
- `comparator` (`Callable`, optional): Function to compare elements.
1470

1471
**Returns:**
1472
- `List[T]`: New duplicate free array.
1473

1474
### without
1475

1476
```python { .api }
1477
def without(array: Iterable[T], *values: T) -> List[T]
1478
```
1479

1480
Creates an array excluding all given values using SameValueZero for equality comparisons.
1481

1482
**Parameters:**
1483
- `array` (`Iterable[T]`): Array to inspect.
1484
- `values` (`*T`): Values to exclude.
1485

1486
**Returns:**
1487
- `List[T]`: New array of filtered values.
1488

1489
**Example:**
1490
```python { .api }
1491
from pydash import without
1492

1493
without([2, 1, 2, 3], 1, 2)
1494
# [3]
1495
```
1496

1497
## Sorted Array Functions
1498

1499
### sorted_index
1500

1501
```python { .api }
1502
def sorted_index(array: Sequence[Any], value: Any) -> int
1503
```
1504

1505
Uses a binary search to determine the lowest index at which `value` should be inserted into array in order to maintain its sort order.
1506

1507
**Parameters:**
1508
- `array` (`Sequence[Any]`): Sorted array to inspect.
1509
- `value` (`Any`): Value to evaluate.
1510

1511
**Returns:**
1512
- `int`: Index at which `value` should be inserted.
1513

1514
**Example:**
1515
```python { .api }
1516
from pydash import sorted_index
1517

1518
sorted_index([30, 50], 40)
1519
# 1
1520
```
1521

1522
### sorted_index_by
1523

1524
```python { .api }
1525
def sorted_index_by(array: Sequence[T], value: T, iteratee=None) -> int
1526
```
1527

1528
Like `sorted_index` except that it accepts an iteratee which is invoked for `value` and each element of array to compute their sort ranking.
1529

1530
**Parameters:**
1531
- `array` (`Sequence[T]`): Sorted array to inspect.
1532
- `value` (`T`): Value to evaluate.
1533
- `iteratee` (`Callable`, optional): Function to transform values.
1534

1535
**Returns:**
1536
- `int`: Index at which `value` should be inserted.
1537

1538
### sorted_index_of
1539

1540
```python { .api }
1541
def sorted_index_of(array: Sequence[Any], value: Any) -> int
1542
```
1543

1544
Like `index_of` except that it performs a binary search on a sorted array.
1545

1546
**Parameters:**
1547
- `array` (`Sequence[Any]`): Sorted array to inspect.
1548
- `value` (`Any`): Value to search for.
1549

1550
**Returns:**
1551
- `int`: Index of `value`, else -1.
1552

1553
### sorted_last_index
1554

1555
```python { .api }
1556
def sorted_last_index(array: Sequence[Any], value: Any) -> int
1557
```
1558

1559
Like `sorted_index` except that it returns the highest index at which `value` should be inserted.
1560

1561
**Parameters:**
1562
- `array` (`Sequence[Any]`): Sorted array to inspect.
1563
- `value` (`Any`): Value to evaluate.
1564

1565
**Returns:**
1566
- `int`: Index at which `value` should be inserted.
1567

1568
### sorted_last_index_by
1569

1570
```python { .api }
1571
def sorted_last_index_by(array: Sequence[T], value: T, iteratee=None) -> int
1572
```
1573

1574
Like `sorted_last_index` except that it accepts an iteratee which is invoked for `value` and each element of array.
1575

1576
**Parameters:**
1577
- `array` (`Sequence[T]`): Sorted array to inspect.
1578
- `value` (`T`): Value to evaluate.
1579
- `iteratee` (`Callable`, optional): Function to transform values.
1580

1581
**Returns:**
1582
- `int`: Index at which `value` should be inserted.
1583

1584
### sorted_last_index_of
1585

1586
```python { .api }
1587
def sorted_last_index_of(array: Sequence[Any], value: Any) -> int
1588
```
1589

1590
Like `last_index_of` except that it performs a binary search on a sorted array.
1591

1592
**Parameters:**
1593
- `array` (`Sequence[Any]`): Sorted array to inspect.
1594
- `value` (`Any`): Value to search for.
1595

1596
**Returns:**
1597
- `int`: Index of `value`, else -1.
1598

1599
### sorted_uniq
1600

1601
```python { .api }
1602
def sorted_uniq(array: Iterable[SupportsRichComparisonT]) -> List[SupportsRichComparisonT]
1603
```
1604

1605
Like `uniq` except that it's designed and optimized for sorted arrays.
1606

1607
**Parameters:**
1608
- `array` (`Iterable[SupportsRichComparisonT]`): Sorted array to inspect.
1609

1610
**Returns:**
1611
- `List[SupportsRichComparisonT]`: New duplicate free array.
1612

1613
### sorted_uniq_by
1614

1615
```python { .api }
1616
def sorted_uniq_by(array: Sequence[T], iteratee=None) -> List[T]
1617
```
1618

1619
Like `uniq_by` except that it's designed and optimized for sorted arrays.
1620

1621
**Parameters:**
1622
- `array` (`Sequence[T]`): Sorted array to inspect.
1623
- `iteratee` (`Callable`, optional): Function to transform elements.
1624

1625
**Returns:**
1626
- `List[T]`: New duplicate free array.
1627

1628
## Advanced Array Operations
1629

1630
### intercalate
1631

1632
```python { .api }
1633
def intercalate(array: Iterable[Any], separator: Any) -> List[Any]
1634
```
1635

1636
Like `intersperse` but automatically flattens the result.
1637

1638
**Parameters:**
1639
- `array` (`Iterable[Any]`): Array to intercalate.
1640
- `separator` (`Any`): Separator to insert.
1641

1642
**Returns:**
1643
- `List[Any]`: Intercalated array.
1644

1645
**Example:**
1646
```python { .api }
1647
from pydash import intercalate
1648

1649
intercalate([1, [2], [3]], 0)
1650
# [1, 0, 2, 0, 3]
1651
```
1652

1653
### interleave
1654

1655
```python { .api }
1656
def interleave(*arrays: Iterable[T]) -> List[T]
1657
```
1658

1659
Merges multiple arrays by round-robin insertion of each array's elements.
1660

1661
**Parameters:**
1662
- `arrays` (`*Iterable[T]`): Arrays to interleave.
1663

1664
**Returns:**
1665
- `List[T]`: Interleaved array.
1666

1667
**Example:**
1668
```python { .api }
1669
from pydash import interleave
1670

1671
interleave([1, 2, 3], [4, 5, 6], [7, 8, 9])
1672
# [1, 4, 7, 2, 5, 8, 3, 6, 9]
1673
```
1674

1675
### intersperse
1676

1677
```python { .api }
1678
def intersperse(array: Iterable[T], separator: T2) -> List[Union[T, T2]]
1679
```
1680

1681
Inserts a separator between each element of array.
1682

1683
**Parameters:**
1684
- `array` (`Iterable[T]`): Array to modify.
1685
- `separator` (`T2`): Separator to insert.
1686

1687
**Returns:**
1688
- `List[Union[T, T2]]`: Interspersed array.
1689

1690
**Example:**
1691
```python { .api }
1692
from pydash import intersperse
1693

1694
intersperse([1, 2, 3], 0)
1695
# [1, 0, 2, 0, 3]
1696
```
1697

1698
This module provides comprehensive array manipulation capabilities with 76 functions covering all aspects of array processing from basic operations to complex transformations and set operations.