.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Combinatorics 3pm" .TH Combinatorics 3pm "2012-02-10" "perl v5.20.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Algorithm::Combinatorics \- Efficient generation of combinatorial sequences .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Algorithm::Combinatorics qw(permutations); \& \& my @data = qw(a b c); \& \& # scalar context gives an iterator \& my $iter = permutations(\e@data); \& while (my $p = $iter\->next) { \& # ... \& } \& \& # list context slurps \& my @all_permutations = permutations(\e@data); .Ve .SH "VERSION" .IX Header "VERSION" This documentation refers to Algorithm::Combinatorics version 0.26. .SH "DESCRIPTION" .IX Header "DESCRIPTION" Algorithm::Combinatorics is an efficient generator of combinatorial sequences. Algorithms are selected from the literature (work in progress, see \*(L"\s-1REFERENCES\*(R"\s0). Iterators do not use recursion, nor stacks, and are written in C. .PP Tuples are generated in lexicographic order, except in \f(CW\*(C`subsets()\*(C'\fR. .SH "SUBROUTINES" .IX Header "SUBROUTINES" Algorithm::Combinatorics provides these subroutines: .PP .Vb 12 \& permutations(\e@data) \& circular_permutations(\e@data) \& derangements(\e@data) \& complete_permutations(\e@data) \& variations(\e@data, $k) \& variations_with_repetition(\e@data, $k) \& tuples(\e@data, $k) \& tuples_with_repetition(\e@data, $k) \& combinations(\e@data, $k) \& combinations_with_repetition(\e@data, $k) \& partitions(\e@data[, $k]) \& subsets(\e@data[, $k]) .Ve .PP All of them are context-sensitive: .IP "\(bu" 4 In scalar context subroutines return an iterator that responds to the \f(CW\*(C`next()\*(C'\fR method. Using this object you can iterate over the sequence of tuples one by one this way: .Sp .Vb 4 \& my $iter = combinations(\e@data, $k); \& while (my $c = $iter\->next) { \& # ... \& } .Ve .Sp The \f(CW\*(C`next()\*(C'\fR method returns an arrayref to the next tuple, if any, or \f(CW\*(C`undef\*(C'\fR if the sequence is exhausted. .Sp Memory usage is minimal, no recursion and no stacks are involved. .IP "\(bu" 4 In list context subroutines slurp the entire set of tuples. This behaviour is offered for convenience, but take into account that the resulting array may be really huge: .Sp .Vb 1 \& my @all_combinations = combinations(\e@data, $k); .Ve .SS "permutations(\e@data)" .IX Subsection "permutations(@data)" The permutations of \f(CW@data\fR are all its reorderings. For example, the permutations of \f(CW\*(C`@data = (1, 2, 3)\*(C'\fR are: .PP .Vb 6 \& (1, 2, 3) \& (1, 3, 2) \& (2, 1, 3) \& (2, 3, 1) \& (3, 1, 2) \& (3, 2, 1) .Ve .PP The number of permutations of \f(CW\*(C`n\*(C'\fR elements is: .PP .Vb 2 \& n! = 1, if n = 0 \& n! = n*(n\-1)*...*1, if n > 0 .Ve .PP See some values at . .SS "circular_permutations(\e@data)" .IX Subsection "circular_permutations(@data)" The circular permutations of \f(CW@data\fR are its arrangements around a circle, where only relative order of elements matter, rather than their actual position. Think possible arrangements of people around a circular table for dinner according to whom they have to their right and left, no matter the actual chair they sit on. .PP For example the circular permutations of \f(CW\*(C`@data = (1, 2, 3, 4)\*(C'\fR are: .PP .Vb 6 \& (1, 2, 3, 4) \& (1, 2, 4, 3) \& (1, 3, 2, 4) \& (1, 3, 4, 2) \& (1, 4, 2, 3) \& (1, 4, 3, 2) .Ve .PP The number of circular permutations of \f(CW\*(C`n\*(C'\fR elements is: .PP .Vb 2 \& n! = 1, if 0 <= n <= 1 \& (n\-1)! = (n\-1)*(n\-2)*...*1, if n > 1 .Ve .PP See a few numbers in a comment of . .SS "derangements(\e@data)" .IX Subsection "derangements(@data)" The derangements of \f(CW@data\fR are those reorderings that have no element in its original place. In jargon those are the permutations of \f(CW@data\fR with no fixed points. For example, the derangements of \f(CW\*(C`@data = (1, 2, 3)\*(C'\fR are: .PP .Vb 2 \& (2, 3, 1) \& (3, 1, 2) .Ve .PP The number of derangements of \f(CW\*(C`n\*(C'\fR elements is: .PP .Vb 2 \& d(n) = 1, if n = 0 \& d(n) = n*d(n\-1) + (\-1)**n, if n > 0 .Ve .PP See some values at . .SS "complete_permutations(\e@data)" .IX Subsection "complete_permutations(@data)" This is an alias for \f(CW\*(C`derangements\*(C'\fR, documented above. .ie n .SS "variations(\e@data, $k)" .el .SS "variations(\e@data, \f(CW$k\fP)" .IX Subsection "variations(@data, $k)" The variations of length \f(CW$k\fR of \f(CW@data\fR are all the tuples of length \f(CW$k\fR consisting of elements of \f(CW@data\fR. For example, for \f(CW\*(C`@data = (1, 2, 3)\*(C'\fR and \f(CW\*(C`$k = 2\*(C'\fR: .PP .Vb 6 \& (1, 2) \& (1, 3) \& (2, 1) \& (2, 3) \& (3, 1) \& (3, 2) .Ve .PP For this to make sense, \f(CW$k\fR has to be less than or equal to the length of \f(CW@data\fR. .PP Note that .PP .Vb 1 \& permutations(\e@data); .Ve .PP is equivalent to .PP .Vb 1 \& variations(\e@data, scalar @data); .Ve .PP The number of variations of \f(CW\*(C`n\*(C'\fR elements taken in groups of \f(CW\*(C`k\*(C'\fR is: .PP .Vb 2 \& v(n, k) = 1, if k = 0 \& v(n, k) = n*(n\-1)*...*(n\-k+1), if 0 < k <= n .Ve .ie n .SS "variations_with_repetition(\e@data, $k)" .el .SS "variations_with_repetition(\e@data, \f(CW$k\fP)" .IX Subsection "variations_with_repetition(@data, $k)" The variations with repetition of length \f(CW$k\fR of \f(CW@data\fR are all the tuples of length \f(CW$k\fR consisting of elements of \f(CW@data\fR, including repetitions. For example, for \f(CW\*(C`@data = (1, 2, 3)\*(C'\fR and \f(CW\*(C`$k = 2\*(C'\fR: .PP .Vb 9 \& (1, 1) \& (1, 2) \& (1, 3) \& (2, 1) \& (2, 2) \& (2, 3) \& (3, 1) \& (3, 2) \& (3, 3) .Ve .PP Note that \f(CW$k\fR can be greater than the length of \f(CW@data\fR. For example, for \f(CW\*(C`@data = (1, 2)\*(C'\fR and \f(CW\*(C`$k = 3\*(C'\fR: .PP .Vb 8 \& (1, 1, 1) \& (1, 1, 2) \& (1, 2, 1) \& (1, 2, 2) \& (2, 1, 1) \& (2, 1, 2) \& (2, 2, 1) \& (2, 2, 2) .Ve .PP The number of variations with repetition of \f(CW\*(C`n\*(C'\fR elements taken in groups of \f(CW\*(C`k >= 0\*(C'\fR is: .PP .Vb 1 \& vr(n, k) = n**k .Ve .ie n .SS "tuples(\e@data, $k)" .el .SS "tuples(\e@data, \f(CW$k\fP)" .IX Subsection "tuples(@data, $k)" This is an alias for \f(CW\*(C`variations\*(C'\fR, documented above. .ie n .SS "tuples_with_repetition(\e@data, $k)" .el .SS "tuples_with_repetition(\e@data, \f(CW$k\fP)" .IX Subsection "tuples_with_repetition(@data, $k)" This is an alias for \f(CW\*(C`variations_with_repetition\*(C'\fR, documented above. .ie n .SS "combinations(\e@data, $k)" .el .SS "combinations(\e@data, \f(CW$k\fP)" .IX Subsection "combinations(@data, $k)" The combinations of length \f(CW$k\fR of \f(CW@data\fR are all the sets of size \f(CW$k\fR consisting of elements of \f(CW@data\fR. For example, for \f(CW\*(C`@data = (1, 2, 3, 4)\*(C'\fR and \f(CW\*(C`$k = 3\*(C'\fR: .PP .Vb 4 \& (1, 2, 3) \& (1, 2, 4) \& (1, 3, 4) \& (2, 3, 4) .Ve .PP For this to make sense, \f(CW$k\fR has to be less than or equal to the length of \f(CW@data\fR. .PP The number of combinations of \f(CW\*(C`n\*(C'\fR elements taken in groups of \f(CW\*(C`0 <= k <= n\*(C'\fR is: .PP .Vb 1 \& n choose k = n!/(k!*(n\-k)!) .Ve .ie n .SS "combinations_with_repetition(\e@data, $k);" .el .SS "combinations_with_repetition(\e@data, \f(CW$k\fP);" .IX Subsection "combinations_with_repetition(@data, $k);" The combinations of length \f(CW$k\fR of an array \f(CW@data\fR are all the bags of size \f(CW$k\fR consisting of elements of \f(CW@data\fR, with repetitions. For example, for \f(CW\*(C`@data = (1, 2, 3)\*(C'\fR and \f(CW\*(C`$k = 2\*(C'\fR: .PP .Vb 6 \& (1, 1) \& (1, 2) \& (1, 3) \& (2, 2) \& (2, 3) \& (3, 3) .Ve .PP Note that \f(CW$k\fR can be greater than the length of \f(CW@data\fR. For example, for \f(CW\*(C`@data = (1, 2, 3)\*(C'\fR and \f(CW\*(C`$k = 4\*(C'\fR: .PP .Vb 10 \& (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) .Ve .PP The number of combinations with repetition of \f(CW\*(C`n\*(C'\fR elements taken in groups of \f(CW\*(C`k >= 0\*(C'\fR is: .PP .Vb 1 \& n+k\-1 over k = (n+k\-1)!/(k!*(n\-1)!) .Ve .ie n .SS "partitions(\e@data[, $k])" .el .SS "partitions(\e@data[, \f(CW$k\fP])" .IX Subsection "partitions(@data[, $k])" A partition of \f(CW@data\fR is a division of \f(CW@data\fR in separate pieces. Technically that's a set of subsets of \f(CW@data\fR which are non-empty, disjoint, and whose union is \f(CW@data\fR. For example, the partitions of \f(CW\*(C`@data = (1, 2, 3)\*(C'\fR are: .PP .Vb 5 \& ((1, 2, 3)) \& ((1, 2), (3)) \& ((1, 3), (2)) \& ((1), (2, 3)) \& ((1), (2), (3)) .Ve .PP 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 \f(CW@data\fR. .PP The number of partitions of a set of \f(CW\*(C`n\*(C'\fR elements are known as Bell numbers, and satisfy the recursion: .PP .Vb 2 \& B(0) = 1 \& B(n+1) = (n over 0)B(0) + (n over 1)B(1) + ... + (n over n)B(n) .Ve .PP See some values at . .PP If you pass the optional parameter \f(CW$k\fR, the subroutine generates only partitions of size \f(CW$k\fR. This uses an specific algorithm for partitions of known size, which is more efficient than generating all partitions and filtering them by size. .PP Note that in that case the subsets themselves may have several sizes, it is the number of elements \fIof the partition\fR which is \f(CW$k\fR. For instance if \f(CW@data\fR 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. .PP The number of partitions of size \f(CW\*(C`k\*(C'\fR of a set of \f(CW\*(C`n\*(C'\fR elements are known as Stirling numbers of the second kind, and satisfy the recursion: .PP .Vb 4 \& 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) .Ve .ie n .SS "subsets(\e@data[, $k])" .el .SS "subsets(\e@data[, \f(CW$k\fP])" .IX Subsection "subsets(@data[, $k])" This subroutine iterates over the subsets of data, which is assumed to represent a set. If you pass the optional parameter \f(CW$k\fR the iteration runs over subsets of data of size \f(CW$k\fR. .PP The number of subsets of a set of \f(CW\*(C`n\*(C'\fR elements is .PP .Vb 1 \& 2**n .Ve .PP See some values at . .SH "CORNER CASES" .IX Header "CORNER CASES" Since version 0.05 subroutines are more forgiving for unsual values of \f(CW$k\fR: .IP "\(bu" 4 If \f(CW$k\fR is less than zero no tuple exists. Thus, the very first call to the iterator's \f(CW\*(C`next()\*(C'\fR method returns \f(CW\*(C`undef\*(C'\fR, and a call in list context returns the empty list. (See \*(L"\s-1DIAGNOSTICS\*(R"\s0.) .IP "\(bu" 4 If \f(CW$k\fR is zero we have one tuple, the empty tuple. This is a different case than the former: when \f(CW$k\fR is negative there are no tuples at all, when \f(CW$k\fR 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 \&\f(CW@data\fR with \f(CW\*(C`$k = 0\*(C'\fR elements, so it complies with the definition. .IP "\(bu" 4 If \f(CW$k\fR is greater than the size of \f(CW@data\fR, 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 \f(CW\*(C`next()\*(C'\fR method returns \f(CW\*(C`undef\*(C'\fR, and a call in list context returns the empty list. (See \*(L"\s-1DIAGNOSTICS\*(R"\s0.) .PP In addition, since 0.05 empty \f(CW@data\fRs are supported as well. .SH "EXPORT" .IX Header "EXPORT" Algorithm::Combinatorics exports nothing by default. Each of the subroutines can be exported on demand, as in .PP .Vb 1 \& use Algorithm::Combinatorics qw(combinations); .Ve .PP and the tag \f(CW\*(C`all\*(C'\fR exports them all: .PP .Vb 1 \& use Algorithm::Combinatorics qw(:all); .Ve .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" .SS "Warnings" .IX Subsection "Warnings" The following warnings may be issued: .ie n .IP "Useless use of %s in void context" 4 .el .IP "Useless use of \f(CW%s\fR in void context" 4 .IX Item "Useless use of %s in void context" A subroutine was called in void context. .IP "Parameter k is negative" 4 .IX Item "Parameter k is negative" A subroutine was called with a negative k. .IP "Parameter k is greater than the size of data" 4 .IX Item "Parameter k is greater than the size of data" A subroutine that does not generate tuples with repetitions was called with a k greater than the size of data. .SS "Errors" .IX Subsection "Errors" The following errors may be thrown: .IP "Missing parameter data" 4 .IX Item "Missing parameter data" A subroutine was called with no parameters. .IP "Missing parameter k" 4 .IX Item "Missing parameter k" A subroutine that requires a second parameter k was called without one. .IP "Parameter data is not an arrayref" 4 .IX Item "Parameter data is not an arrayref" The first parameter is not an arrayref (tested with \*(L"\fIreftype()\fR\*(R" from Scalar::Util.) .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" Algorithm::Combinatorics is known to run under perl 5.6.2. The distribution uses Test::More and FindBin for testing, Scalar::Util for \f(CW\*(C`reftype()\*(C'\fR, and XSLoader for \s-1XS.\s0 .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \&\f(CW\*(C`bug\-algorithm\-combinatorics@rt.cpan.org\*(C'\fR, or through the web interface at . .SH "SEE ALSO" .IX Header "SEE ALSO" Math::Combinatorics is a pure Perl module that offers similar features. .PP List::PowerSet offers a fast pure-Perl generator of power sets that Algorithm::Combinatorics copies and translates to \s-1XS.\s0 .SH "BENCHMARKS" .IX Header "BENCHMARKS" There are some benchmarks in the \fIbenchmarks\fR directory of the distribution. .SH "REFERENCES" .IX Header "REFERENCES" [1] Donald E. Knuth, \fIThe Art of Computer Programming, Volume 4, Fascicle 2: Generating All Tuples and Permutations\fR. Addison Wesley Professional, 2005. \s-1ISBN 0201853930.\s0 .PP [2] Donald E. Knuth, \fIThe Art of Computer Programming, Volume 4, Fascicle 3: Generating All Combinations and Partitions\fR. Addison Wesley Professional, 2005. \s-1ISBN 0201853949.\s0 .PP [3] Michael Orlov, \fIEfficient Generation of Set Partitions\fR, . .SH "AUTHOR" .IX Header "AUTHOR" Xavier Noria (\s-1FXN\s0), .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2005\-2012 Xavier Noria, all rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.