feat: Add Unwords operation.

docs/pages/api.rst

@@ -1753,6 +1753,35 @@ Signature: ``Collection::unwindow();``
         ->drop(1)
         ->normalize(); // [10, 11, 12, 13, 14, 15, 16, 17, 18]
 
+unwords
+~~~~~~~
+
+Create a string from words.
+
+Interface: `Unwordsable`_
+
+Signature: ``Collection::unwords();``
+
+.. code-block:: php
+
+    $words = [
+        'The',
+        'quick',
+        'brow',
+        'fox',
+        'jumps',
+        'over',
+        'the',
+        'lazy',
+        "dog.\n\nThis",
+        'is',
+        'another',
+        'sentence.',
+    ];
+
+    Collection::fromIterable($words)
+        ->unwords();
+
 unwrap
 ~~~~~~
 
@@ -1921,6 +1950,7 @@ Signature: ``Collection::zip(iterable ...$iterables);``
 .. _Unpairable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Unpairable.php
 .. _Untilable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Untilable.php
 .. _Unwindowable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Unwindowable.php
+.. _Unwordsable: https://github.com/loophp/collection/blob/master/src/Contract/Operation/Unwordsable.php
 .. _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

spec/loophp/collection/CollectionSpec.php

@@ -2328,6 +2328,34 @@ public function it_can_unwindow(): void
             ->shouldIterateAs(range('a', 'z'));
     }
 
+    public function it_can_unwords(): void
+    {
+        $string = <<<'EOF'
+The quick brow fox jumps over the lazy dog.
+
+This is another sentence.
+EOF;
+
+        $words = [
+            'The',
+            'quick',
+            'brow',
+            'fox',
+            'jumps',
+            'over',
+            'the',
+            'lazy',
+            "dog.\n\nThis",
+            'is',
+            'another',
+            'sentence.',
+        ];
+
+        $this::fromIterable($words)
+            ->unwords()
+            ->shouldIterateAs([11 => $string]);
+    }
+
     public function it_can_unwrap()
     {
         $this::fromIterable([['a' => 'A'], ['b' => 'B'], ['c' => 'C']])

src/Collection.php

@@ -99,6 +99,7 @@
 use loophp\collection\Operation\Unpair;
 use loophp\collection\Operation\Until;
 use loophp\collection\Operation\Unwindow;
+use loophp\collection\Operation\Unwords;
 use loophp\collection\Operation\Unwrap;
 use loophp\collection\Operation\Unzip;
 use loophp\collection\Operation\Window;
@@ -787,6 +788,11 @@ public function unwindow(): CollectionInterface
         return $this->run(Unwindow::of());
     }
 
+    public function unwords(): CollectionInterface
+    {
+        return $this->run(Unwords::of());
+    }
+
     public function unwrap(): CollectionInterface
     {
         return $this->run(Unwrap::of());

src/Contract/Collection.php

@@ -92,6 +92,7 @@
 use loophp\collection\Contract\Operation\Unpairable;
 use loophp\collection\Contract\Operation\Untilable;
 use loophp\collection\Contract\Operation\Unwindowable;
+use loophp\collection\Contract\Operation\Unwordsable;
 use loophp\collection\Contract\Operation\Unwrapable;
 use loophp\collection\Contract\Operation\Unzipable;
 use loophp\collection\Contract\Operation\Windowable;
@@ -182,6 +183,7 @@
  * @template-extends Unpairable<TKey, T>
  * @template-extends Untilable<TKey, T>
  * @template-extends Unwindowable<TKey, T>
+ * @template-extends Unwordsable<TKey, T>
  * @template-extends Unwrapable<TKey, T>
  * @template-extends Unzipable<TKey, T>
  * @template-extends Windowable<TKey, T>
@@ -278,6 +280,7 @@ interface Collection extends
     Unpairable,
     Untilable,
     Unwindowable,
+    Unwordsable,
     Unwrapable,
     Unzipable,
     Windowable,

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

src/Operation/Unwords.php

@@ -0,0 +1,37 @@
+<?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 Unwords extends AbstractOperation
+{
+    /**
+     * @psalm-return Closure(Iterator<TKey, T|string>): Generator<TKey, T|string, mixed, void>
+     */
+    public function __invoke(): Closure
+    {
+        /**
+         * @psalm-param Iterator<TKey, T|string> $iterator
+         *
+         * @psalm-return Generator<TKey, string>
+         */
+        return static function (Iterator $iterator): Generator {
+            /** @psalm-var callable(Iterator<TKey, T|string>): Generator<TKey, string> $implode */
+            $implode = Implode::of()(' ');
+
+            return $implode($iterator);
+        };
+    }
+}