Combinatorics(3pm)

📦

version 0.27 · 10 versions

🦋 Combinatorics(3pm) — User Contributed Perl Documentation 🦋

okay bestie, buckle UP, because this is the <pink>Algorithm::Combinatorics</pink> page and it is genuinely iconic. it's a Perl module for generating combinatorial sequences and no cap, it's fast. like, C-fast. we're in our math era 💅

✨ NAME ✨

Algorithm::Combinatorics — Efficient generation of combinatorial sequences. yes, "efficient" is in the actual name-adjacent description, we don't make the rules, we just slay by them 🫶

✨ SYNOPSIS ✨

here's the vibe, fr fr:

use Algorithm::Combinatorics qw(permutations);

my @data = qw(a b c);

# scalar context gives an iterator
my $iter = permutations(\@data);
while (my $p = $iter->next) {
    # ...
}

# list context slurps
my @all_permutations = permutations(\@data);

see that? scalar context hands you an iterator, list context just yanks the whole thing into an array. the duality 😭

✨ VERSION ✨

this documentation is talking about Algorithm::Combinatorics version 0.26. periodt.

✨ DESCRIPTION ✨

Algorithm::Combinatorics is an efficient generator of combinatorial sequences. the algorithms are pulled straight from the literature (work in progress btw, peep the "REFERENCES" section when we get there). the iterators do not use recursion, they do not use stacks, and they're written in C. she's lowkey a little machine 🧚

Tuples get generated in lexicographic order — except in subsets(), which is out here doing its own thing. main character behavior, honestly. 👑

✨ SUBROUTINES ✨

okay so here's the full roster, <pink>Algorithm::Combinatorics</pink> serves up all of these:

permutations(\@data)
circular_permutations(\@data)
derangements(\@data)
complete_permutations(\@data)
variations(\@data, $k)
variations_with_repetition(\@data, $k)
tuples(\@data, $k)
tuples_with_repetition(\@data, $k)
combinations(\@data, $k)
combinations_with_repetition(\@data, $k)
partitions(\@data[, $k])
subsets(\@data[, $k])

and every single one of them is context-sensitive. literally every one. here's the tea:

In scalar context, the subroutines return an iterator that responds to the next() method. using this lil object you can walk the sequence of tuples one at a time, like so:

my $iter = combinations(\@data, $k);
while (my $c = $iter->next) {
    # ...
}

The next() method returns an arrayref to the next tuple, if there is one, or "undef" if the sequence is exhausted — like, tapped out, done, no more crumbs.

Memory usage stays minimal, and there is no recursion and no stacks involved. she's lean. she's efficient. she's not carrying anybody's baggage 💅

In list context, the subroutines slurp the entire set of tuples. this behavior exists purely for convenience, but be so for real right now: the resulting array may be really huge:

my @all_combinations = combinations(\@data, $k);

⚠️ bestie, "really huge" is not a drill. you asked for the whole list, you got the whole list. your RAM is going through it. 😭

🌸 `permutations(\@data)` 🌸

The permutations of @data are all its reorderings. for example, the permutations of "@data = (1, 2, 3)" are:

(1, 2, 3)
(1, 3, 2)
(2, 1, 3)
(2, 3, 1)
(3, 1, 2)
(3, 2, 1)

The number of permutations of "n" elements is:

n! = 1,                  if n = 0
n! = n*(n-1)*...*1,      if n > 0

wanna see some values? the original points you at the OEIS page for sequence A000142:

http://www.research.att.com/~njas/sequences/A000142

🎀 `circular_permutations(\@data)` 🎀

The circular permutations of @data are its arrangements around a circle — where only the relative order of elements matters, rather than their actual position. think of it as the possible seating arrangements of people around a circular dinner table, based on who's to their right and left, and zero percent based on which specific chair they're sitting in. the chair is irrelevant, the neighbors are everything 🍓

For example the circular permutations of "@data = (1, 2, 3, 4)" are:

(1, 2, 3, 4)
(1, 2, 4, 3)
(1, 3, 2, 4)
(1, 3, 4, 2)
(1, 4, 2, 3)
(1, 4, 3, 2)

The number of circular permutations of "n" elements is:

    n! = 1,                      if 0 <= n <= 1
(n-1)! = (n-1)*(n-2)*...*1,      if n > 1

you can peep a few numbers in a comment on sequence A000142:

http://www.research.att.com/~njas/sequences/A000142

💀 `derangements(\@data)` 💀

The derangements of @data are those reorderings that have no element in its original place. in jargon, these are the permutations of @data with no fixed points. everybody moved, nobody stayed home, it's giving total chaos 😭

For example, the derangements of "@data = (1, 2, 3)" are:

(2, 3, 1)
(3, 1, 2)

The number of derangements of "n" elements is:

d(n) = 1,                       if n = 0
d(n) = n*d(n-1) + (-1)**n,      if n > 0

some values live at sequence A000166:

http://www.research.att.com/~njas/sequences/A000166

🦋 `complete_permutations(\@data)` 🦋

This is an alias for "derangements", documented just above. same energy, different name 💜

✨ `variations(\@data, $k)` ✨

