Update First operation.

loophp · Aug 22, 2020 · c7ac8b3 · c7ac8b3
1 parent 1d15657
commit c7ac8b3
Show file tree

Hide file tree

Showing 7 changed files with 163 additions and 104 deletions.
diff --git a/docs/pages/api.rst b/docs/pages/api.rst
@@ -458,6 +458,46 @@ Signature: ``Collection::filter(callable ...$callbacks);``
     $collection = Collection::with(range(1, 100))
         ->filter($callback);
 
+first
+~~~~~
+
+Get the first items from the collection passing the given truth test.
+
+Interface: `Firstable`_
+
+Signature: ``Collection::first(?callable $callback = null, int $size = 1);``
+
+.. code-block:: php
+
+        $generator = static function (): Generator {
+            yield 'a' => 'a';
+            yield 'b' => 'b';
+            yield 'c' => 'c';
+            yield 'a' => 'd';
+            yield 'b' => 'e';
+            yield 'c' => 'f';
+        };
+
+        Collection::fromIterable($generator())
+            ->first(
+                static function ($value, $key) {
+                    return 'b' === $key;
+                }
+            ); // ['b' => 'b']
+
+        $output = static function (): Generator {
+            yield 'b' => 'b';
+            yield 'b' => 'e';
+        };
+
+        Collection::fromIterable($generator())
+            ->first(
+                static function ($value, $key) {
+                    return 'b' === $key;
+                },
+                2
+            ); // ['b' => 'b', 'b' => 'e']
+
 flatten
 ~~~~~~~
 
@@ -1351,11 +1391,6 @@ falsy
 
 Interface: `Falsyable`_
 
-first
-~~~~~
-
-Interface: `Firstable`_
-
 foldLeft
 ~~~~~~~~
 
@@ -1425,7 +1460,7 @@ Interface: `Truthyable`_
 .. _Explodeable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Explodeable.php
 .. _Falsyable: https://github.com/loophp/collection/blob/master/src/Contract/Transformation/Falsyable.php
 .. _Filterable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Filterable.php
-.. _Firstable: https://github.com/loophp/collection/blob/master/src/Contract/Transformation/Firstable.php
+.. _Firstable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Firstable.php
 .. _Flattenable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Flattenable.php
 .. _Flipable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Flipable.php
 .. _array_flip(): https://php.net/array_flip

diff --git a/spec/loophp/collection/CollectionSpec.php b/spec/loophp/collection/CollectionSpec.php
@@ -836,32 +836,55 @@ public function it_can_get_items_with_only_specific_keys(): void
             ->shouldIterateAs([0 => 'A', 1 => 'B', 2 => 'C', 3 => 'D', 4 => 'E']);
     }
 
-    public function it_can_get_its_first_value(): void
+    public function it_can_get_the_first_item(): void
     {
         $this::fromIterable(range(1, 10))
             ->first()
-            ->shouldReturn(1);
+            ->shouldIterateAs([0 => 1]);
 
         $this::fromIterable(range(1, 10))
             ->first(
                 static function ($value) {
                     return 0 === $value % 5;
                 }
             )
-            ->shouldReturn(5);
-
-        $this::fromIterable(range(1, 10))
-            ->first(
-                static function ($value) {
-                    return 0 === $value % 11;
-                },
-                'foo'
-            )
-            ->shouldReturn('foo');
+            ->shouldIterateAs([4 => 5]);
 
         $this::fromIterable([])
             ->first()
-            ->shouldBe(null);
+            ->shouldIterateAs([]);
+
+        $generator = static function (): Generator {
+            yield 'a' => 'a';
+
+            yield 'b' => 'b';
+
+            yield 'c' => 'c';
+
+            yield 'a' => 'd';
+
+            yield 'b' => 'e';
+
+            yield 'c' => 'f';
+        };
+
+        $this::fromIterable($generator())
+            ->first(static function ($value, $key) {
+                return 'b' === $key;
+            })
+            ->shouldIterateAs(['b' => 'b']);
+
+        $output = static function (): Generator {
+            yield 'b' => 'b';
+
+            yield 'b' => 'e';
+        };
+
+        $this::fromIterable($generator())
+            ->first(static function ($value, $key) {
+                return 'b' === $key;
+            }, 2)
+            ->shouldIterateAs($output());
     }
 
     public function it_can_get_the_last_item(): void

diff --git a/src/Collection.php b/src/Collection.php
@@ -29,6 +29,7 @@
 use loophp\collection\Operation\Distinct;
 use loophp\collection\Operation\Explode;
 use loophp\collection\Operation\Filter;
+use loophp\collection\Operation\First;
 use loophp\collection\Operation\Flatten;
 use loophp\collection\Operation\Flip;
 use loophp\collection\Operation\Forget;
