/ 
Algorithm-Combinatorics-0.07
River stage three • 17 direct dependents • 122 total dependents
/ Algorithm::Combinatorics

NAME

Algorithm::Combinatorics - Efficient generation of combinatorial sequences

SYNOPSIS

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);

VERSION

This documentation refers to Algorithm::Combinatorics version 0.07.

DESCRIPTION

Algorithm::Combinatorics is an efficient generator of combinatorial sequences, where efficient means:

  • Speed: The core loops are written in C.

  • Memory: No recursion and no stacks are used.

Tuples are generated in lexicographic order.

SUBROUTINES

Algorithm::Combinatorics provides these subroutines:

permutations(\@data)
variations(\@data, $k)
variations_with_repetition(\@data, $k)
combinations(\@data, $k)
combinations_with_repetition(\@data, $k)

All of them are context-sensitive:

  • In scalar context the subroutines return an iterator that responds to the next() method. Using this object you can iterate over the sequence of tuples one by one this way:

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

    The next() method returns an arrayref to the next tuple, if any, or undef if the sequence is exhausted.

    Since no recursion and no stacks are used the memory usage is minimal. Thus, we can iterate over sequences of virtually any size.

  • In list context the 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:

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

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

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.

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. 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

combinations(\@data, $k)

The combinations of length $k of @data are all the sets of size $k consisting of elements of @data. 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)!)

CORNER CASES

Since version 0.05 subroutines are more forgiving for unsual values of $k:

  • 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. (See "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 a 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.

  • 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. (See "DIAGNOSTICS".)

In addition, since 0.05 empty @datas are supported as well.

EXPORT

Algorithm::Combinatorics exports nothing by default. 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);

DIAGNOSTICS

Warnings

The following warnings may be issued:

Useless use of %s in void context

A subroutine was called in void context.

Parameter k is negative

A subroutine was called with a negative k.

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.

Errors

The following errors may be thrown:

Missing parameter data

A subroutine was called with no parameters.

Missing parameter k

A subroutine that requires a second parameter k was called without one.

Parameter data is not an arrayref

The first parameter is not an arrayref (tested with "reftype()" from Scalar::Util.)

DEPENDENCIES

Algorithm::Combinatorics uses Test::More and FindBin for testing, Scalar::Util for reftype(), and Inline::C for XS.

SEE ALSO

Math::Combinatorics is a pure Perl module that offers similar features.

AUTHOR

Xavier Noria (FXN), <fxn@cpan.org>

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.

COPYRIGHT & LICENSE

Copyright 2005 Xavier Noria, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.