Refactor Scalar Operations

docs/pages/api.rst

@@ -452,28 +452,22 @@ contains
 
 Check if the collection contains one or more values.
 
-.. warning:: The `values` parameter is variadic and will be evaluated as a logical ``OR``.
-             If you're looking for a logical ``AND``, you have to make separate calls to this method;
-             note the calls cannot be in succession because the collection will contain a boolean after the first call.
+.. warning:: The ``values`` parameter is variadic and will be evaluated as a logical ``OR``.
 
 Interface: `Containsable`_
 
 Signature: ``Collection::contains(...$values);``
 
 .. code-block:: php
 
-    $collection = Collection::fromIterable(range('a', 'c'))
-        ->contains('d'); // [false]
+    $result = Collection::fromIterable(range('a', 'c'))
+        ->contains('d'); // false
 
-    $collection = Collection::fromIterable(range('a', 'c'))
-        ->contains('a', 'z'); // [true]
+    $result = Collection::fromIterable(range('a', 'c'))
+        ->contains('a', 'z'); // true
 
-    $collection = Collection::fromIterable(['a' => 'b', 'c' => 'd'])
-        ->contains('d'); // ['c' => true]
-
-    if ($collection->contains('d')->current()) {
-        // do something
-    }
+    $result = Collection::fromIterable(['a' => 'b', 'c' => 'd'])
+        ->contains('d'); // true
 
 count
 ~~~~~
@@ -652,32 +646,25 @@ every
 
 This operation tests whether all elements in the collection pass the test implemented by the provided callback(s).
 
-.. warning:: The `callbacks` parameter is variadic and will be evaluated as a logical ``OR``.
-             If you're looking for a logical ``AND``, you have to make multiple calls to the
-             same operation.
+.. warning:: The ``callbacks`` parameter is variadic and will be evaluated as a logical ``OR``.
 
 Interface: `Everyable`_
 
 Signature: ``Collection::every(callable ...$callbacks);``
 
 .. code-block:: php
 
-    $callback = static function ($value): bool {
-        return $value < 20;
-    };
+    $callback = static function (int $value): bool => $value < 20;
 
-    Collection::fromIterable(range(0, 10))
-        ->every($callback)
-        ->current(); // true
+    $result = Collection::fromIterable(range(0, 10))
+        ->every($callback); // true
 
-    Collection::fromIterable(range(0, 10))
+    $result = Collection::fromIterable(range(0, 10))
         ->append(21)
-        ->every($callback)
-        ->current(); // false
+        ->every($callback); // false
 
-    Collection::fromIterable([])
-        ->every($callback)
-        ->current(); // true
+    $result = Collection::fromIterable([])
+        ->every($callback); // true
 
 explode
 ~~~~~~~
@@ -707,15 +694,14 @@ Signature: ``Collection::falsy();``
 
 .. code-block:: php
 
-    $truthyCollection = Collection::fromIterable([2, 3, 4])
-        ->falsy(); // [false]
+    $result = Collection::fromIterable([2, 3, 4])
+        ->falsy(); // false
 
-    $falsyCollection = Collection::fromIterable(['', null, 0])
-        ->falsy(); // [true]
+    $result = Collection::fromIterable([2, null, 4])
+        ->falsy(); // false
 
-    if ($falsyCollection->falsy()->current()) {
-        // do something
-    }
+    $result = Collection::fromIterable(['', null, 0])
+        ->falsy(); // true
 
 filter
 ~~~~~~
@@ -1008,29 +994,27 @@ Signature: ``Collection::groupBy(?callable $callback = null);``
 has
 ~~~
 
-Check if the collection has values.
+Check if the collection has values with the help of one or more callables.
 
-.. warning:: The `callbacks` parameter is variadic and will be evaluated as a logical ``OR``.
-             If you're looking for a logical ``AND``, you have to make multiple calls to the
-             same operation.
+.. warning:: The ``callbacks`` parameter is variadic and will be evaluated as a logical ``OR``.
 
 Interface: `Hasable`_
 
 Signature: ``Collection::has(callable ...$callbacks);``
 
 .. code-block:: php
 
-    Collection::fromIterable(range('A', 'C'))
-        ->has(static fn (): string => 'B'); // [1 => true]
+    $result = Collection::fromIterable(range('A', 'C'))
+        ->has(static fn (): string => 'B'); // true
 