The variations of length $k of @data are all the tuples of length $k consisting of elements of @data. for example, for "@data = (1, 2, 3)" and "$k = 2":

(1, 2)
(1, 3)
(2, 1)
(2, 3)
(3, 1)
(3, 2)

For this to make sense, $k has to be less than or equal to the length of @data. math said no to anything else 🙈

Note that

permutations(\@data);

is equivalent to

variations(\@data, scalar @data);

The number of variations of "n" elements taken in groups of "k" is:

v(n, k) = 1,                        if k = 0
v(n, k) = n*(n-1)*...*(n-k+1),      if 0 < k <= n

🌈 `variations_with_repetition(\@data, $k)` 🌈

The variations with repetition of length $k of @data are all the tuples of length $k consisting of elements of @data, including repetitions. you can reuse, bestie, it's allowed here. for example, for "@data = (1, 2, 3)" and "$k = 2":

(1, 1)
(1, 2)
(1, 3)
(2, 1)
(2, 2)
(2, 3)
(3, 1)
(3, 2)
(3, 3)

Note that $k can be greater than the length of @data. for example, for "@data = (1, 2)" and "$k = 3":

(1, 1, 1)
(1, 1, 2)
(1, 2, 1)
(1, 2, 2)
(2, 1, 1)
(2, 1, 2)
(2, 2, 1)
(2, 2, 2)

The number of variations with repetition of "n" elements taken in groups of "k >= 0" is:

vr(n, k) = n**k

🌸 `tuples(\@data, $k)` 🌸

This is an alias for "variations", documented above. 💅

🎀 `tuples_with_repetition(\@data, $k)` 🎀

This is an alias for "variations_with_repetition", documented above. 💅

👑 `combinations(\@data, $k)` 👑

The combinations of length $k of @data are all the sets of size $k consisting of elements of @data. sets, babes — order is not the moment here. for example, for "@data = (1, 2, 3, 4)" and "$k = 3":

(1, 2, 3)
(1, 2, 4)
(1, 3, 4)
(2, 3, 4)

For this to make sense, $k has to be less than or equal to the length of @data.

The number of combinations of "n" elements taken in groups of "0 <= k <= n" is:

n choose k = n!/(k!*(n-k)!)

🍓 `combinations_with_repetition(\@data, $k);` 🍓

The combinations of length $k of an array @data are all the bags of size $k consisting of elements of @data, with repetitions. for example, for "@data = (1, 2, 3)" and "$k = 2":

(1, 1)
(1, 2)
(1, 3)
(2, 2)
(2, 3)
(3, 3)

Note that $k can be greater than the length of @data. for example, for "@data = (1, 2, 3)" and "$k = 4":

(1, 1, 1, 1)
(1, 1, 1, 2)
(1, 1, 1, 3)
(1, 1, 2, 2)
(1, 1, 2, 3)
(1, 1, 3, 3)
(1, 2, 2, 2)
(1, 2, 2, 3)
(1, 2, 3, 3)
(1, 3, 3, 3)
(2, 2, 2, 2)
(2, 2, 2, 3)
(2, 2, 3, 3)
(2, 3, 3, 3)
(3, 3, 3, 3)

The number of combinations with repetition of "n" elements taken in groups of "k >= 0" is:

n+k-1 over k = (n+k-1)!/(k!*(n-1)!)

💜 `partitions(\@data[, $k])` 💜

A partition of @data is a division of @data in separate pieces. technically that's a set of subsets of @data which are non-empty, disjoint, and whose union is @data. no overlaps, no leftovers, no empty little groups just vibing. for example, the partitions of "@data = (1, 2, 3)" are:

((1, 2, 3))
((1, 2), (3))
((1, 3), (2))
((1), (2, 3))
((1), (2), (3))

This subroutine returns in consequence tuples of tuples. the top-level tuple (an arrayref) represents the partition itself, whose elements are tuples (arrayrefs) in turn, each one representing a subset of @data. it's arrayrefs all the way down, bestie, we love a nesting moment 🫶

The number of partitions of a set of "n" elements are known as Bell numbers, and satisfy the recursion:

B(0) = 1
B(n+1) = (n over 0)B(0) + (n over 1)B(1) + ... + (n over n)B(n)

some values are at sequence A000110:

http://www.research.att.com/~njas/sequences/A000110

If you pass the optional parameter $k, the subroutine generates only partitions of size $k. this uses a specific algorithm for partitions of known size, which is more efficient than generating all partitions and then filtering them by size. we do not do brute force and pray in this house 🙅‍♀️

Note that in that case the subsets themselves may have several sizes — it is the number of elements of the partition which is $k. for instance if @data has 5 elements there are partitions of size 2 that consist of a subset of size 2 and its complement of size 3; and partitions of size 2 that consist of a subset of size 1 and its complement of size 4. in both cases the partitions have the same size, they have two elements. so like, the $k is counting the pieces, not how big each piece is. iykyk 💅

The number of partitions of size "k" of a set of "n" elements are known as Stirling numbers of the second kind, and satisfy the recursion:

