feat: add SortIterableAggregate and SortIterator

src/SortIterableAggregate.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace loophp\iterators;
+
+use Closure;
+use Generator;
+use IteratorAggregate;
+
+/**
+ * @template TKey
+ * @template T
+ *
+ * @implements IteratorAggregate<int, T>
+ */
+final class SortIterableAggregate implements IteratorAggregate
+{
+    /**
+     * @param iterable<TKey, T> $iterable
+     * @param (Closure(T, T): int) $callback
+     */
+    public function __construct(private iterable $iterable, private Closure $callback) {}
+
+    /**
+     * @return Generator<int, T>
+     */
+    public function getIterator(): Generator
+    {
+        yield from new SortIterator($this->iterable, $this->callback);
+    }
+}

src/SortIterator.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace loophp\iterators;
+
+use Closure;
+use SplHeap;
+
+/**
+ * @template TKey
+ * @template T
+ *
+ * @extends SplHeap<T>
+ */
+final class SortIterator extends SplHeap
+{
+    /**
+     * @param iterable<TKey, T> $iterable
+     * @param Closure(T, T): int $callback
+     */
+    public function __construct(private iterable $iterable, private Closure $callback)
+    {
+        foreach ($iterable as $value) {
+            $this->insert($value);
+        }
+    }
+
+    /**
+     * @param T $left
+     * @param T $right
+     */
+    public function compare($left, $right): int
+    {
+        return ($this->callback)($left, $right);
+    }
+}

tests/unit/SortIterableAggregateTest.php

@@ -0,0 +1,51 @@
+<?php
+
+/**
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace tests\loophp\iterators;
+
+use loophp\iterators\SortIterableAggregate;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ *
+ * @coversDefaultClass \loophp\iterators
+ */
+final class SortIterableAggregateTest extends TestCase
+{
+    public function testDoNothing(): void
+    {
+        $input = ['a', 'b', 'c', 'd', 'e', 'f'];
+
+        $iterator = (new SortIterableAggregate($input, static fn ($right, $left): int => $left <=> $right));
+
+        $expected = [];
+
+        foreach ($iterator as $value) {
+            $expected[] = $value;
+        }
+
+        self::assertSame($expected, $input);
+    }
+
+    public function testSimpleSort(): void
+    {
+        $input = array_combine(range('c', 'a'), range('c', 'a'));
+
+        $iterator = (new SortIterableAggregate($input, static fn ($right, $left): int => $left <=> $right));
+
+        $expected = [];
+
+        foreach ($iterator as $value) {
+            $expected[] = $value;
+        }
+
+        self::assertSame($expected, range('a', 'c'));
+    }
+}