Support folding via Monoids

src/Bonami/Collection/ArrayList.php

@@ -7,6 +7,7 @@
 use ArrayIterator;
 use Bonami\Collection\Exception\NotImplementedException;
 use Bonami\Collection\Exception\OutOfBoundsException;
+use Bonami\Collection\Monoid\Monoid;
 use Countable;
 use IteratorAggregate;
 use JsonSerializable;
@@ -699,6 +700,22 @@ public function reduce(callable $reducer, $initialReduction)
         }, $initialReduction);
     }
 
+    /**
+     * Reduce (folds) List to single value using Monoid
+     *
+     * Complexity: o(n)
+     *
+     * @phpstan-param Monoid<T> $monoid
+     *
+     * @phpstan-return T
+     */
+    public function mfold(Monoid $monoid)
+    {
+        return array_reduce($this->items, static function ($carry, $next) use ($monoid) {
+            return $monoid->concat($carry, $next);
+        }, $monoid->getEmpty());
+    }
+
     /**
      * Finds minimal value defined by comparator
      *

src/Bonami/Collection/LazyList.php

@@ -5,6 +5,7 @@
 namespace Bonami\Collection;
 
 use ArrayIterator;
+use Bonami\Collection\Monoid\Monoid;
 use Generator;
 use InvalidArgumentException;
 use Iterator;
@@ -208,6 +209,24 @@ public function reduce(callable $reducer, $initialReduction)
         return $reduction;
     }
 
+    /**
+     * Reduce (folds) List to single value using Monoid
+     *
+     * Complexity: o(n)
+     *
+     * @phpstan-param Monoid<T> $monoid
+     *
+     * @phpstan-return T
+     */
+    public function mfold(Monoid $monoid)
+    {
+        $reduction = $monoid->getEmpty();
+        foreach ($this->items as $item) {
+            $reduction = $monoid->concat($reduction, $item);
+        }
+        return $reduction;
+    }
+
     /**
      * Computes a prefix scan (reduction) of the elements of the collection.
      *

src/Bonami/Collection/Monoid/DoubleProductMonoid.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bonami\Collection\Monoid;
+
+/** @phpstan-implements Monoid<double> */
+class DoubleProductMonoid implements Monoid
+{
+
+    public function concat($a, $b)
+    {
+        return $a * $b;
+    }
+
+    public function getEmpty()
+    {
+        return 1;
+    }
+}

src/Bonami/Collection/Monoid/DoubleSumMonoid.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bonami\Collection\Monoid;
+
+/** @phpstan-implements Monoid<double> */
+class DoubleSumMonoid implements Monoid
+{
+
+    public function concat($a, $b)
+    {
+        return $a + $b;
+    }
+
+    public function getEmpty()
+    {
+        return 0;
+    }
+}

src/Bonami/Collection/Monoid/IntProductMonoid.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bonami\Collection\Monoid;
+
+/** @phpstan-implements Monoid<int> */
+class IntProductMonoid implements Monoid
+{
+
+    public function concat($a, $b)
+    {
+        return $a * $b;
+    }
+
+    public function getEmpty()
+    {
+        return 1;
+    }
+}

src/Bonami/Collection/Monoid/IntSumMonoid.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bonami\Collection\Monoid;
+
+/** @phpstan-implements Monoid<int> */
+class IntSumMonoid implements Monoid
+{
+
+    public function concat($a, $b)
+    {
+        return $a + $b;
+    }
+
+    public function getEmpty()
+    {
+        return 0;
+    }
+}

src/Bonami/Collection/Monoid/Monoid.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bonami\Collection\Monoid;
+
+/** @phpstan-template A */
+interface Monoid
+{
+
+    /**
+     * A binary operation.
+     *
+     * It must follow monoid laws:
+     * - associativity - `concat(concat($a, $b), $c) === concat($a, concat($b, $c))` for any element `A`
+     * - identity law - `concat($a, getEmpty()) === concat(getEmpty(), $a) === $a`
+     *
+     * @phpstan-param A $a
+     * @phpstan-param A $b
+     *
+     * @phpstan-return A
+     */
+    public function concat($a, $b);
+
+    /**
+     * Neutral element for binary concat operation
+     *
+     * @phpstan-return A
+     */
+    public function getEmpty();
+}

src/Bonami/Collection/Monoid/StringMonoid.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bonami\Collection\Monoid;
+
+/** @phpstan-implements Monoid<string> */
+class StringMonoid implements Monoid
+{
+
+    public function concat($a, $b)
+    {
+        return $a . $b;
+    }
+
+    public function getEmpty()
+    {
+        return "";
+    }
+}

tests/Bonami/Collection/ArrayListTest.php

@@ -6,6 +6,7 @@
 
 use ArrayIterator;
 use Bonami\Collection\Exception\OutOfBoundsException;
+use Bonami\Collection\Monoid\IntSumMonoid;
 use PHPUnit\Framework\TestCase;
 use RuntimeException;
 use stdClass;
@@ -432,6 +433,13 @@ public function testReduce(): void
         self::assertEquals(6, $sum);
     }
 
+    public function testMfold(): void
+    {
+        $list = ArrayList::of(1, 2, 3);
+        $sum = $list->mfold(new IntSumMonoid());
+        self::assertEquals(6, $sum);
+    }
+
     public function testMin(): void
     {
         self::assertEquals(Option::some(1), ArrayList::of(3, 1, 2)->min(comparator()));

tests/Bonami/Collection/LazyListTest.php

@@ -5,6 +5,7 @@
 namespace Bonami\Collection;
 
 use ArrayIterator;
+use Bonami\Collection\Monoid\IntSumMonoid;
 use EmptyIterator;
 use Generator;
 use InvalidArgumentException;
@@ -227,6 +228,13 @@ public function testReduce(): void
         self::assertEquals(6, $sum);
     }
 
+    public function testMfold(): void
+    {
+        $list = LazyList::of(1, 2, 3);
+        $sum = $list->mfold(new IntSumMonoid());
+        self::assertEquals(6, $sum);
+    }
+
     public function testScan(): void
     {
         $lazyList = LazyList::fill(1);

tests/Bonami/Collection/Monoid/MonoidTest.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bonami\Collection\Monoid;
+
+use PHPUnit\Framework\TestCase;
+
+class MonoidTest extends TestCase
+{
+
+    /**
+     * @dataProvider provideFixtures
+     *
+     * @phpstan-template A
+     *
+     * @phpstan-param A $a
+     * @phpstan-param A $b
+     * @phpstan-param Monoid<A> $monoid
+     * @phpstan-param A $result
+     */
+    public function testFromMonoids($a, $b, Monoid $monoid, $result): void
+    {
+        self::assertSame($a, $monoid->concat($a, $monoid->getEmpty()));
+        self::assertSame($a, $monoid->concat($monoid->getEmpty(), $a));
+        self::assertSame($result, $monoid->concat($a, $b));
+    }
+
+    /** @phpstan-return iterable<array{0: mixed, 1: mixed, 2: Monoid<mixed>, 3: mixed}> */
+    public function provideFixtures(): iterable
+    {
+        yield [1, 2, new IntSumMonoid(), 3];
+        yield [1, 2, new IntProductMonoid(), 2];
+        yield [1.1, 2.1, new DoubleSumMonoid(), 3.2];
+        yield [1.1, 2.1, new DoubleProductMonoid(), 2.31];
+        yield ["foo", "bar", new StringMonoid(), "foobar"];
+    }
+}