feat: Add Words operation.

docs/pages/api.rst

@@ -1832,6 +1832,26 @@ Signature: ``Collection::window(int $size);``
         ->window(2)
         ->all(); // [ ['a'], ['a', 'b'], ['b', 'c'], ['c', 'd'], ... ]
 
+words
+~~~~~
+
+Get words from a string.
+
+Interface: `Wordsable`_
+
+Signature: ``Collection::words();``
+
+.. code-block:: php
+
+    $string = <<<'EOF'
+    The quick brow fox jumps over the lazy dog.
+
+    This is another sentence.
+    EOF;
+
+    Collection::fromString($string)
+        ->words()
+
 wrap
 ~~~~
 
@@ -1954,5 +1974,6 @@ Signature: ``Collection::zip(iterable ...$iterables);``
 .. _Unwrapable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Unwrapable.php
 .. _Unzipable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Unzipable.php
 .. _Windowable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Windowable.php
+.. _Wordsable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Wordsable.php
 .. _Wrapable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Wrapable.php
 .. _Zipable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Zipable.php

spec/loophp/collection/CollectionSpec.php

@@ -2647,6 +2647,35 @@ public function it_can_window(): void
             ]);
     }
 
+    public function it_can_words(): void
+    {
+        $string = <<<'EOF'
+The quick brow fox jumps over the lazy dog.
+
+This is another sentence.
+EOF;
+
+        $words = [
+            0 => 'The',
+            1 => 'quick',
+            2 => 'brow',
+            3 => 'fox',
+            4 => 'jumps',
+            5 => 'over',
+            6 => 'the',
+            7 => 'lazy',
+            8 => 'dog.',
+            10 => 'This',
+            11 => 'is',
+            12 => 'another',
+            13 => 'sentence.',
+        ];
+
+        $this::fromString($string)
+            ->words()
+            ->shouldIterateAs($words);
+    }
+
     public function it_can_wrap()
     {
         $this::fromIterable(['a' => 'A', 'b' => 'B', 'c' => 'C'])

src/Collection.php

@@ -103,6 +103,7 @@
 use loophp\collection\Operation\Unwrap;
 use loophp\collection\Operation\Unzip;
 use loophp\collection\Operation\Window;
+use loophp\collection\Operation\Words;
 use loophp\collection\Operation\Wrap;
 use loophp\collection\Operation\Zip;
 use Psr\Cache\CacheItemPoolInterface;
@@ -813,6 +814,11 @@ public static function with($data = [], ...$parameters): Collection
         return new self($data, ...$parameters);
     }
 
+    public function words(): CollectionInterface
+    {
+        return $this->run(Words::of());
+    }
+
     public function wrap(): CollectionInterface
     {
         return $this->run(Wrap::of());

src/Contract/Collection.php

@@ -96,6 +96,7 @@
 use loophp\collection\Contract\Operation\Unwrapable;
 use loophp\collection\Contract\Operation\Unzipable;
 use loophp\collection\Contract\Operation\Windowable;
+use loophp\collection\Contract\Operation\Wordsable;
 use loophp\collection\Contract\Operation\Wrapable;
 use loophp\collection\Contract\Operation\Zipable;
 use loophp\collection\Iterator\ClosureIterator;
@@ -187,6 +188,7 @@
  * @template-extends Unwrapable<TKey, T>
  * @template-extends Unzipable<TKey, T>
  * @template-extends Windowable<TKey, T>
+ * @template-extends Wordsable<TKey, T>
  * @template-extends Wrapable<TKey, T>
  * @template-extends Zipable<TKey, T>
  * @template-extends IteratorAggregate<TKey, T>
@@ -284,6 +286,7 @@ interface Collection extends
     Unwrapable,
     Unzipable,
     Windowable,
+    Wordsable,
     Wrapable,
     Zipable
 {

src/Contract/Operation/Wordsable.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 Wordsable
+{
+    /**
+     * @psalm-return \loophp\collection\Contract\Collection<TKey, T>
+     */
+    public function words(): Collection;
+}

src/Operation/Words.php

@@ -0,0 +1,49 @@
+<?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
+ *
+ * phpcs:disable Generic.WhiteSpace.ScopeIndent.IncorrectExact
+ */
+final class Words extends AbstractOperation
+{
+    /**
+     * @psalm-return Closure(Iterator<TKey, T>): Generator<TKey, string, mixed, void>
+     */
+    public function __invoke(): Closure
+    {
+        return
+            /**
+             * @psalm-param Iterator<TKey, string> $iterator
+             *
+             * @psalm-return Generator<TKey, string, mixed, void>
+             */
+            static function (Iterator $iterator): Generator {
+                $mapCallback = static function (array $value): string {
+                    return implode('', $value);
+                };
+
+                /** @psalm-var callable(Iterator<TKey, T>): Generator<TKey, T> $explode */
+                $explode = Explode::of()("\t", "\n", ' ');
+                /** @psalm-var callable(Iterator<TKey, T>): Generator<TKey, string> $map */
+                $map = Map::of()($mapCallback);
+                /** @psalm-var callable(Iterator<TKey, T>): Generator<TKey, string> $compact */
+                $compact = Compact::of()();
+
+                /** @psalm-var callable(Iterator<TKey, string>): Generator<TKey, string> $compose */
+                $compose = Compose::of()($explode, $map, $compact);
+
+                return yield from $compose($iterator);
+            };
+    }
+}