refactor: Refactor Reduce operation. (#259)

* refactor: Refactor `Reduce` operation. BREAKING CHANGE: yes * refactor: Refactor `FoldLeft` operation. BREAKING CHANGE: yes * refactor: Refactor `FoldLeft1` operation. BREAKING CHANGE: yes * refactor: Refactor `FoldRight` operation. BREAKING CHANGE: yes * refactor: Refactor `FoldRight1` operation. BREAKING CHANGE: yes * refactor: Refactor `First` operation. BREAKING CHANGE: yes * refactor: Refactor `Implode` operation. BREAKING CHANGE: yes * refactor: Update `Unlines` operation. * refactor: Update `Unwords` operation. * Update PHPStan baseline. * refactor: Update `Last` operation. * refactor: Update `Head` operation. * refactor: Update `Get` operation. * refactor: Update `Partition` operation. * refactor: Update `Span` operation. * Refactor operations: - compare - min - max * Further update documentation * refactor: Refactor `Reduce` operation. BREAKING CHANGE: yes * refactor: Refactor `FoldLeft` operation. BREAKING CHANGE: yes * refactor: Refactor `FoldLeft1` operation. BREAKING CHANGE: yes * refactor: Refactor `FoldRight` operation. BREAKING CHANGE: yes * refactor: Refactor `FoldRight1` operation. BREAKING CHANGE: yes * refactor: Refactor `First` operation. BREAKING CHANGE: yes * refactor: Refactor `Implode` operation. BREAKING CHANGE: yes * refactor: Update `Unlines` operation. * refactor: Update `Unwords` operation. * Update PHPStan baseline. * refactor: Update `Last` operation. * refactor: Update `Head` operation. * refactor: Update `Get` operation. * refactor: Update `Partition` operation. * refactor: Update `Span` operation. * Refactor operations: - compare - min - max * Further update documentation * Update docs with default param * Use unique functions for static analysis checks Co-authored-by: AlexandruGG <alex.gidei@gmail.com>
loophp · Sep 12, 2022 · e3eaa14 · e3eaa14
1 parent 734f054
commit e3eaa14
Show file tree

Hide file tree

Showing 42 changed files with 422 additions and 507 deletions.
diff --git a/docs/pages/api.rst b/docs/pages/api.rst
@@ -502,18 +502,18 @@ Signature: ``Collection::compact(...$values): Collection;``
 compare
 ~~~~~~~
 
-Fold the collection through a comparison operation, yielding the "highest" or "lowest" 
-element as defined by the comparator callback. The callback takes a pair of two elements 
+Fold the collection through a comparison operation, yielding the "highest" or "lowest"
+element as defined by the comparator callback. The callback takes a pair of two elements
 and should return the "highest" or "lowest" one as desired.
 
-If no custom logic is required for the comparison, the simpler ``max`` or ``min`` operations 
+If no custom logic is required for the comparison, the simpler ``max`` or ``min`` operations
 can be used instead.
 
 .. tip:: This operation is a specialised application of ``foldLeft1``.
 
 Interface: `Comparable`_
 
-Signature: ``Collection::compare(callable $comparator): Collection;``
+Signature: ``Collection::compare(callable $comparator, $default = null): Collection;``
 
 .. literalinclude:: code/operations/compare.php
   :language: php
@@ -838,26 +838,20 @@ first
 
 Get the first item from the collection in a separate collection. Alias for ``head``.
 
-The ``current`` operation can then be used to extract the item out of the collection.
-
 Interface: `Firstable`_
 
-Signature: ``Collection::first(): Collection;``
+Signature: ``Collection::first($default = null): mixed;``
 
 .. code-block:: php
 
         $generator = static function (): Generator {
             yield 'a' => 'a';
             yield 'b' => 'b';
             yield 'c' => 'c';
-            yield 'a' => 'd';
-            yield 'b' => 'e';
-            yield 'c' => 'f';
         };
 
         Collection::fromIterable($generator())
-            ->first()
-            ->current(); // ['a' => 'a']
+            ->first(); // a
 
 flatMap
 ~~~~~~~
@@ -954,7 +948,7 @@ on. See ``scanLeft`` for intermediate results.
 
 Interface: `FoldLeftable`_
 
-Signature: ``Collection::foldLeft(callable $callback, $initial = null): Collection;``
+Signature: ``Collection::foldLeft(callable $callback, $initial = null): mixed;``
 
 .. code-block:: php
 
@@ -966,7 +960,7 @@ Signature: ``Collection::foldLeft(callable $callback, $initial = null): Collecti
                 return $carry;
             },
             ''