S(0, 0) = 1
S(n, 0) = 0 if n > 0
S(n, 1) = S(n, n) = 1
S(n, k) = S(n-1, k-1) + kS(n-1, k)

🧚 `subsets(\@data[, $k])` 🧚

This subroutine iterates over the subsets of data, which is assumed to represent a set. if you pass the optional parameter $k, the iteration runs over subsets of data of size $k.

The number of subsets of a set of "n" elements is

 2**n

some values live at sequence A000079:

http://www.research.att.com/~njas/sequences/A000079

✨ CORNER CASES ✨

Since version 0.05 the subroutines are way more forgiving for unusual values of $k. they really said "we can be chill about this" 🥰

If $k is less than zero, no tuple exists. thus, the very first call to the iterator's next() method returns "undef", and a call in list context returns the empty list. (peep "DIAGNOSTICS".)
If $k is zero we have one tuple — the empty tuple. this is a different case than the former: when $k is negative there are no tuples at all, when $k is zero there is one tuple. the rationale for this behaviour is the same rationale for n choose 0 = 1: the empty tuple is a subset of @data with "$k = 0" elements, so it complies with the definition. math is consistent and we respect her for it ✨
If $k is greater than the size of @data, and we are calling a subroutine that does not generate tuples with repetitions, no tuple exists. thus, the very first call to the iterator's next() method returns "undef", and a call in list context returns the empty list. (peep "DIAGNOSTICS".)

In addition, since 0.05 empty @datas are supported as well. yes bestie, the empty array gets a seat at the table too 🫶

✨ EXPORT ✨

Algorithm::Combinatorics exports nothing by default. not a single thing. you have to ask. consent is key 💅

Each of the subroutines can be exported on demand, as in

use Algorithm::Combinatorics qw(combinations);

and the tag "all" exports them all:

use Algorithm::Combinatorics qw(:all);

okay so that's the whole <pink>:all</pink> situation — one word, everything, no takebacks. 🌈

💖 DIAGNOSTICS 💖

Okay bestie, listen — sometimes this module has to be a little bit of a mood and tell you that you messed up. Here's the whole gossip, no cap. 🫶

🔔 Warnings

These are the gentle lil "hey babes…" nudges. They may be issued:

Useless use of %s in void context — you called a subroutine in void context. Like, you did the work and then threw it in the void? The audacity. 😭
Parameter k is negative — a subroutine got called with a negative k. Negative k is not the vibe, bestie. ✨
Parameter k is greater than the size of data — a subroutine that does not generate tuples with repetitions got called with a k that's bigger than the size of data. The math is mathing wrong, babe. 💀

🚨 Errors

And these ones? These are the full-on thrown errors. They get yeeted:

Missing parameter data — a subroutine was called with no parameters at all. Zero. Nothing. Ghosted. 👻
Missing parameter k — a subroutine that requires a second parameter, k, was called without one. It's giving "where is she." 🎀
Parameter data is not an arrayref — the first parameter isn't an arrayref. This gets tested with reftype() from Scalar::Util. 🙈

🌈 DEPENDENCIES

Algorithm::Combinatorics is known to run under perl 5.6.2. Iconic longevity honestly, she's been around. 👑

The distribution uses Test::More and FindBin for testing, Scalar::Util for reftype(), and XSLoader for XS. Little dream team fr fr. 💅

💀 BUGS

Please report any bugs or feature requests to bug-algorithm-combinatorics@rt.cpan.org, or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Algorithm-Combinatorics>.

Like, genuinely please do — she wants to grow and heal. 🌱

👀 SEE ALSO

Math::Combinatorics — a pure Perl module offering similar features. Same energy, different implementation. 🦋
List::PowerSet — offers a fast pure-Perl generator of power sets, which Algorithm::Combinatorics copies and translates to XS. The way she took notes and went to the gym. 💪

🔥 BENCHMARKS

There are some benchmarks in the benchmarks directory of the distribution. Numbers, bestie. Receipts. ✨

📚 REFERENCES

[1] Donald E. Knuth, The Art of Computer Programming, Volume 4, Fascicle 2: Generating All Tuples and Permutations. Addison Wesley Professional, 2005. ISBN 0201853930.
[2] Donald E. Knuth, The Art of Computer Programming, Volume 4, Fascicle 3: Generating All Combinations and Partitions. Addison Wesley Professional, 2005. ISBN 0201853949.
[3] Michael Orlov, Efficient Generation of Set Partitions, <http://www.informatik.uni-ulm.de/ni/Lehre/WS03/DMM/Software/partitions.pdf>.

Knuth citation is main character energy honestly. 👑

🎀 AUTHOR

Xavier Noria (FXN), <fxn@cpan.org> — thank you for your service, king. 🫶

💜 COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Slay, and also legally binding. 🌸

and that's the whole page, bestie — from perl v5.42.3, dated 2026-08-19, this was Combinatorics(3pm) 🦋✨💖 go forth and generate all the tuples, permutations and combinations your heart desires, you absolute genius 👑💅

📦 where this page comes from

ubuntu stonking: libalgorithm-combinatorics-perl 0.27-3build6 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

Combinatorics(3pm)