Add Finder::rows()

Author: samsonasik

README.md

@@ -17,7 +17,7 @@ Features
 
 - [x] Verify at least times: `once()`, `twice()`, `times()`
 - [x] Verify exact times: `once()`, `twice()`, `times()`
-- [x] Search data: `first()`, `last()`
+- [x] Search data: `first()`, `last()`, `rows()`
 
 Installation
 ------------
@@ -319,3 +319,34 @@ var_dump(Finder::last(
     static fn ($datum, $key): bool => $datum < 5 && $key >= 0
 )); // null
 ```
+
+*3. `Finder::rows()`*
+
+It get rows data filtered found.
+
+```php
+use ArrayLookup\Finder;
+
+$data = [6, 7, 8, 9];
+var_dump(Finder::rows(
+    $data,
+    static fn($datum): bool => $datum > 6
+)); // [7, 8, 9]
+
+var_dump(Finder::rows(
+    $data,
+    static fn ($datum): bool => $datum < 5
+)); // []
+
+// ... with PRESERVE original key
+var_dump(Finder::rows(
+    $data,
+    static fn ($datum): bool => $datum > 6,
+    true
+)); // [1 => 7, 2 => 8, 3 => 9]
+
+var_dump(Finder::rows(
+    $data,
+    static fn ($datum): bool => $datum < 5,
+    true
+)); // []

src/Finder.php

@@ -116,4 +116,31 @@ public static function last(
 
         return null;
     }
+
+    /**
+     * @param array<int|string, mixed>|Traversable<int|string, mixed> $data
+     * @param callable(mixed $datum, int|string|null $key=): bool $filter
+     * @return mixed[]
+     */
+    public static function rows(iterable $data, callable $filter, bool $preserveKey = false): array
+    {
+        $rows = [];
+        $newKey = 0;
+
+        foreach ($data as $key => $datum) {
+            $isFound = $filter($datum, $key);
+
+            // returns of callable must be bool
+            Assert::boolean($isFound);
+
+            if (! $isFound) {
+                continue;
+            }
+
+            $rows[$preserveKey ? $key : $newKey] = $datum;
+            ++$newKey;
+        }
+
+        return $rows;
+    }
 }

tests/FinderTest.php

@@ -253,4 +253,58 @@ public static function lastReturnKeyResortKeyDataProvider(): array
             ],
         ];
     }
+
+    #[DataProvider('rowsDataProvider')]
+    public function testRows(iterable $data, callable $filter, array $expected): void
+    {
+        $this->assertSame(
+            $expected,
+            Finder::rows($data, $filter)
+        );
+    }
+
+    public static function rowsDataProvider(): array
+    {
+        return [
+            [
+                [6, 7, 8, 9],
+                static fn($datum): bool => $datum > 6,
+                [7, 8, 9],
+            ],
+            [
+                [6, 7, 8, 9],
+                static fn($datum): bool => $datum < 5,
+                [],
+            ],
+        ];
+    }
+
+    #[DataProvider('rowsDataProviderPreserveKey')]
+    public function testRowsPreserveKey(iterable $data, callable $filter, array $expected): void
+    {
+        $this->assertSame(
+            $expected,
+            Finder::rows($data, $filter, true)
+        );
+    }
+
+    public static function rowsDataProviderPreserveKey(): array
+    {
+        return [
+            [
+                [6, 7, 8, 9],
+                static fn($datum): bool => $datum > 6,
+                [
+                    1 => 7,
+                    2 => 8,
+                    3 => 9
+                ],
+            ],
+            [
+                [6, 7, 8, 9],
+                static fn($datum): bool => $datum < 5,
+                [],
+            ],
+        ];
+    }
 }