Merge pull request #21 from Innmind/sequence-prepend

Add `Sequence::prepend()`

Author: Baptouuuu

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+- `Innmind\Immutable\Sequence::prepend()`
+
 ## 5.6.0 - 2024-06-15
 
 ### Added

docs/structures/sequence.md

@@ -104,6 +104,15 @@ $sequence = Sequence::ints(1, 2)->append(Sequence::ints(3, 4));
 $sequence->equals(Sequence::ints(1, 2, 3, 4)); // true
 ```
 
+### `->prepend()`
+
+This is similar to `->append()` except the order is switched.
+
+!!! success ""
+    The main advantage of this method is when using lazy sequences. If you want to add elements at the beginning of a sequence but the rest may be lazy then you need to create a lazy sequence with your values and then append the other lazy sequence; but this reveals the underlying lazyness of the call and you need to be aware that it could be lazy.
+
+    Instead by using this method you no longer have to be aware that the other sequence is lazy or not.
+
 ## Access values
 
 ### `->size()` :material-memory-arrow-down:

proofs/sequence.php

@@ -2,6 +2,7 @@
 declare(strict_types = 1);
 
 use Innmind\Immutable\Sequence;
+use Innmind\BlackBox\Set;
 
 return static function() {
     yield test(
@@ -15,4 +16,42 @@ static function($assert) {
             );
         },
     );
+
+    yield proof(
+        'Sequence::prepend()',
+        given(
+            Set\Sequence::of(Set\Type::any()),
+            Set\Sequence::of(Set\Type::any()),
+        ),
+        static function($assert, $first, $second) {
+            $assert->same(
+                [...$first, ...$second],
+                Sequence::of(...$second)
+                    ->prepend(Sequence::of(...$first))
+                    ->toList(),
+            );
+
+            $assert->same(
+                [...$first, ...$second],
+                Sequence::defer((static function() use ($second) {
+                    yield from $second;
+                })())
+                    ->prepend(Sequence::defer((static function() use ($first) {
+                        yield from $first;
+                    })()))
+                    ->toList(),
+            );
+
+            $assert->same(
+                [...$first, ...$second],
+                Sequence::lazy(static function() use ($second) {
+                    yield from $second;
+                })
+                    ->prepend(Sequence::lazy(static function() use ($first) {
+                        yield from $first;
+                    }))
+                    ->toList(),
+            );
+        },
+    );
 };

src/Sequence.php

@@ -489,6 +489,20 @@ public function append(self $sequence): self
         ));
     }
 
+    /**
+     * Prepend the given sequence to the current one
+     *
+     * @param self<T> $sequence
+     *
+     * @return self<T>
+     */
+    public function prepend(self $sequence): self
+    {
+        return new self($this->implementation->prepend(
+            $sequence->implementation,
+        ));
+    }
+
     /**
      * Return a sequence with all elements from the current one that exist
      * in the given one

src/Sequence/Defer.php

@@ -483,6 +483,29 @@ public function append(Implementation $sequence): Implementation
         );
     }
 
+    /**
+     * @param Implementation<T> $sequence
+     *
+     * @return Implementation<T>
+     */
+    public function prepend(Implementation $sequence): Implementation
+    {
+        /** @psalm-suppress ImpureFunctionCall */
+        return new self(
+            (static function(\Iterator $values, Implementation $sequence): \Generator {
+                /** @var T $value */
+                foreach ($sequence->iterator() as $value) {
+                    yield $value;
+                }
+
+                /** @var T $value */
+                foreach ($values as $value) {
+                    yield $value;
+                }
+            })($this->values, $sequence),
+        );
+    }
+
     /**
      * @param Implementation<T> $sequence
      *

src/Sequence/Implementation.php

@@ -228,6 +228,15 @@ public function takeEnd(int $size): self;
      */
     public function append(self $sequence): self;
 
+    /**
+     * Prepend the given sequence to the current one
+     *
+     * @param self<T> $sequence
+     *
+     * @return self<T>
+     */
+    public function prepend(self $sequence): self;
+
     /**
      * Return a sequence with all elements from the current one that exist
      * in the given one

src/Sequence/Lazy.php

@@ -517,6 +517,31 @@ static function(RegisterCleanup $registerCleanup) use ($values, $sequence): \Gen
         );
     }
 
+    /**
+     * @param Implementation<T> $sequence
+     *
+     * @return Implementation<T>
+     */
+    public function prepend(Implementation $sequence): Implementation
+    {
+        $values = $this->values;
+
+        return new self(
+            static function(RegisterCleanup $registerCleanup) use ($values, $sequence): \Generator {
+                /** @var \Iterator<int, T> */
+                $generator = self::open($sequence, $registerCleanup);
+
+                foreach ($generator as $value) {
+                    yield $value;
+                }
+
+                foreach ($values($registerCleanup) as $value) {
+                    yield $value;
+                }
+            },
+        );
+    }
+
     /**
      * @param Implementation<T> $sequence
      *

src/Sequence/Primitive.php

@@ -363,6 +363,22 @@ public function append(Implementation $sequence): self
         return new self(\array_merge($this->values, $other));
     }
 
+    /**
+     * @param Implementation<T> $sequence
+     *
+     * @return self<T>
+     */
+    public function prepend(Implementation $sequence): self
+    {
+        $other = [];
+
+        foreach ($sequence->iterator() as $value) {
+            $other[] = $value;
+        }
+
+        return new self(\array_merge($other, $this->values));
+    }
+
     /**
      * @param Implementation<T> $sequence
      *