Document List.combinations

lib/List.pod

@@ -375,4 +375,52 @@ Example:
     @foo.unshift: 1, 3 ... 11;
     say @foo;                   # 1 3 5 7 9 11 a b c
 
+=head2 combinations
+
+    multi method combinations (List:D: Int:D $of)          returns List:D
+    multi method combinations (List:D: Range:D $of = 0..*) returns List:D
+    multi sub    combinations ($n, $k)                     returns List:D
+
+The C<Int> variant teturns all C<$of>-combinations of the invocant list.
+For example
+
+    say .join('|') for <a b c>.combinations(2);
+
+prints
+
+    a|b
+    a|c
+    b|c
+
+because all the 2-combinations of C<'a', 'b', 'c'> are
+C<['a', 'b'], ['a', 'c'], ['b', 'c']>.
+
+The C<Range> variant combines all the individual combinations into a single
+list, so
+
+    say .join('|') for <a b c>.combinations(2..3);
+
+prints
+
+    a|b
+    a|c
+    b|c
+    a|b|c
+
+because that's the list of all 2- and 3-combinations.
+
+The subroutine form C<combinations($n, $k)> is equivalent to
+C<(^$n).combinations($k)>, so
+
+    .say for combinations(4, 2)
+
+prints
+
+    0 1
+    0 2
+    0 3
+    1 2
+    1 3
+    2 3
+
 =end pod