feat: Add Inits operation.

docs/pages/api.rst

@@ -846,6 +846,20 @@ Signature: ``Collection::init();``
     Collection::fromIterable(range('a', 'e'))
         ->init(); // ['a', 'b', 'c', 'd']
 
+inits
+~~~~~
+
+Returns all initial segments of the collection, shortest first.
+
+Interface: `Initsable`_
+
+Signature: ``Collection::inits();``
+
+.. code-block:: php
+
+    Collection::fromIterable(range('a', 'c'))
+        ->inits(); // [[], ['a'], ['a', 'b'], ['a', 'b', 'c']]
+
 intersect
 ~~~~~~~~~
 
@@ -1957,6 +1971,7 @@ Signature: ``Collection::zip(iterable ...$iterables);``
 .. _IfThenElseable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/IfThenElseable.php
 .. _Implodeable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Implodeable.php
 .. _Initable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Initable.php
+.. _Initsable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Initsable.php
 .. _Intersectable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Intersectable.php
 .. _Intersectkeysable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Intersectkeysable.php
 .. _Intersperseable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Intersperseable.php

spec/loophp/collection/CollectionSpec.php

@@ -1144,6 +1144,18 @@ public function it_can_init(): void
             ]);
     }
 
+    public function it_can_inits(): void
+    {
+        $this::fromIterable(range('a', 'c'))
+            ->inits()
+            ->shouldIterateAs([
+                [],
+                ['a'],
+                ['a', 'b'],
+                ['a', 'b', 'c'],
+            ]);
+    }
+
     public function it_can_intersect(): void
     {
         $this::fromIterable(range(1, 5))

src/Collection.php

@@ -52,6 +52,7 @@
 use loophp\collection\Operation\IfThenElse;
 use loophp\collection\Operation\Implode;
 use loophp\collection\Operation\Init;
+use loophp\collection\Operation\Inits;
 use loophp\collection\Operation\Intersect;
 use loophp\collection\Operation\IntersectKeys;
 use loophp\collection\Operation\Intersperse;
@@ -551,6 +552,11 @@ public function init(): CollectionInterface
         return $this->run(Init::of());
     }
 
+    public function inits(): CollectionInterface
+    {
+        return $this->run(Inits::of());
+    }
+
     public function intersect(...$values): CollectionInterface
     {
         return $this->run(Intersect::of()(...$values));

src/Contract/Collection.php

@@ -46,6 +46,7 @@
 use loophp\collection\Contract\Operation\IfThenElseable;
 use loophp\collection\Contract\Operation\Implodeable;
 use loophp\collection\Contract\Operation\Initable;
+use loophp\collection\Contract\Operation\Initsable;
 use loophp\collection\Contract\Operation\Intersectable;
 use loophp\collection\Contract\Operation\Intersectkeysable;
 use loophp\collection\Contract\Operation\Intersperseable;
@@ -146,6 +147,7 @@
  * @template-extends Headable<TKey, T>
  * @template-extends IfThenElseable<TKey, T>
  * @template-extends Initable<TKey, T>
+ * @template-extends Initsable<TKey, T>
  * @template-extends Intersectable<TKey, T>
  * @template-extends Intersectkeysable<TKey, T>
  * @template-extends Intersperseable<TKey, T>
@@ -240,6 +242,7 @@ interface Collection extends
     IfThenElseable,
     Implodeable,
     Initable,
+    Initsable,
     Intersectable,
     Intersectkeysable,
     Intersperseable,

src/Contract/Operation/Initsable.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace loophp\collection\Contract\Operation;
+
+use loophp\collection\Contract\Collection;
+
+/**
+ * @psalm-template TKey
+ * @psalm-template TKey of array-key
+ * @psalm-template T
+ */
+interface Initsable
+{
+    /**
+     * @psalm-return \loophp\collection\Contract\Collection<TKey, T>
+     */
+    public function inits(): Collection;
+}

src/Operation/Inits.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace loophp\collection\Operation;
+
+use Closure;
+use Generator;
+use Iterator;
+
+/**
+ * @psalm-template TKey
+ * @psalm-template TKey of array-key
+ * @psalm-template T
+ */
+final class Inits extends AbstractOperation
+{
+    /**
+     * @psalm-return Closure(Iterator<TKey, T>): Generator<int, list<T>>
+     */
+    public function __invoke(): Closure
+    {
+        $scanLeftCallback =
+            /**
+             * @psalm-param array<TKey, T> $carry
+             * @psalm-param T $value
+             * @psalm-param TKey $key
+             * @psalm-param Iterator<TKey, T> $iterator
+             *
+             * @psalm-return array<TKey, T>
+             *
+             * @param mixed $value
+             * @param mixed $key
+             */
+            static function (array $carry, $value, $key, Iterator $iterator): array {
+                $carry[$key] = $value;
+
+                return $carry;
+            };
+
+        /** @psalm-var Closure(Iterator<TKey, T>): Generator<int, list<T>> $inits */
+        $inits = Compose::of()(
+            ScanLeft::of()($scanLeftCallback)([]),
+            Normalize::of()
+        );
+
+        // Point free style.
+        return $inits;
+    }
+}