refactor: Update Match operation.

docs/pages/api.rst

@@ -1077,24 +1077,25 @@ Signature: ``Collection::map(callable ...$callbacks);``
 match
 ~~~~~
 
-Check if the collection has a value that match a callback.
+Check if the collection match a ``user callback``.
 
-The returned value is true if the callback match at least one element
-of the collection. False otherwise.
+User must provide a callback that will get the ``key``, the ``current value`` and the ``iterator`` as parameters.
 
-Interface: `Matchable`_
+When no matcher callback is provided, the user callback must return ``true`` (the
+default value of the ``matcher callback``) in order to stop.
 
-Signature: ``Collection::match(callable $callback);``
+The returned value of the operation is ``true`` when the callback match at least one element
+of the collection. ``false`` otherwise.
 
-.. code-block:: php
+If you want to match the ``user callback`` against another value (other than ``true``), you must
+provide your own ``matcher callback`` as a second argument.
 
-    $matcher = static function(int $value): bool {
-        return $value % 2;
-    };
+Interface: `Matchable`_
 
-    $collection = Collection::fromIterable(range(1, 100))
-        ->match($matcher)
-        ->current(); // true
+Signature: ``Collection::match(callable $callback, ?callable $matcher = null);``
+
+.. literalinclude:: code/operations/match.php
+  :language: php
 
 merge
 ~~~~~

docs/pages/code/operations/match.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use loophp\collection\Collection;
+
+include __DIR__ . '/../../../../vendor/autoload.php';
+
+// Example 1
+$matcher = static function (int $value): bool {
+    return 10 > $value;
+};
+
+$collection = Collection::fromIterable(range(1, 100))
+    ->match($matcher); // true
+
+// Example 2
+$matcher = static function (int $value): bool {
+    return 314 < $value;
+};
+
+$collection = Collection::fromIterable(range(1, 100))
+    ->match($matcher); // false
+
+// Example 3
+$input = [
+    'Ningbo (CN)',
+    'California (US)',
+    'Brussels (EU)',
+    'New York (US)',
+];
+
+$pattern = '/\(EU\)$/';
+
+$colletion = Collection::fromIterable($input)
+    ->match(
+        static fn (string $value): bool => preg_match($pattern, $value)
+    ); // true

spec/loophp/collection/CollectionSpec.php

@@ -1594,6 +1594,20 @@ static function (int $value): bool {
                 }
             )
             ->shouldIterateAs([0 => false]);
+
+        $this::fromIterable($input)
+            ->match(
+                static fn (int $value): string => 17 === $value ? 'foo' : 'bar',
+                static fn (): string => 'foo'
+            )
+            ->shouldIterateAs([0 => false]);
+
+        $this::fromIterable($input)
+            ->match(
+                static fn (int $value): string => 5 === $value ? 'foo' : 'bar',
+                static fn (): string => 'foo'
+            )
+            ->shouldIterateAs([4 => true]);
     }
 
     public function it_can_merge(): void

src/Collection.php

@@ -532,9 +532,11 @@ public function map(callable ...$callbacks): CollectionInterface
         return new self(Map::of()(...$callbacks), $this->getIterator());
     }
 
-    public function match(callable $callback): CollectionInterface
+    public function match(callable $callback, ?callable $matcher = null): CollectionInterface
     {
-        return new self(Match::of()(static fn () => true)($callback), $this->getIterator());
+        $matcher = $matcher ?? static fn () => true;
+
+        return new self(Match::of()($matcher)($callback), $this->getIterator());
     }
 
     public function merge(iterable ...$sources): CollectionInterface

src/Contract/Operation/Matchable.php

@@ -16,8 +16,9 @@ interface Matchable
 {
     /**
      * @psalm-param callable(T, TKey, Iterator<TKey, T>): bool $callback
+     * @psalm-param null|callable(T, TKey, Iterator<TKey, T>): T $matcher
      *
      * @psalm-return \loophp\collection\Collection<int, bool>
      */
-    public function match(callable $callback): Collection;
+    public function match(callable $callback, ?callable $matcher = null): Collection;
 }