feat: Add Averages operation.

src/Collection.php

@@ -21,6 +21,7 @@
 use loophp\collection\Operation\Associate;
 use loophp\collection\Operation\AsyncMap;
 use loophp\collection\Operation\AsyncMapN;
+use loophp\collection\Operation\Averages;
 use loophp\collection\Operation\Cache;
 use loophp\collection\Operation\Chunk;
 use loophp\collection\Operation\Coalesce;
@@ -208,6 +209,11 @@ public function asyncMapN(callable ...$callbacks): CollectionInterface
         return new self((new AsyncMapN())()(...$callbacks), [$this]);
     }
 
+    public function averages(): CollectionInterface
+    {
+        return new self((new Averages())(), [$this]);
+    }
+
     public function cache(?CacheItemPoolInterface $cache = null): CollectionInterface
     {
         return new self((new Cache())()($cache ?? new ArrayAdapter()), [$this]);

src/Contract/Collection.php

@@ -18,6 +18,7 @@
 use loophp\collection\Contract\Operation\Associateable;
 use loophp\collection\Contract\Operation\AsyncMapable;
 use loophp\collection\Contract\Operation\AsyncMapNable;
+use loophp\collection\Contract\Operation\Averagesable;
 use loophp\collection\Contract\Operation\Cacheable;
 use loophp\collection\Contract\Operation\Chunkable;
 use loophp\collection\Contract\Operation\Coalesceable;
@@ -142,6 +143,7 @@
  * @template-extends Associateable<TKey, T>
  * @template-extends AsyncMapable<TKey, T>
  * @template-extends AsyncMapNable<TKey, T>
+ * @template-extends Averagesable<TKey, T>
  * @template-extends Cacheable<TKey, T>
  * @template-extends Chunkable<TKey, T>
  * @template-extends Coalesceable<TKey, T>
@@ -259,6 +261,7 @@ interface Collection extends
     Associateable,
     AsyncMapable,
     AsyncMapNable,
+    Averagesable,
     Cacheable,
     Chunkable,
     Coalesceable,

src/Contract/Operation/Averagesable.php

@@ -0,0 +1,28 @@
+<?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 loophp\collection\Contract\Operation;
+
+use loophp\collection\Contract\Collection;
+
+/**
+ * @template TKey
+ * @template T
+ */
+interface Averagesable
+{
+    /**
+     * Compute the averages.
+     *
+     * @see https://loophp-collection.readthedocs.io/en/stable/pages/api.html#averages
+     *
+     * @return Collection<TKey, float>
+     */
+    public function averages(): Collection;
+}

src/Operation/Averages.php

@@ -0,0 +1,43 @@
+<?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 loophp\collection\Operation;
+
+use Closure;
+
+/**
+ * @immutable
+ *
+ * @template TKey
+ * @template T
+ *
+ * phpcs:disable Generic.Files.LineLength.TooLong
+ */
+final class Averages extends AbstractOperation
+{
+    /**
+     * @return Closure(iterable<TKey, T>): Generator<int, float>
+     */
+    public function __invoke(): Closure
+    {
+        return Pipe::of()(
+            (new Normalize())(),
+            (new Associate())()(static fn (int $i): int => $i + 1)(static fn ($i) => $i),
+            (new ScanLeft1())()(
+                /**
+                 * @param float $acc
+                 * @param float $value
+                 *
+                 * @return float
+                 */
+                static fn ($acc, $value, int $key) => ($acc * ($key - 1) + $value) / ($key)
+            )
+        );
+    }
+}

tests/unit/CollectionGenericOperationTest.php

@@ -31,6 +31,7 @@ final class CollectionGenericOperationTest extends TestCase
      * @dataProvider associateOperationProvider
      * @dataProvider asyncMapOperationProvider
      * @dataProvider asyncMapNOperationProvider
+     * @dataProvider averagesOperationProvider
      * @dataProvider cacheOperationProvider
      * @dataProvider chunkOperationProvider
      * @dataProvider coalesceOperationProvider

tests/unit/Traits/GenericCollectionProviders.php

@@ -175,6 +175,19 @@ static function (int $v): int {
         ];
     }
 
+    public function averagesOperationProvider()
+    {
+        $operation = 'averages';
+        $input = range(0, 5);
+
+        yield [
+            $operation,
+            [],
+            $input,
+            [(int) 0, (float) .5, (float) 1.0, (float) 1.5, (float) 2.0, (float) 2.5],
+        ];
+    }
+
     public function cacheOperationProvider()
     {
         $operation = 'cache';