Name

    Math::Cartesian::Product - Generate the Cartesian product of zero or
    more lists.

Synopsis

     use Math::Cartesian::Product;
    
     cartesian {print "@_\n"} [qw(a b c)], [1..2];
    
     #  a 1
     #  a 2
     #  b 1
     #  b 2
     #  c 1
     #  c 2
    
     cartesian {print "@_\n"} ([0..1]) x 8;
    
     #  0 0 0 0 0 0 0 0
     #  0 0 0 0 0 0 0 1
     #  0 0 0 0 0 0 1 0
     #  ...
     #  1 1 1 1 1 1 1 0
     #  1 1 1 1 1 1 1 1
    
     print "@$_\n" for
       cartesian {"@{[reverse @_]}" eq "@_"}
         ([' ', '*']) x 8;
    
     #       * *
     #     *     *
     #     * * * *
     #   *         *
     #   *   * *   *
     #   * *     * *
     #   * * * * * *
     # *             *
     # *     * *     *
     # *   *     *   *
     # *   * * * *   *
     # * *         * *
     # * *   * *   * *
     # * * *     * * *
     # * * * * * * * *

Description

    Generate the Cartesian product of zero or more lists.

    Given two lists, say: [a,b] and [1,2,3], the Cartesian product is the
    set of all ordered pairs:

     (a,1), (a,2), (a,3), (b,1), (b,2), (b,3)

    which select their first element from all the possibilities listed in
    the first list, and select their second element from all the
    possibilities in the second list.

    The idea can be generalized to n-tuples selected from n lists where all
    the elements of the first list are combined with all the elements of
    the second list, the results of which are then combined with all the
    member of the third list and so on over all the input lists.

    It should be noted that Cartesian product of one or more lists where
    one or more of the lists are empty (representing the empty set) is the
    empty set and thus has zero members; and that the Cartesian product of
    zero lists is a set with exactly one member, namely the empty set.

    cartesian() takes the following parameters:

    1. A block of code to process each n-tuple. this code should return
    true if the current n-tuple should be included in the returned value of
    the cartesian() function, otherwise false.

    2. Zero or more lists.

    cartesian() returns an array of references to all the n-tuples selected
    by the code block supplied as parameter 1 if called in list context,
    else it returns a count of the selected n-tuples.

    cartesian() croaks if you try to form the Cartesian product of
    something other than lists of things or prior Cartesian products.

    The cartesian product of lists A,B,C is associative, that is:

      (A X B) X C = A X (B X C)

    cartesian() respects associativity by allowing you to include a
    Cartesian product produced by an earlier call to cartesian() in the set
    of lists whose Cartesian product is to be formed, at the cost of a
    performance penalty if this option is chosen.

      use Math::Cartesian::Product;
    
      my $a = [qw(a b)];
      my $b = [cartesian {1} $a, $a];
      cartesian {print "@_\n"} $b, $b;
    
      # a a a a
      # a a a b
      # a a b a
      # ...

    cartesian() is easy to use and fast. It is written in 100% Pure Perl.

Export

    The cartesian() function is exported.

Installation

    Standard Module::Build process for building and installing modules:

      perl Build.PL
      ./Build
      ./Build test
      ./Build install

    Or, if you're on a platform (like DOS or Windows) that doesn't require
    the "./" notation, you can do this:

      perl Build.PL
      Build
      Build test
      Build install

Author

    Philip R Brenan at gmail dot com

    http://www.appaapps.com

Acknowledgements

    With much help and good natured advice from Philipp Rumpf and Justin
    Case to whom I am indebted.

See Also

    Math::Disarrange::List

    Math::Permute::List

    Math::Permute::Lists

    Math::Permute::Partitions

    Math::Subsets::List

    Math::Transform::List

Copyright

    Copyright (c) 2009-2015 Philip R Brenan.

    This module is free software. It may be used, redistributed and/or
    modified under the same terms as Perl itself.