-    Collection::fromIterable(range('A', 'C'))
-        ->has(static fn (): string => 'D'); // [0 => false]
+    $result = Collection::fromIterable(range('A', 'C'))
+        ->has(static fn (): string => 'D'); // false
 
-    Collection::fromIterable(range('A', 'C'))
+    $result = Collection::fromIterable(range('A', 'C'))
         ->has(
-            static fn ($value, $key, Iterator $iterator): string => 'A',
-            static fn ($value, $key, Iterator $iterator): string => 'Z'
-        ); // [true]
+            static fn ($value, $key): string => $key > 4 ? 'D' : 'A',
+            static fn ($value, $key): string => 'Z'
+        ); // true
 
 head
 ~~~~
@@ -1325,15 +1309,15 @@ Signature: ``Collection::mapN(callable ...$callbacks);``
 match
 ~~~~~
 
-Check if the collection match a ``user callback``.
+Check if the collection matches a given ``user callback``.
 
-You must provide a callback that will get the ``key``, the ``current value``, and the ``iterator`` as parameters.
+You must provide a callback that can get the ``key``, the ``current value``, and the ``iterator`` as parameters.
 
 When no matcher callback is provided, the user callback must return ``true`` (the
 default value of the ``matcher callback``) in order to stop.
 
-The returned value of the operation is ``true`` when the callback match at least one element
-of the collection. ``false`` otherwise.
+The returned value of the operation is ``true`` when the callback matches at least one element
+of the collection, ``false`` otherwise.
 
 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, and it must return a ``boolean``.
@@ -1427,15 +1411,11 @@ Signature: ``Collection::nullsy();``
 
 .. code-block:: php
 
-    $nullsy = Collection::fromIterable([null, null])
-        ->nullsy(); // [true]
+    $result = Collection::fromIterable([null, false])
+        ->nullsy(); // true
 
-    $nonNullsy = Collection::fromIterable(['a', null, 'c'])
-        ->nullsy(); // [false]
-
-    if ($falsyCollection->nullsy()->current()) {
-        // do something
-    }
+    $result = Collection::fromIterable(['a', null, 'c'])
+        ->nullsy(); // false
 
 pack
 ~~~~
@@ -2081,15 +2061,11 @@ Signature: ``Collection::truthy();``
 
 .. code-block:: php
 
-    $truthyCollection = Collection::fromIterable([2, 3, 4])
-        ->truthy(); // [true]
+    $result = Collection::fromIterable([2, 3, 4])
+        ->truthy(); // true
 
-    $falsyCollection = Collection::fromIterable(['a', '', 'c', 'd'])
-        ->truthy(); // [false]
-
-    if ($falsyCollection->truthy()->current()) {
-        // do something
-    }
+    $result = Collection::fromIterable(['a', '', 'c', 'd'])
+        ->truthy(); // false
 
 unlines
 ~~~~~~~

docs/pages/code/operations/match.php

@@ -13,23 +13,15 @@
 
 include __DIR__ . '/../../../../vendor/autoload.php';
 
-// Example 1
-$matcher = static function (int $value): bool {
-    return 10 > $value;
-};
+// Example 1 -> match found
+$result = Collection::fromIterable(range(1, 100))
+    ->match(static fn (int $value): bool => 10 > $value); // true
 
-$collection = Collection::fromIterable(range(1, 100))
-    ->match($matcher); // true
+// Example 2 -> match not found
+$result = Collection::fromIterable(range(1, 100))
+    ->match(static fn (int $value): bool => 314 < $value); // false
 
-// Example 2
-$matcher = static function (int $value): bool {
-    return 314 < $value;
-};
-
-$collection = Collection::fromIterable(range(1, 100))
-    ->match($matcher); // false
-
-// Example 3
+// Example 3 -> match found
 $input = [
     'Ningbo (CN)',
     'California (US)',
@@ -39,5 +31,9 @@
 
 $pattern = '/\(EU\)$/';
 
-$collection = Collection::fromIterable($input)
+$result = Collection::fromIterable($input)
     ->match(static fn (string $value): bool => (bool) preg_match($pattern, $value)); // true
+
+// Example 4 -> custom matcher
+$result = Collection::fromIterable(range(1, 10))
+    ->match(static fn (int $value): bool => 5 !== $value, static fn (): bool => false); // true