@@ -79,7 +80,6 @@
 use loophp\collection\Transformation\Contains;
 use loophp\collection\Transformation\Count;
 use loophp\collection\Transformation\Falsy;
-use loophp\collection\Transformation\First;
 use loophp\collection\Transformation\FoldLeft;
 use loophp\collection\Transformation\FoldRight;
 use loophp\collection\Transformation\Get;
@@ -327,9 +327,9 @@ public function filter(callable ...$callbacks): CollectionInterface
         return $this->run(new Filter(...$callbacks));
     }
 
-    public function first(?callable $callback = null, $default = null)
+    public function first(?callable $callback = null, int $size = 1): CollectionInterface
     {
-        return $this->transform(new First($callback, $default));
+        return $this->run(new First($callback, $size));
     }
 
     public function flatten(int $depth = PHP_INT_MAX): CollectionInterface

diff --git a/src/Contract/Collection.php b/src/Contract/Collection.php
@@ -22,6 +22,7 @@
 use loophp\collection\Contract\Operation\Distinctable;
 use loophp\collection\Contract\Operation\Explodeable;
 use loophp\collection\Contract\Operation\Filterable;
+use loophp\collection\Contract\Operation\Firstable;
 use loophp\collection\Contract\Operation\Flattenable;
 use loophp\collection\Contract\Operation\Flipable;
 use loophp\collection\Contract\Operation\Forgetable;
@@ -71,7 +72,6 @@
 use loophp\collection\Contract\Transformation\Allable;
 use loophp\collection\Contract\Transformation\Containsable;
 use loophp\collection\Contract\Transformation\Falsyable;
-use loophp\collection\Contract\Transformation\Firstable;
 use loophp\collection\Contract\Transformation\FoldLeftable;
 use loophp\collection\Contract\Transformation\FoldRightable;
 use loophp\collection\Contract\Transformation\Getable;

diff --git a/src/Contract/Transformation/Firstable.php → src/Contract/Operation/Firstable.php b/src/Contract/Transformation/Firstable.php → src/Contract/Operation/Firstable.php
@@ -2,7 +2,9 @@
 
 declare(strict_types=1);
 
-namespace loophp\collection\Contract\Transformation;
+namespace loophp\collection\Contract\Operation;
+
+use loophp\collection\Contract\Collection;
 
 /**
  * @psalm-template TKey
@@ -16,11 +18,7 @@ interface Firstable
      *
      * @psalm-param null|callable(T, TKey):(bool) $callback
      *
-     * @param mixed $default
-     * @psalm-param T|null $default
-     *
-     * @return mixed|null
-     * @psalm-return T|null
+     * @psalm-return \loophp\collection\Contract\Collection<TKey, T>
      */
-    public function first(?callable $callback = null, $default = null);
+    public function first(?callable $callback = null, int $size = 1): Collection;
 }
diff --git a/src/Operation/First.php b/src/Operation/First.php
@@ -0,0 +1,77 @@
+<?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
+ *
+ * @implements Operation<TKey, T>
+ */
+final class First extends AbstractOperation implements Operation
+{
+    /**
+     * @var callable
+     * @psalm-var callable(T, TKey):(bool)
+     */
+    private $callback;
+
+    /**
+     * @psalm-param callable(T, TKey):(bool)|null $callback
+     *
+     * @psalm-param T|null $default
+     */
+    public function __construct(?callable $callback = null, int $size = 1)
+    {
+        $defaultCallback =
+            /**
+             * @param mixed $value
+             * @param mixed $key
+             * @psalm-param T $value
+             * @psalm-param TKey $key
+             * @psalm-param Iterator<TKey, T> $iterator
+             */
+            static function ($value, $key, Iterator $iterator): bool {
+                return true;
+            };
+
+        $this->storage = [
+            'callback' => $callback ?? $defaultCallback,
+            'size' => $size,
+        ];
+    }
+
+    public function __invoke(): Closure
+    {
+        return
+            /**
+             * @psalm-param \Iterator<TKey, T> $iterator
+             *
+             * @psalm-return \Generator<TKey, T>
+             */
+            static function (Iterator $iterator, callable $callback, int $size): Generator {
+                $callback =
+                    /**
+                     * @param mixed $value
+                     * @param mixed $key
+                     * @psalm-param T $value
+                     * @psalm-param TKey $key
+                     * @psalm-param Iterator<TKey, T> $iterator
+                     */
+                    static function ($value, $key, Iterator $iterator) use ($callback): bool {
+                        return true === $callback($value, $key, $iterator);
+                    };
+
+                return yield from (new Run(new Filter($callback), new Limit($size)))($iterator);
+            };
+    }
+}
diff --git a/src/Transformation/First.php b/src/Transformation/First.php