-        ); // [2 => 'ABC']
+        ); // 'ABC'
 
 foldLeft1
 ~~~~~~~~~
@@ -977,17 +971,17 @@ See ``scanLeft1`` for intermediate results.
 
 Interface: `FoldLeft1able`_
 
-Signature: ``Collection::foldLeft1(callable $callback): Collection;``
+Signature: ``Collection::foldLeft1(callable $callback): mixed;``
 
 .. code-block:: php
 
     $callback = static fn(int $carry, int $value): int => $carry - $value;
 
     Collection::fromIterable([64, 4, 2, 8])
-        ->foldLeft1($callback); // [0 => 50]
+        ->foldLeft1($callback); // 50
 
     Collection::empty()
-        ->foldLeft1($callback); // []
+        ->foldLeft1($callback); // null
 
 foldRight
 ~~~~~~~~~
@@ -998,7 +992,7 @@ See ``scanRight`` for intermediate results.
 
 Interface: `FoldRightable`_
 
-Signature: ``Collection::foldRight(callable $callback, $initial = null): Collection;``
+Signature: ``Collection::foldRight(callable $callback, $initial = null): mixed;``
 
 .. code-block:: php
 
@@ -1010,7 +1004,7 @@ Signature: ``Collection::foldRight(callable $callback, $initial = null): Collect
                 return $carry;
             },
             ''
-        ); // [0 => 'CBA']
+        ); // 'CBA'
 
 foldRight1
 ~~~~~~~~~~
@@ -1021,17 +1015,17 @@ intermediate results.
 
 Interface: `FoldRight1able`_
 
-Signature: ``Collection::foldRight1(callable $callback): Collection;``
+Signature: ``Collection::foldRight1(callable $callback): mixed;``
 
 .. code-block:: php
 
     $callback = static fn(int $carry, int $value): int => $carry + $value;
 
     Collection::fromIterable([1, 2, 3, 4])
-        ->foldRight1($callback); // [0 => 10]
+        ->foldRight1($callback); // 10
 
     Collection::empty()
-        ->foldRight1($callback); // []
+        ->foldRight1($callback); // null
 
 forget
 ~~~~~~
@@ -1075,9 +1069,9 @@ Signature: ``Collection::get($key, $default = null): Collection;``
 
 .. code-block:: php
 
-    Collection::fromIterable(range('a', 'c'))->get(1) // [1 => 'b']
+    Collection::fromIterable(range('a', 'c'))->get(1) // 'b'
 
-    Collection::fromIterable(range('a', 'c'))->get(4, '') // [0 => '']
+    Collection::fromIterable(range('a', 'c'))->get(4, '') // ''
 
 group
 ~~~~~
@@ -1147,11 +1141,9 @@ head
 
 Get the first item from the collection in a separate collection. Same as ``first``.
 
-The ``current`` operation can then be used to extract the item out of the collection.
-
 Interface: `Headable`_
 
-Signature: ``Collection::head(): Collection;``
+Signature: ``Collection::head($default = null): mixed;``
 
 .. code-block:: php
 
@@ -1165,8 +1157,7 @@ Signature: ``Collection::head(): Collection;``
     };
 
     Collection::fromIterable($generator())
-        ->head()
-        ->current(); // [1 => 'a']
+        ->head(); // 'a'
 
 ifThenElse
 ~~~~~~~~~~
@@ -1206,16 +1197,14 @@ implode
 
 Join all the elements of the collection into a single string using a glue provided or the empty string as default.
 
-.. tip:: Internally this operation uses ``foldLeft``, which is why the result will have the last element's key.
-
 Interface: `Implodeable`_
 
-Signature: ``Collection::implode(string $glue = ''): Collection;``
+Signature: ``Collection::implode(string $glue = ''): string;``
 
 .. code-block:: php
 
     Collection::fromIterable(range('a', 'c'))
