add iterable_combinations function

Author: lrhoek

README.md

@@ -37,6 +37,32 @@ $subsets = $items
 
 ## Functions
 
+### `iterable_combinations(int $n)`
+
+Yield all subsets of **exactly** size `$n` from an iterable. Output is lazy; input is materialized into an array first.
+
+- Preserves the original keys in each subset.
+- Yields `C(count(items), n)` combinations (binomial coefficient).
+- For `$n = 0`, yields the empty subset only: `[[]]`.
+- Throws `InvalidArgumentException` if `$n < 0`.
+
+```php
+use Anarchitecture\combinatorics as c;
+use Anarchitecture\pipe as p;
+
+$items = ['a' => 1, 'b' => 2, 'c' => 3];
+
+$pairs = $items
+    |> c\iterable_combinations(2)
+    |> p\collect(...);
+
+// [
+//   ['b' => 2, 'c' => 3],
+//   ['a' => 1, 'c' => 3],
+//   ['a' => 1, 'b' => 2],
+// ]
+```
+
 ### `iterable_powerset()`
 
 Yield all subsets (the power set) of an iterable. Output is lazy; input is materialized into an array first.

src/combinatorics.php

@@ -52,6 +52,55 @@ function iterable_allocations(int $total): Closure {
     };
 }
 
+/**
+ * Yield all combinations (subsets) of size $n from the given items (lazy).
+ *
+ * Preserves original keys.
+ *
+ * @throws InvalidArgumentException
+ * @return Closure(iterable<array-key, mixed>, int): iterable<array-key, array<array-key, mixed>>
+ */
+function iterable_combinations(int $n): Closure {
+
+    if ($n < 0) {
+        throw new InvalidArgumentException("iterable_combinations_n: n must be >= 0");
+    }
+
+    return static function (iterable $items) use ($n): Generator {
+
+        $items = \is_array($items) ? $items : \iterator_to_array($items, true);
+
+        $iterable_combinations = static function (array $items, int $n) use (&$iterable_combinations): Generator {
+
+            if ($n === 0) {
+                yield [];
+                return;
+            }
+
+            if ($items === [] || $n > \count($items)) {
+                return;
+            }
+
+            $k = \array_key_first($items);
+            $v = $items[$k];
+            unset($items[$k]);
+
+            /** @var array<array-key, mixed> $subset */
+            foreach ($iterable_combinations($items, $n) as $subset) {
+                yield $subset;
+            }
+
+            /** @var array<array-key, mixed> $subset */
+            foreach ($iterable_combinations($items, $n - 1) as $subset) {
+                yield [$k => $v] + $subset;
+            }
+        };
+
+        yield from $iterable_combinations($items, $n);
+    };
+}
+
+
 /**
  * Generate (lazy) permutation of iterable (consumed)
  *
@@ -97,7 +146,7 @@ function iterable_powerset() : Closure {
 
         $items = \is_array($items) ? $items : \iterator_to_array($items, true);
 
-        $gen = static function (array $items) use (&$gen): Generator {
+        $iterable_powerset = static function (array $items) use (&$iterable_powerset): Generator {
 
             if ($items === []) {
                 yield [];
@@ -109,12 +158,12 @@ function iterable_powerset() : Closure {
             unset($items[$k]);
 
             /** @var array<array-key, mixed> $subset */
-            foreach ($gen($items) as $subset) {
+            foreach ($iterable_powerset($items) as $subset) {
                 yield $subset;
                 yield [$k => $v] + $subset;
             }
         };
 
-        yield from $gen($items);
+        yield from $iterable_powerset($items);
     };
 }

tests/IterableCombinationsTest.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Anarchitecture\combinatorics\Tests;
+
+use Generator;
+use InvalidArgumentException;
+use PHPUnit\Framework\TestCase;
+
+use Anarchitecture\pipe as p;
+
+use function Anarchitecture\combinatorics\iterable_combinations;
+
+final class IterableCombinationsTest extends TestCase
+{
+    public function testItThrowsWhenNIsNegative() : void {
+
+        $this->expectException(InvalidArgumentException::class);
+
+        iterable_combinations(-1);
+    }
+
+    public function testNZeroYieldsOneEmptyCombination() : void {
+
+        $result = ['a' => 1, 'b' => 2]
+            |> iterable_combinations(0)
+            |> p\collect(...);
+
+        self::assertSame([[]], $result);
+    }
+
+    public function testEmptyInputNZeroYieldsOneEmptyCombination() : void {
+
+        $result = []
+            |> iterable_combinations(0)
+            |> p\collect(...);
+
+        self::assertSame([[]], $result);
+    }
+
+    public function testEmptyInputNPositiveYieldsNothing() : void {
+
+        $result = []
+            |> iterable_combinations(2)
+            |> p\collect(...);
+
+        self::assertSame([], $result);
+    }
+
+    public function testNGreaterThanCountYieldsNothing() : void {
+
+        $result = ['a' => 1, 'b' => 2]
+            |> iterable_combinations(3)
+            |> p\collect(...);
+
+        self::assertSame([], $result);
+    }
+
+    public function testTwoOfThreePreservesKeysAndExpectedOrder() : void {
+
+        $items = ['a' => 1, 'b' => 2, 'c' => 3];
+
+        $result = $items
+            |> iterable_combinations(2)
+            |> p\collect(...);
+
+        self::assertContains(['b' => 2, 'c' => 3], $result);
+        self::assertContains(['a' => 1, 'c' => 3], $result);
+        self::assertContains(['a' => 1, 'b' => 2], $result);
+    }
+
+    public function testItWorksWithGeneratorInputAndPreservesKeys() : void {
+
+        $items = static function (): Generator {
+            yield 'x' => 10;
+            yield 'y' => 20;
+            yield 'z' => 30;
+        };
+
+        $result = $items()
+            |> iterable_combinations(2)
+            |> p\collect(...);
+
+        self::assertContains(['y' => 20, 'z' => 30], $result);
+        self::assertContains(['x' => 10, 'z' => 30], $result);
+        self::assertContains(['x' => 10, 'y' => 20], $result);
+    }
+
+    public function testCountMatchesBinomialCoefficient() : void {
+
+        $items = ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5];
+
+        $result = $items
+            |> iterable_combinations(3)
+            |> p\collect(...);
+
+        self::assertCount(10, $result);
+    }
+}