Add Pair operation.

docs/pages/api.rst

@@ -714,6 +714,56 @@ Signature: ``Collection::pad(int $size, $value);``
     $collection = Collection::with(range(1, 5))
         ->pad(10, 'foo');
 
+pair
+~~~~
+
+Make an associative collection from pairs of values.
+
+Interface: `Pairable`_
+
+Signature: ``Collection::pair();``
+
+.. code-block:: php
+
+    $input = [
+        [
+            'key' => 'k1',
+            'value' => 'v1',
+        ],
+        [
+            'key' => 'k2',
+            'value' => 'v2',
+        ],
+        [
+            'key' => 'k3',
+            'value' => 'v3',
+        ],
+        [
+            'key' => 'k4',
+            'value' => 'v4',
+        ],
+        [
+            'key' => 'k4',
+            'value' => 'v5',
+        ],
+    ];
+
+    $c = Collection::fromIterable($input)
+        ->unwrap()
+        ->pair()
+        ->group()
+        ->all();
+
+    // [
+    //    [k1] => v1
+    //    [k2] => v2
+    //    [k3] => v3
+    //    [k4] => [
+    //        [0] => v4
+    //        [1] => v5
+    //    ]
+    // ]
+
 permutate
 ~~~~~~~~~
 
@@ -1276,6 +1326,7 @@ Interface: `Truthyable`_
 .. _Nullsyable: https://github.com/loophp/collection/blob/master/src/Contract/Transformation/Nullsyable.php
 .. _Onlyable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Onlyable.php
 .. _Padable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Padable.php
+.. _Pairable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Pairable.php
 .. _Permutateable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Permutateable.php
 .. _Pluckable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Pluckable.php
 .. _Prependable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Prependable.php

spec/loophp/collection/CollectionSpec.php

@@ -1211,6 +1211,49 @@ public function it_can_pad(): void
             ->shouldIterateAs(['A' => 'A', 'B' => 'B', 'C' => 'C', 'D' => 'D', 'E' => 'E', 0 => 'foo', 1 => 'foo', 2 => 'foo', 3 => 'foo', 4 => 'foo']);
     }
 
+    public function it_can_pair(): void
+    {
+        $input = [
+            [
+                'key' => 'k1',
+                'value' => 'v1',
+            ],
+            [
+                'key' => 'k2',
+                'value' => 'v2',
+            ],
+            [
+                'key' => 'k3',
+                'value' => 'v3',
+            ],
+            [
+                'key' => 'k4',
+                'value' => 'v4',
+            ],
+            [
+                'key' => 'k4',
+                'value' => 'v5',
+            ],
+        ];
+
+        $gen = static function () {
+            yield 'k1' => 'v1';
+
+            yield 'k2' => 'v2';
+
+            yield 'k3' => 'v3';
+
+            yield 'k4' => 'v4';
+
+            yield 'k4' => 'v5';
+        };
+
+        $this::fromIterable($input)
+            ->unwrap()
+            ->pair()
+            ->shouldIterateAs($gen());
+    }
+
     public function it_can_permutate(): void
     {
         $this::fromIterable(range('a', 'c'))

src/Collection.php

@@ -45,6 +45,7 @@
 use loophp\collection\Operation\Nth;
 use loophp\collection\Operation\Only;
 use loophp\collection\Operation\Pad;
+use loophp\collection\Operation\Pair;
 use loophp\collection\Operation\Permutate;
 use loophp\collection\Operation\Pluck;
 use loophp\collection\Operation\Prepend;
@@ -454,6 +455,11 @@ public function pad(int $size, $value): CollectionInterface
         return $this->run(new Pad($size, $value));
     }
 
+    public function pair(): CollectionInterface
+    {
+        return $this->run(new Pair());
+    }
+
     public function permutate(): CollectionInterface
     {
         return $this->run(new Permutate());

src/Contract/Collection.php

@@ -39,6 +39,7 @@
 use loophp\collection\Contract\Operation\Nthable;
 use loophp\collection\Contract\Operation\Onlyable;
 use loophp\collection\Contract\Operation\Padable;
+use loophp\collection\Contract\Operation\Pairable;
 use loophp\collection\Contract\Operation\Permutateable;
 use loophp\collection\Contract\Operation\Pluckable;
 use loophp\collection\Contract\Operation\Prependable;
@@ -125,6 +126,7 @@
  * @template-extends Nthable<TKey, T>
  * @template-extends Onlyable<TKey, T>
  * @template-extends Padable<TKey, T>
+ * @template-extends Pairable<TKey, T>
  * @template-extends Permutateable<TKey, T>
  * @template-extends Pluckable<TKey, T>
  * @template-extends Prependable<TKey, T>
@@ -200,6 +202,7 @@ interface Collection extends
     Nullsyable,
     Onlyable,
     Padable,
+    Pairable,
     Permutateable,
     Pluckable,
     Prependable,

src/Contract/Operation/Pairable.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace loophp\collection\Contract\Operation;
+
+use loophp\collection\Contract\Collection;
+
+/**
+ * @psalm-template TKey
+ * @psalm-template TKey of array-key
+ * @psalm-template T
+ */
+interface Pairable
+{
+    /**
+     * @return \loophp\collection\Contract\Collection<TKey, T>
+     */
+    public function pair(): Collection;
+}

src/Operation/Pair.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace loophp\collection\Operation;
+
+use Closure;
+use Generator;
+use Iterator;
+use loophp\collection\Contract\Operation;
+use loophp\collection\Transformation\Run;
+
+/**
+ * @psalm-template TKey
+ * @psalm-template TKey of array-key
+ * @psalm-template T
+ */
+final class Pair extends AbstractOperation implements Operation
+{
+    public function __invoke(): Closure
+    {
+        return
+            /**
+             * @psalm-param \Iterator<TKey, T> $iterator
+             *
+             * @psalm-return \Generator<TKey, T>
+             */
+            static function (Iterator $iterator): Generator {
+                foreach ((new Run(new Chunk(2)))($iterator) as $chunk) {
+                    /** @psalm-var array{TKey, T} $chunk */
+                    $chunk = array_values($chunk);
+
+                    yield $chunk[0] => $chunk[1];
+                }
+            };
+    }
+}