-        ->implode('-'); // [2 => 'a-b-c']
+        ->implode('-'); // 'a-b-c'
 
 init
 ~~~~
@@ -1351,11 +1340,9 @@ last
 
 Extract the last element of a collection, which must be finite and non-empty.
 
-The ``current`` operation can then be used to extract the item out of the collection.
-
 Interface: `Lastable`_
 
-Signature: ``Collection::last(): Collection;``
+Signature: ``Collection::last($default = null): Collection;``
 
 .. code-block:: php
 
@@ -1369,8 +1356,7 @@ Signature: ``Collection::last(): Collection;``
         };
 
         Collection::fromIterable($generator())
-            ->last()
-            ->current(); // ['c' => 'f']
+            ->last(); // 'f'
 
 limit
 ~~~~~
@@ -1497,12 +1483,12 @@ max
 Generate the maximum value of the collection by successively applying the PHP ``max`` function
 to each pair of two elements.
 
-If custom logic is required to determine the maximum, such as when comparing objects, 
+If custom logic is required to determine the maximum, such as when comparing objects,
 the ``compare`` operation can be used instead.
 
 Interface: `Maxable`_
 
-Signature: ``Collection::max(): Collection;``
+Signature: ``Collection::max($default = null): Collection;``
 
 .. literalinclude:: code/operations/max.php
   :language: php
@@ -1532,12 +1518,12 @@ min
 Generate the minimum value of the collection by successively applying the PHP ``min`` function
 to each pair of two elements.
 
-If custom logic is required to determine the minimum, such as when comparing objects, 
+If custom logic is required to determine the minimum, such as when comparing objects,
 the ``compare`` operation can be used instead.
 
 Interface: `Minable`_
 
-Signature: ``Collection::min(): Collection;``
+Signature: ``Collection::min($default = null): Collection;``
 
 .. literalinclude:: code/operations/min.php
   :language: php
@@ -1834,7 +1820,7 @@ Reduce a collection of items through a given callback.
 
 Interface: `Reduceable`_
 
-Signature: ``Collection::reduce(callable $callback, $initial = null): Collection;``
+Signature: ``Collection::reduce(callable $callback, $initial = null): mixed;``
 
 .. literalinclude:: code/operations/reduce.php
   :language: php
@@ -2286,7 +2272,7 @@ Opposite of ``lines``, creates a single string from multiple lines using ``PHP_E
 
 Interface: `Unlinesable`_
 
-Signature: ``Collection::unlines(): Collection;``
+Signature: ``Collection::unlines(): string;``
 
 .. code-block:: php
 
@@ -2298,11 +2284,9 @@ Signature: ``Collection::unlines(): Collection;``
 
     Collection::fromIterable($lines)
         ->unlines();
-    // [
     //    'The quick brown fox jumps over the lazy dog.
     //
     //     This is another sentence.'
-    // ]
 
 unpack
 ~~~~~~
@@ -2401,7 +2385,7 @@ creates a single string from multiple strings using one space as the glue.
 
 Interface: `Unwordsable`_
 
-Signature: ``Collection::unwords(): Collection;``
+Signature: ``Collection::unwords(): string;``
 
 .. code-block:: php
 
@@ -2418,7 +2402,7 @@ Signature: ``Collection::unwords(): Collection;``
     ];
 
     Collection::fromIterable($words)
-        ->unwords(); // ['The quick brown fox jumps over the lazy dog.']
+        ->unwords(); // 'The quick brown fox jumps over the lazy dog.'
 
 unwrap
 ~~~~~~

diff --git a/docs/pages/code/e.php b/docs/pages/code/e.php
@@ -16,14 +16,12 @@
 $addition = static fn (float $value1, float $value2): float => $value1 + $value2;
 
 $fact = static fn (float $number): float => (float) Collection::range(1, $number + 1)
-    ->foldLeft($multiplication, 1)
-    ->current();
+    ->foldLeft($multiplication, 1);
 
 $number_e_approximation = Collection::unfold(static fn (int $i = 0): array => [$i + 1])
     ->unwrap()
     ->map(static fn (float $value): float => $value / $fact($value))
     ->until(static fn (float $value): bool => 10 ** -12 > $value)
