Documentation for routine combinations

Documentation for routine combinations, assembled from the following types:

class Any

From Any

(Any) method combinations

Defined As:

    method combinations(--> TODO)

TODO

class List

From List

(List) routine combinations

Defined as:

multi sub    combinations($n$k                     --> Seq:D)
multi method combinations(List:D: Int:D $of          --> Seq:D)
multi method combinations(List:D: Range:D $of = 0..* --> Seq:D)

The Int variant returns all $of-combinations of the invocant list. For example

say .join('|'for <a b c>.combinations(2);
# OUTPUT: «a|b␤ 
# a|c␤ 
# b|c␤» 

because all the 2-combinations of 'a', 'b', 'c' are ['a', 'b'], ['a', 'c'], ['b', 'c'].

The Range variant combines all the individual combinations into a single list, so

say .join('|'for <a b c>.combinations(2..3);
# OUTPUT: «a|b 
# a|c␤ 
# b|c␤ 
# a|b|c␤» 

because that's the list of all 2- and 3-combinations.

The subroutine form combinations($n, $k) is equivalent to (^$n).combinations($k), so

.say for combinations(42)
# OUTPUT: «0 1 
# 0 2␤ 
# 0 3␤ 
# 1 2␤ 
# 1 3␤ 
# 2 3␤» 

If $k is negative or is larger than there are items in the given list, an empty list will be returned. If $k is zero, a 1-item list containing an empty list will be returned (there's exactly 1 way to pick no items).

Note: some implementations may limit the maximum $n. On Rakudo, 64-bit systems have a limit of 2³¹-1 and 32-bit systems have a limit of 2²⁸-1.