Revert "refactor: remove reduce() from the main branch for 1.x"

ramsey · raphaelts3 · ramsey · commit dd2918f9d376 · 2022-12-27T13:22:49.000-06:00
This reverts commit 94a6ace. Co-authored-by: Raphael Tomé Santana <raphaelts3@gmail.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## 2.0.0 - TBD
+
+### Added
+
+* Add support for CollectionInterface::reduce().
+
 ## 1.3.0 - 2022-12-27
 
 ### Fixed
diff --git a/src/AbstractCollection.php b/src/AbstractCollection.php
@@ -26,6 +26,7 @@
 use function array_filter;
 use function array_map;
 use function array_merge;
+use function array_reduce;
 use function array_search;
 use function array_udiff;
 use function array_uintersect;
@@ -210,6 +211,14 @@ public function map(callable $callback): CollectionInterface
         return new Collection('mixed', array_map($callback, $this->data));
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function reduce(callable $callback, $initial = null)
+    {
+        return array_reduce($this->data, $callback, $initial);
+    }
+
     public function diff(CollectionInterface $other): CollectionInterface
     {
         $this->compareCollectionTypes($other);
diff --git a/src/CollectionInterface.php b/src/CollectionInterface.php
@@ -173,6 +173,27 @@ public function where(string $propertyOrMethod, $value): self;
      */
     public function map(callable $callback): self;
 
+    /**
+     * Apply a given callback method on each item of the collection
+     * to reduce it to a single value. If an initial value is provided
+     * it will be used at the beginning of the process, or as a final
+     * result in case the array is empty.
+     *
+     * See the {@link http://php.net/manual/en/function.array-reduce.php PHP array_reduce() documentation}
+     * for examples of how the `$callback` and `$initial` parameters work.
+     *
+     * @param callable(TCarry|null, T): (TCarry|null) $callback A callable to apply to each
+     *     item of the collection to reduce it to a single value.
+     * @param TCarry|null $initial If provided, this is the initial value provided
+     *     to the callback.
+     *
+     * @return TCarry|mixed
+     *
+     * @template TCarry
+     */
+    // phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
+    public function reduce(callable $callback, $initial = null);
+
     /**
      * Create a new collection with divergent items between current and given
      * collection.
diff --git a/tests/CollectionManipulationTest.php b/tests/CollectionManipulationTest.php
@@ -178,6 +178,38 @@ public function testMapShouldRunOverEachItem(): void
         $this->assertNotSame($barCollection, $mapCollection);
     }
 
+    public function testReduceShouldRunOverEachItem(): void
+    {
+        $bar1 = new Bar(1, 'a');
+        $bar2 = new Bar(2, 'b');
+
+        $barCollection = new BarCollection([$bar1, $bar2]);
+
+        $reduceCollection = $barCollection->reduce(function (?int $carry, Bar $item): int {
+            $carry += $item->getId();
+
+            return $carry;
+        });
+
+        $this->assertSame(3, $reduceCollection);
+    }
+
+    public function testReduceShouldUseInitialIfProvided(): void
+    {
+        $bar1 = new Bar(1, 'a');
+        $bar2 = new Bar(2, 'b');
+
+        $barCollection = new BarCollection([$bar1, $bar2]);
+
+        $reduceCollection = $barCollection->reduce(function (?int $carry, Bar $item): int {
+            $carry += $item->getId();
+
+            return $carry;
+        }, 1);
+
+        $this->assertSame(4, $reduceCollection);
+    }
+
     public function testDiffShouldRaiseExceptionOnDiverseCollections(): void
     {
         $barCollection = new BarCollection();