-    ->foldLeft($addition, 0)
-    ->current();
+    ->foldLeft($addition, 0);
 
 var_dump($number_e_approximation); // 2.718281828459
diff --git a/docs/pages/code/gamma.php b/docs/pages/code/gamma.php
@@ -45,7 +45,6 @@
 $gamma_factorial_approximation = Collection::fromIterable($ℕ)
     ->map($γ($number))
     ->until($ε)
-    ->foldLeft($addition, 0)
-    ->current();
+    ->foldLeft($addition, 0);
 
 print_r($gamma_factorial_approximation);
diff --git a/docs/pages/code/operations/compare.php b/docs/pages/code/operations/compare.php
@@ -12,12 +12,16 @@
 use loophp\collection\Collection;
 use stdClass;
 
+use const INF;
+
 include __DIR__ . '/../../../../vendor/autoload.php';
 
 $callback = static fn (stdClass $left, stdClass $right): stdClass => $left->age > $right->age
     ? $left
     : $right;
 
 $result = Collection::fromIterable([(object) ['id' => 2, 'age' => 5], (object) ['id' => 1, 'age' => 10]])
-    ->compare($callback)
-    ->current(); // (object) ['id' => 1, 'age' => 10]
+    ->compare($callback); // (object) ['id' => 1, 'age' => 10]
+
+$result = Collection::empty()
+    ->compare($callback, -INF); // -INF
diff --git a/docs/pages/code/operations/max.php b/docs/pages/code/operations/max.php
@@ -11,12 +11,15 @@
 
 use loophp\collection\Collection;
 
+use const PHP_INT_MAX;
+
 include __DIR__ . '/../../../../vendor/autoload.php';
 
 $result = Collection::fromIterable([1, 4, 3, 0, 2])
-    ->max()      // [1 => 4]
-    ->current(); // 4
+    ->max(); // 4
 
 $result = Collection::fromIterable([1, 4, null, 0, 2])
-    ->max()
-    ->current(); // 4
+    ->max(); // 4
+
+$result = Collection::empty()
+    ->max(PHP_INT_MAX); // PHP_INT_MAX
diff --git a/docs/pages/code/operations/min.php b/docs/pages/code/operations/min.php
@@ -11,12 +11,15 @@
 
 use loophp\collection\Collection;
 
+use const PHP_INT_MIN;
+
 include __DIR__ . '/../../../../vendor/autoload.php';
 
 $result = Collection::fromIterable([1, 4, 3, 0, 2])
-    ->min()      // [4 => 0]
-    ->current(); // 0
+    ->min(); // 0
 
 $result = Collection::fromIterable([1, 4, null, 0, 2])
-    ->min()
-    ->current(); // null
+    ->min(); // null
+
+$result = Collection::empty()
+    ->min(PHP_INT_MIN); // PHP_INT_MIN
diff --git a/docs/pages/code/operations/partition.php b/docs/pages/code/operations/partition.php
@@ -54,8 +54,7 @@
 // Example 2 -> Retrieve the first group only
 $left = Collection::fromIterable($input)
     ->partition($isGreaterThan(5))
-    ->first()
-    ->current();
+    ->first();
 
 // Numbers that are greater than 5
 print_r($left->all(false));

diff --git a/docs/pages/code/operations/reduce.php b/docs/pages/code/operations/reduce.php
@@ -16,7 +16,7 @@
 $callback = static fn (int $carry, int $item): int => $carry + $item;
 
 $collection = Collection::empty()
-    ->reduce($callback); // []
+    ->reduce($callback); // null
 
 $collection = Collection::fromIterable(range(1, 5))
-    ->reduce($callback, 0); // [4 => 15]
+    ->reduce($callback, 0); // 15
diff --git a/docs/pages/code/operations/span.php b/docs/pages/code/operations/span.php
@@ -28,8 +28,7 @@
 // Example 2 -> Retrieve the second group only
 $last = Collection::fromIterable($input)
     ->span(static fn ($x): bool => 4 > $x)
-    ->last()
-    ->current();
+    ->last();
 
 print_r($last->all()); // [4, 5, 6, 7, 8, 9, 10]