Merge pull request #21 from worksolutions/first-element-filter

First element filter support

Author: sokolovsky

src/WS/Utils/Collections/DummyStreamDecorator.php

@@ -63,7 +63,7 @@ public function findAny()
         return $this->decoratedStream->findAny();
     }
 
-    public function findFirst()
+    public function findFirst(callable $filter = null)
     {
         return $this->decoratedStream->findFirst();
     }

src/WS/Utils/Collections/SerialStream.php

@@ -205,11 +205,20 @@ public function findAny()
     /**
      * @inheritDoc
      */
-    public function findFirst()
+    public function findFirst(callable $filter = null)
     {
+        if (!$filter) {
+            /** @noinspection LoopWhichDoesNotLoopInspection */
+            foreach ($this->list as $item) {
+                return $item;
+            }
+            return null;
+        }
         /** @noinspection LoopWhichDoesNotLoopInspection */
         foreach ($this->list as $item) {
-            return $item;
+            if ($filter($item)) {
+                return $item;
+            }
         }
         return null;
     }

src/WS/Utils/Collections/Stream.php

@@ -71,9 +71,10 @@ public function findAny();
 
     /**
      * Returns first collection element or null if absent
+     * @param callable|null $filter
      * @return mixed
      */
-    public function findFirst();
+    public function findFirst(callable $filter = null);
 
     /**
      * Returns last collection element or null if absent

tests/WS/Utils/Collections/SerialStreamTest.php

@@ -391,6 +391,15 @@ public function firstLastElementCases(): array
         ];
     }
 
+    public function firstFirstElementWithFilterCases(): array
+    {
+        return [
+            [ [1, 2, 3], 2, 2],
+            [ [1], 2, null],
+            [[], 2, null]
+        ];
+    }
+
     /**
      * @dataProvider firstLastElementCases
      * @test
@@ -405,6 +414,23 @@ public function findFirstElement($input, $first): void
         $this->assertEquals($first, $actual);
     }
 
+    /**
+     * @dataProvider firstFirstElementWithFilterCases
+     * @test
+     * @param array $input
+     * @param mixed $first
+     * @param mixed $expected
+     */
+    public function findFirstElementWithFilter(array $input, $first, $expected): void
+    {
+        $actual = $this->createCollection($input)
+            ->stream()
+            ->findFirst(function ($item) use ($first) {
+                return $item === $first;
+            });
+        $this->assertEquals($expected, $actual);
+    }
+
     /** @noinspection PhpUnusedParameterInspection */
     /**
      * @dataProvider firstLastElementCases