feat: introduce iterable.find (#8)

Author: simPod

README.md

@@ -18,3 +18,18 @@ match ($val) {
   default => noop(),
 };
 ```
+
+## Iterable
+
+### find()
+
+Finds a value in an iterable.
+
+```php
+use function Cdn77\Functions\Iterable\find;
+
+$iterable = [0, 1, 2, 3];
+$option = find($iterable, static fn (mixed $_, int $value) => $value < 2);
+
+assert($option->get() === 0);
+```

composer.json

@@ -20,7 +20,8 @@
     ],
     "require": {
         "php": "^8.0",
-        "ext-ds": "*"
+        "ext-ds": "*",
+        "phpoption/phpoption": "^1.9"
     },
     "require-dev": {
         "cdn77/coding-standard": "^6.0",

src/functions_include.php

@@ -5,5 +5,6 @@
 require_once __DIR__ . '/absurd.php';
 require_once __DIR__ . '/ds.php';
 require_once __DIR__ . '/generator.php';
+require_once __DIR__ . '/iterable.php';
 require_once __DIR__ . '/never.php';
 require_once __DIR__ . '/noop.php';

src/iterable.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cdn77\Functions\Iterable;
+
+use PhpOption\None;
+use PhpOption\Option;
+use PhpOption\Some;
+
+/**
+ * @param iterable<K, T> $iterable
+ * @param callable(K, T): bool $filterFn
+ *
+ * @return Option<T>
+ *
+ * @template K
+ * @template T
+ */
+function find(iterable $iterable, callable $filterFn): Option
+{
+    foreach ($iterable as $k => $v) {
+        if ($filterFn($k, $v)) {
+            return new Some($v);
+        }
+    }
+
+    return None::create();
+}

tests/IterableTest.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cdn77\Functions\Tests;
+
+use PhpOption\None;
+use PHPUnit\Framework\TestCase;
+
+use function Cdn77\Functions\Iterable\find;
+
+final class IterableTest extends TestCase
+{
+    public function testFindFirst(): void
+    {
+        $iterable = [0, 1, 2, 3];
+        $option = find($iterable, static fn (mixed $_, int $value) => $value < 2);
+
+        self::assertSame(0, $option->getOrElse(null));
+    }
+
+    public function testDontFind(): void
+    {
+        $iterable = [0, 1, 2, 3];
+        $option = find($iterable, static fn (mixed $_, int $value) => $value > 3);
+
+        self::assertSame(None::create(), $option);
+    }
+}