Add Init operation.

README.md

@@ -59,6 +59,7 @@ This library has been inspired by:
 * [Collect.js][collect.js]
 * [nikic/iter][nikic/iter package]
 * [Lazy.js][lazy.js]
+* [Haskell][haskell]
 
 ## Installation
 
@@ -169,4 +170,5 @@ For more detailed changelogs, please check [the release changelogs][changelog-re
 [phpstorm annotated august 2020]: https://blog.jetbrains.com/phpstorm/2020/08/php-annotated-august-2020/
 [changelog-md]: https://github.com/loophp/collection/blob/master/CHANGELOG.md
 [git-commits]: https://github.com/loophp/collection/commits/master
-[changelog-releases]: https://github.com/loophp/collection/releases
+[changelog-releases]: https://github.com/loophp/collection/releases
+[haskell]: https://www.haskell.org/

docs/pages/api.rst

@@ -713,6 +713,20 @@ implode
 
 Interface: `Implodeable`_
 
+init
+~~~~
+
+Returns the collection without its last item.
+
+Interface: `Initable`_
+
+Signature: ``Collection::init();``
+
+.. code-block:: php
+
+    Collection::with(range('a', 'e'))
+        ->init(); // ['a', 'b', 'c', 'd']
+
 intersect
 ~~~~~~~~~
 
@@ -1528,6 +1542,7 @@ Signature: ``Collection::zip(iterable ...$iterables);``
 .. _Headable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Headable.php
 .. _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
 .. _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

@@ -1036,6 +1036,18 @@ public function it_can_implode(): void
             ->shouldReturn('ABC');
     }
 
+    public function it_can_init(): void
+    {
+        $this::fromIterable(range(0, 4))
+            ->init()
+            ->shouldIterateAs([
+                0 => 0,
+                1 => 1,
+                2 => 2,
+                3 => 3,
+            ]);
+    }
+
     public function it_can_intersect(): void
     {
         $this::fromIterable(range(1, 5))

src/Collection.php

@@ -44,6 +44,7 @@
 use loophp\collection\Operation\Head;
 use loophp\collection\Operation\IfThenElse;
 use loophp\collection\Operation\Implode;
+use loophp\collection\Operation\Init;
 use loophp\collection\Operation\Intersect;
 use loophp\collection\Operation\IntersectKeys;
 use loophp\collection\Operation\Intersperse;
@@ -462,6 +463,11 @@ public function implode(string $glue = ''): string
         return $this->run(Implode::of()($glue))->getIterator()->current();
     }
 
+    public function init(): CollectionInterface
+    {
+        return $this->run(Init::of());
+    }
+
     public function intersect(...$values): CollectionInterface
     {
         return $this->run(Intersect::of()(...$values));

src/Contract/Collection.php

@@ -38,6 +38,7 @@
 use loophp\collection\Contract\Operation\Headable;
 use loophp\collection\Contract\Operation\IfThenElseable;
 use loophp\collection\Contract\Operation\Implodeable;
+use loophp\collection\Contract\Operation\Initable;
 use loophp\collection\Contract\Operation\Intersectable;
 use loophp\collection\Contract\Operation\Intersectkeysable;
 use loophp\collection\Contract\Operation\Intersperseable;
@@ -120,6 +121,7 @@
  * @template-extends Hasable<TKey, T>
  * @template-extends Headable<TKey, T>
  * @template-extends IfThenElseable<TKey, T>
+ * @template-extends Initable<TKey, T>
  * @template-extends Intersectable<TKey, T>
  * @template-extends Intersectkeysable<TKey, T>
  * @template-extends Intersperseable<TKey, T>
@@ -195,6 +197,7 @@ interface Collection extends
     Headable,
     IfThenElseable,
     Implodeable,
+    Initable,
     Intersectable,
     Intersectkeysable,
     Intersperseable,

src/Contract/Operation/Initable.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 Initable
+{
+    /**
+     * @psalm-return static<TKey, T>
+     */
+    public function init(): Collection;
+}

src/Operation/Init.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace loophp\collection\Operation;
+
+use CachingIterator;
+use Closure;
+use Generator;
+use Iterator;
+
+/**
+ * @psalm-template TKey
+ * @psalm-template TKey of array-key
+ * @psalm-template T
+ */
+final class Init extends AbstractOperation
+{
+    /**
+     * @psalm-return Closure(Iterator<TKey, T>): Generator<TKey, T>
+     */
+    public function __invoke(): Closure
+    {
+        return
+            /**
+             * @psalm-param Iterator<TKey, T> $iterator
+             *
+             * @psalm-return Generator<TKey, T>
+             */
+            static function (Iterator $iterator): Generator {
+                $cacheIterator = new CachingIterator($iterator);
+                $cacheIterator->next();
+
+                for (; $iterator->valid(); $cacheIterator->next()) {
+                    yield $cacheIterator->key() => $cacheIterator->current();
+                }
+            };
+    }
+}