Add Head operation.

docs/pages/api.rst

@@ -567,6 +567,27 @@ Signature: ``Collection::group(callable $callable = null);``
     $collection = Collection::with($callback)
         ->group();
 
+head
+~~~~
+
+Interface: `Headable`_
+
+Signature: ``Collection::head();``
+
+.. code-block:: php
+
+    $generator = static function (): \Generator {
+            yield 1 => 'a';
+            yield 1 => 'b';
+            yield 1 => 'c';
+            yield 2 => 'd';
+            yield 2 => 'e';
+            yield 3 => 'f';
+    };
+
+    Collection::fromIterable($generator())
+        ->head(); // [1 => 'a']
+
 intersect
 ~~~~~~~~~
 
@@ -1385,6 +1406,7 @@ Interface: `Truthyable`_
 .. _Getable: https://github.com/loophp/collection/blob/master/src/Contract/Transformation/Getable.php
 .. _Groupable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Groupable.php
 .. _Hasable: https://github.com/loophp/collection/blob/master/src/Contract/Transformation/Hasable.php
+.. _Headable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Headable.php
 .. _Implodeable: https://github.com/loophp/collection/blob/master/src/Contract/Transformation/Implodeable.php
 .. _Intersectable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Intersectable.php
 .. _Intersectkeysable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Intersectkeysable.php

spec/loophp/collection/CollectionSpec.php

@@ -973,6 +973,15 @@ public function it_can_has(): void
             ->shouldReturn(false);
     }
 
+    public function it_can_head(): void
+    {
+        $input = range('A', 'E');
+
+        $this::fromIterable($input)
+            ->head()
+            ->shouldIterateAs([0 => 'A']);
+    }
+
     public function it_can_implode(): void
     {
         $this::fromIterable(range('A', 'C'))

src/Collection.php

@@ -34,6 +34,7 @@
 use loophp\collection\Operation\Forget;
 use loophp\collection\Operation\Frequency;
 use loophp\collection\Operation\Group;
+use loophp\collection\Operation\Head;
 use loophp\collection\Operation\Intersect;
 use loophp\collection\Operation\IntersectKeys;
 use loophp\collection\Operation\Intersperse;
@@ -423,6 +424,11 @@ public function has(callable $callback): bool
         return $this->transform(new Has($callback));
     }
 
+    public function head(): CollectionInterface
+    {
+        return $this->run(new Head());
+    }
+
     public function implode(string $glue = ''): string
     {
         return $this->transform(new Implode($glue));

src/Contract/Collection.php

@@ -27,6 +27,7 @@
 use loophp\collection\Contract\Operation\Forgetable;
 use loophp\collection\Contract\Operation\Frequencyable;
 use loophp\collection\Contract\Operation\Groupable;
+use loophp\collection\Contract\Operation\Headable;
 use loophp\collection\Contract\Operation\Intersectable;
 use loophp\collection\Contract\Operation\Intersectkeysable;
 use loophp\collection\Contract\Operation\Intersperseable;
@@ -115,6 +116,7 @@
  * @template-extends Getable<TKey, T>
  * @template-extends Groupable<TKey, T>
  * @template-extends Hasable<TKey, T>
+ * @template-extends Headable<TKey, T>
  * @template-extends Intersectable<TKey, T>
  * @template-extends Intersectkeysable<TKey, T>
  * @template-extends Intersperseable<TKey, T>
@@ -187,6 +189,7 @@ interface Collection extends
     Getable,
     Groupable,
     Hasable,
+    Headable,
     Implodeable,
     Intersectable,
     Intersectkeysable,

src/Contract/Operation/Headable.php

@@ -0,0 +1,22 @@
+<?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 Headable
+{
+    /**
+     * Get the first item from the collection.
+     *
+     * @psalm-return \loophp\collection\Contract\Collection<TKey, T>
+     */
+    public function head(): Collection;
+}

src/Operation/Head.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace loophp\collection\Operation;
+
+use Closure;
+use Generator;
+use Iterator;
+use loophp\collection\Contract\Operation;
+
+/**
+ * @psalm-template TKey
+ * @psalm-template TKey of array-key
+ * @psalm-template T
+ *
+ * @implements Operation<TKey, T>
+ */
+final class Head extends AbstractOperation implements Operation
+{
+    /**
+     * @psalm-return Closure(Iterator<TKey, T>): (Generator<TKey, T>)
+     */
+    public function __invoke(): Closure
+    {
+        return static function (Iterator $iterator): Generator {
+            return yield $iterator->key() => $iterator->current();
+        };
+    }
+}