.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 >0, 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 "Math::Cartesian::Product 3pm"
.TH Math::Cartesian::Product 3pm "2022-10-13" "perl v5.34.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"
.IX Header "Name"
Math::Cartesian::Product \- Generate the Cartesian product of zero or more lists.
.SH "Synopsis"
.IX Header "Synopsis"
.Vb 1
\& use Math::Cartesian::Product;
\&
\& cartesian {print "@_\en"} [qw(a b c)], [1..2];
\&
\& #  a 1
\& #  a 2
\& #  b 1
\& #  b 2
\& #  c 1
\& #  c 2
\&
\& cartesian {print "@_\en"} ([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 "@$_\en" for
\&   cartesian {"@{[reverse @_]}" eq "@_"}
\&     ([\*(Aq \*(Aq, \*(Aq*\*(Aq]) x 8;
\&
\& #       * *
\& #     *     *
\& #     * * * *
\& #   *         *
\& #   *   * *   *
\& #   * *     * *
\& #   * * * * * *
\& # *             *
\& # *     * *     *
\& # *   *     *   *
\& # *   * * * *   *
\& # * *         * *
\& # * *   * *   * *
\& # * * *     * * *
\& # * * * * * * * *
.Ve
.SH "Description"
.IX Header "Description"
Generate the Cartesian product of zero or more lists.
.PP
Given two lists, say: [a,b] and [1,2,3], the Cartesian product is the
set of all ordered pairs:
.PP
.Vb 1
\& (a,1), (a,2), (a,3), (b,1), (b,2), (b,3)
.Ve
.PP
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.
.PP
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.
.PP
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.
.PP
\&\f(CW\*(C`cartesian()\*(C'\fR takes the following parameters:
.PP
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
\&\f(CW\*(C`cartesian()\*(C'\fR function, otherwise false.
.PP
2. Zero or more lists.
.PP
\&\f(CW\*(C`cartesian()\*(C'\fR 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.
.PP
\&\f(CW\*(C`cartesian()\*(C'\fR croaks if you try to form the Cartesian product of
something other than lists of things or prior Cartesian products.
.PP
The cartesian product of lists A,B,C is associative, that is:
.PP
.Vb 1
\&  (A X B) X C = A X (B X C)
.Ve
.PP
\&\f(CW\*(C`cartesian()\*(C'\fR respects associativity by allowing you to include a
Cartesian product produced by an earlier call to \f(CW\*(C`cartesian()\*(C'\fR in the
set of lists whose Cartesian product is to be formed, at the cost of a
performance penalty if this option is chosen.
.PP
.Vb 1
\&  use Math::Cartesian::Product;
\&
\&  my $a = [qw(a b)];
\&  my $b = [cartesian {1} $a, $a];
\&  cartesian {print "@_\en"} $b, $b;
\&
\&  # a a a a
\&  # a a a b
\&  # a a b a
\&  # ...
.Ve
.PP
\&\f(CW\*(C`cartesian()\*(C'\fR is easy to use and fast. It is written in 100% Pure Perl.
.SH "Export"
.IX Header "Export"
The \f(CW\*(C`cartesian()\*(C'\fR function is exported.
.SH "Installation"
.IX Header "Installation"
Standard Module::Build process for building and installing modules:
.PP
.Vb 4
\&  perl Build.PL
\&  ./Build
\&  ./Build test
\&  ./Build install
.Ve
.PP
Or, if you're on a platform (like \s-1DOS\s0 or Windows) that doesn't require
the \*(L"./\*(R" notation, you can do this:
.PP
.Vb 4
\&  perl Build.PL
\&  Build
\&  Build test
\&  Build install
.Ve
.SH "Author"
.IX Header "Author"
Philip R Brenan at gmail dot com
.PP
http://www.appaapps.com
.SH "Acknowledgements"
.IX Header "Acknowledgements"
With much help and good natured advice from Philipp Rumpf and Justin Case to
whom I am indebted.
.SH "See Also"
.IX Header "See Also"
.IP "Math::Disarrange::List" 4
.IX Item "Math::Disarrange::List"
.PD 0
.IP "Math::Permute::List" 4
.IX Item "Math::Permute::List"
.IP "Math::Permute::Lists" 4
.IX Item "Math::Permute::Lists"
.IP "Math::Permute::Partitions" 4
.IX Item "Math::Permute::Partitions"
.IP "Math::Subsets::List" 4
.IX Item "Math::Subsets::List"
.IP "Math::Transform::List" 4
.IX Item "Math::Transform::List"
.PD
.SH "Copyright"
.IX Header "Copyright"
Copyright (c) 2009\-2015 Philip R Brenan.
.PP
This module is free software. It may be used, redistributed and/or
modified under the same terms as Perl itself.