[Stream] Add sorted fork-operation.

Author: whsv26

src/Fp/Streams/Stream.php

@@ -41,6 +41,7 @@
 use Fp\Operations\ReduceOperation;
 use Fp\Operations\RepeatNOperation;
 use Fp\Operations\RepeatOperation;
+use Fp\Operations\SortedOperation;
 use Fp\Operations\TailOperation;
 use Fp\Operations\TakeOperation;
 use Fp\Operations\TakeWhileOperation;
@@ -476,6 +477,16 @@ public function groupAdjacentBy(callable $discriminator): Stream
         }));
     }
 
+    /**
+     * @inheritDoc
+     * @psalm-param callable(TV, TV): int $cmp
+     * @psalm-return self<TV>
+     */
+    public function sorted(callable $cmp): self
+    {
+        return $this->fork(SortedOperation::of($this->emitter)($cmp));
+    }
+
     /**
      * @inheritDoc
      * @psalm-param callable(TV): bool $predicate

src/Fp/Streams/StreamChainableOps.php

@@ -323,4 +323,20 @@ public function chunks(int $size): Stream;
      * @return Stream<array{D, Seq<TV>}>
      */
     public function groupAdjacentBy(callable $discriminator): Stream;
+
+    /**
+     * Sort streamed elements
+     *
+     * ```php
+     * >>> Stream::emits([2, 1, 3])->sorted(fn($lhs, $rhs) => $lhs - $rhs)->toArray();
+     * => [1, 2, 3]
+     *
+     * >>> Stream::emits([2, 1, 3])->sorted(fn($lhs, $rhs) => $rhs - $lhs)->toArray();
+     * => [3, 2, 1]
+     * ```
+     *
+     * @psalm-param callable(TV, TV): int $cmp
+     * @psalm-return Stream<TV>
+     */
+    public function sorted(callable $cmp): Stream;
 }

tests/Runtime/Classes/Stream/StreamOpsTest.php

@@ -243,4 +243,17 @@ public function testMkString(): void
         $this->assertEquals('(0,1,2)', Stream::emits([0, 1, 2])->mkString('(', ',', ')'));
         $this->assertEquals('()', Stream::emits([])->mkString('(', ',', ')'));
     }
+
+    public function testSorted(): void
+    {
+        $this->assertEquals(
+            [1, 2, 3],
+            Stream::emits([1, 3, 2])->sorted(fn($lhs, $rhs) => $lhs - $rhs)->toArray()
+        );
+
+        $this->assertEquals(
+            [3, 2, 1],
+            Stream::emits([1, 3, 2])->sorted(fn($lhs, $rhs) => $rhs - $lhs)->toArray()
+        );
+    }
 }