Add Sequence::windows

docs/structures/sequence.md

@@ -295,6 +295,30 @@ $lines; // ['foo', 'bar', 'baz', '']
 
 This better accomodates to the case where the initial `Sequence` only contains a single value.
 
+### `->windows()`
+
+Returns a `Sequence` of all contigous windows of length `$size`. The windows overlap. If the `Sequence` is shorter than `$size`, an empty `Sequence` is returned.
+
+```php
+$sequence = Sequence::of('l', 'o', 'r', 'e', 'm');
+
+$windows = $sequence->windows(3);
+
+$actual = $windows
+    ->map(
+        fn($window) => $window->toList()
+    )
+    ->toList();
+
+$expected = [
+    ['l', 'o', 'r'],
+    ['o', 'r', 'e'],
+    ['r', 'e', 'm'],
+];
+
+assert($actual === $expected);
+```
+
 ### `->indices()`
 
 Create a new sequence of integers representing the indices of the original sequence.

proofs/sequence.php

@@ -97,4 +97,39 @@ static function($assert, $string, $chunk) {
             );
         },
     );
+
+    yield proof(
+        'Sequence::windows()',
+        given(
+            Set\Strings::atLeast(100),
+            Set\Integers::between(1, 50),
+        ),
+        static function($assert, $string, int $size) {
+            $chars = Str::of($string, Str\Encoding::ascii)
+                ->split();
+
+            $windows = $chars
+                ->windows($size);
+
+            $windows->foreach(
+                static fn($chars) => $assert
+                    ->same(
+                        $size,
+                        $chars->size()
+                    ),
+            );
+
+            if ($chars->size() < $size) {
+                $assert->same(
+                    0,
+                    $windows->count()
+                );
+            } else {
+                $assert->same(
+                    $chars->count() - $size + 1,
+                    $windows->count(),
+                );
+            }
+        },
+    );
 };

src/Sequence.php

@@ -758,6 +758,30 @@ public function chunk(int $size): self
             });
     }
 
+    /**
+     * Returns a `Sequence` of all contigous `Sequence` windows of length `$size` .
+     * The windows overlap. If the `Sequence` is shorter than `$size`, an empty `Sequence` is returned.
+     * 
+     * @param positive-int $size
+     *
+     * @return self<self<T>>
+     */
+    public function windows(int $size): self
+    {
+        /** @psalm-suppress MixedArgumentTypeCoercion */
+        return $this
+            ->map(static fn($value) => self::of($value))
+            ->aggregate(
+                static fn(self $a, $b) => match ($a->size()) {
+                    $size => self::of($a, $a->drop(1)->append($b)),
+                    default => self::of($a->append($b)),
+                }
+            )
+            ->filter(
+                static fn(self $sequence) => $sequence->size() === $size
+            );
+    }
+
     /**
      * Force to load all values into memory (only useful for deferred and lazy Sequence)
      *