view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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

DESCRIPTION
    Algorithm::Combinatorics is an efficient generator of combinatorial
    sequences. Algorithms are selected from the literature (work in
    progress, see REFERENCES). Iterators do not use recursion, nor stacks,
    and are written in C.

    Tuples are generated in lexicographic order, except in `subsets()'.

SUBROUTINES
    Algorithm::Combinatorics provides these subroutines:

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

    All of them are context-sensitive:

    *   In scalar context 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.

        Memory usage is minimal, no recursion and no stacks are involved.

    *   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:

            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