feat: introduce mappedQueuesFromIterable (#30)

Author: simPod

src/ds.php

@@ -6,6 +6,7 @@
 
 use Ds\Map;
 use Ds\Pair;
+use Ds\Queue;
 use Ds\Set;
 use Ds\Vector;
 
@@ -53,6 +54,37 @@ function mapFromIterable(iterable $iterable, callable $mapper): Map
     return $map;
 }
 
+/**
+ * @param iterable<K, V> $iterable
+ * @param callable(K, V): Pair<KReturn, VReturn> $mapper
+ *
+ * @return Map<KReturn, Queue<VReturn>>
+ *
+ * @template K
+ * @template V
+ * @template KReturn
+ * @template VReturn
+ */
+function mappedQueuesFromIterable(iterable $iterable, callable $mapper): Map
+{
+    /** @var Map<KReturn, Queue<VReturn>> $map */
+    $map = new Map();
+
+    foreach ($iterable as $key => $value) {
+        $keyValue = $mapper($key, $value);
+        $queue = $map->get($keyValue->key, null);
+        if ($queue === null) {
+            /** @var Queue<VReturn> $queue */
+            $queue = new Queue();
+            $map->put($keyValue->key, $queue);
+        }
+
+        $queue->push($keyValue->value);
+    }
+
+    return $map;
+}
+
 /**
  * @deprecated Use {@link mappedSetsFromIterable} instead
  *

tests/DsTest.php

@@ -11,11 +11,13 @@
 
 use function Cdn77\Functions\mapFromEntries;
 use function Cdn77\Functions\mapFromIterable;
+use function Cdn77\Functions\mappedQueuesFromIterable;
 use function Cdn77\Functions\mappedSetsFromIterable;
 use function Cdn77\Functions\setFromIterable;
 use function Cdn77\Functions\vectorFromIterable;
 
 #[CoversFunction('Cdn77\Functions\mapFromIterable')]
+#[CoversFunction('Cdn77\Functions\mappedQueuesFromIterable')]
 #[CoversFunction('Cdn77\Functions\mappedSetsFromIterable')]
 #[CoversFunction('Cdn77\Functions\setFromIterable')]
 #[CoversFunction('Cdn77\Functions\vectorFromIterable')]
@@ -53,6 +55,32 @@ public function testMapFromIterable(): void
         self::assertFalse($map->get(4));
     }
 
+    public function testMappedQueuesFromIterable(): void
+    {
+        /** @var callable():Generator<int, string> $iterableFactory */
+        $iterableFactory = static function (): Generator {
+            yield 1 => 'a';
+            yield 1 => 'b';
+            yield 2 => 'c';
+            yield 2 => 'd';
+        };
+
+        $map = mappedQueuesFromIterable(
+            $iterableFactory(),
+            static fn (int $key, string $value) => new Pair($key * 2, $value . '_')
+        );
+
+        self::assertCount(2, $map);
+
+        $queueAt2 = $map->get(2);
+        self::assertSame('a_', $queueAt2->pop());
+        self::assertSame('b_', $queueAt2->pop());
+
+        $queueAt4 = $map->get(4);
+        self::assertSame('c_', $queueAt4->pop());
+        self::assertSame('d_', $queueAt4->pop());
+    }
+
     public function testMappedSetsFromIterable(): void
     {
         /** @var callable():Generator<int, string> $iterableFactory */