Update documentation.

docs/pages/api.rst

@@ -1509,12 +1509,25 @@ Signature: ``Collection::pair();``
 partition
 ~~~~~~~~~
 
-With one or multiple callable, partition the items into 2 subgroups of items.
+With one or multiple callable, partition the items into two subgroups of items.
 
 .. 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.
 
+The raw `Partition` operation returns a generator yielding two iterators only.
+
+The first inner iterator is the result of a `filter` operation, it contains items
+who has met the provided callback.
+The second and last inner is the result of a `reject` operation, it contains items
+who has not met the provided callback.
+
+When the `partition` operation is used through the `Collection` object, the two
+resulting iterators will be converted and mapped into a `Collection` object.
+
+The first inner collection contains items who has met the provided callback.
+The second and last collection contains items who has not met the provided callback.
+
 Interface: `Partitionable`_
 
 Signature: ``Collection::partition(callable ...$callbacks);``
@@ -1898,19 +1911,24 @@ Signature: ``Collection::sort(?callable $callback = null);``
 span
 ~~~~
 
-Returns a tuple where the first element is the longest prefix (possibly empty) of elements
-that satisfy the callback and the second element is the remainder.
+Partition the collection into two subgroups where the first element is the longest
+prefix (*possibly empty*) of elements that satisfy the callback and the second element
+is the remainder.
 
-Interface: `Spanable`_
+The raw `Span` operation returns a generator yielding two iterators only.
 
-Signature: ``Collection::span(callable $callback);``
+The first inner iterator is the result of a `TakeWhile` operation.
+The second and last inner is the result of a `DropWhile` operation.
 
-.. code-block:: php
+When the `span` operation is used through the `Collection` object, the two
+resulting iterators will be converted and mapped into a `Collection` object.
 
-    $input = range(1, 10);
+Interface: `Spanable`_
 
-    Collection::fromIterable($input)
-        ->span(fn ($x) => $x < 4); // [[1, 2, 3], [4, 5, 6, 7, 8, 9, 10]]
+Signature: ``Collection::span(callable $callback);``
+
+.. literalinclude:: code/operations/span.php
+  :language: php
 
 split
 ~~~~~

docs/pages/code/operations/partition.php

@@ -18,30 +18,54 @@
 
 $input = array_combine(range('a', 'l'), [1, 2, 3, 4, 5, 6, 7, 8, 9, 1, 2, 3]);
 
-$collection = Collection::fromIterable($input)
+// Example 1 - Retrieve the left and right groups
+[$left, $right] = Collection::fromIterable($input)
     ->partition(
-        $isGreaterThan(5),
-        $isGreaterThan(3)
-    );
+        $isGreaterThan(5)
+    )
+    ->all();
 
-// Result
+// Numbers that are greater than 5
+print_r($left->all());
 /*
 [
-    [
-        ['d', 4],
-        ['e', 5],
-        ['f', 6],
-        ['g', 7],
-        ['h', 8],
-        ['i', 9],
-    ],
-    [
-        ['a', 1],
-        ['b', 2],
-        ['c', 3],
-        ['j', 1],
-        ['k', 2],
-        ['l', 3],
-    ],
+    ['f', 6],
+    ['g', 7],
+    ['h', 8],
+    ['i', 9],
+]
+ */
+
+// Numbers that are not greater than 5
+print_r($right->all());
+/*
+[
+    ['a', 1],
+    ['b', 2],
+    ['c', 3],
+    ['d', 4],
+    ['e', 5],
+    ['j', 1],
+    ['k', 2],
+    ['l', 3],
+]
+ */
+
+ // Example 2 - Retrieve the first group
+$left = Collection::fromIterable($input)
+    ->partition(
+        $isGreaterThan(5)
+    )
+    ->first()
+    ->current();
+
+// Numbers that are greater than 5
+print_r($left->all());
+/*
+[
+['f', 6],
+['g', 7],
+['h', 8],
+['i', 9],
 ]
  */

docs/pages/code/operations/span.php

@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace App;
+
+use loophp\collection\Collection;
+
+include __DIR__ . '/../../../../vendor/autoload.php';
+
+$input = range(1, 10);
+
+Collection::fromIterable($input)
+    ->span(static fn ($x): bool => 4 > $x); // [[1, 2, 3], [4, 5, 6, 7, 8, 9, 10]]