view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    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

    See some values at http://www.research.att.com/~njas/sequences/A000079.

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

    *   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 `@data's 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 is known to run under perl 5.6.2. The
    distribution uses Test::More and FindBin for testing, Scalar::Util for
    `reftype()', and XSLoader for XS.

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.

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

    List::PowerSet offers a fast pure-Perl generator of power sets that
    Algorithm::Combinatorics copies and translates to XS.

BENCHMARKS
    There are some benchmarks in the benchmarks directory of the
    distribution.

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

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

COPYRIGHT & LICENSE
    Copyright 2005-2012 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.