% $Id: cartesian.tex,v 1.1.1.2 2003/09/22 18:04:42 nthiery Exp $
\begin{Mhelppage}{cartesian}{Torsten Metzner}[ImplState=stable,TestState=stable,DocState=deprecated]
\begin{MInfo}
  \eng{cartesian product of sets (deprecated)}
\end{MInfo}

\Mproofread{stefanw}{5.6.00}{fertig}

\begin{MIntro}
  \eng{\Mthis\Mex{(set1, set2, ..., setk)} computes the cartesian
    product of the given sets \Mpar{set1}, \Mpar{set2}, ...,
    \Mpar{setk}.}
  
  \eng{For every positive integer $n$, the set $ \{ 1, \ldots, n\} $
    may be denoted by \Mex{n}, and \Mex{0} may be written instead of
    the empty set.}

  \de{\large Noch keine deutsche Doku vorhanden}
\end{MIntro}

\begin{MCalls}
    \Mcall{set1, set2, ..., setk}
\end{MCalls}

\begin{MParameters}
  \param{set1, set2, ..., setk}
    \eng{Sets of domain type \Mup{DOM_SET}, or nonnegative integers. }
\end{MParameters}

\begin{MReturnValue}
  \eng{A set of domain type \Mup{DOM_SET} containing $k$-tuples of
    domain type \Mup{DOM_LIST}, where $k$ is the number of arguments.}
\end{MReturnValue}

\MKeywords{combinatorics}

\begin{MDetails}
  \eng{The cartesian product of the given sets \Mpar{set1},
    \Mpar{set2} is the set \Mmath{set1 x set2 x ... x setk}{set1
      \times set2 \times \ldots \times setk \,} of all $k$-tuples
    \Mmath{[x1,x2,...,xk]}{[x1,x2,\ldots,xk ]} with \Mmath{xn in setn
      for each 1<=n<=k}{x_n \in setn,\, 1\leq n \leq k}.}
  
  \eng{\Mthis() is not commutative, as demonstrated in
    example~\ref{ex-commutative}.}
\end{MDetails}

\begin{MExample}{ex1}
  \eng{Which cards exist, if you have the following suits and numbers
    available?}
  \begin{Mexin}
combinat::warnDeprecated(FALSE):
combinat::cartesian({Diamondsuit,Heartsuit,Spadesuit,Clubsuit},{7,8,9,10})
  \end{Mexin}
  \begin{Mexout}
{[Clubsuit, 7], [Clubsuit, 8], [Clubsuit, 9], [Clubsuit, 10],

   [Spadesuit, 7], [Spadesuit, 8], [Spadesuit, 9],

   [Spadesuit, 10], [Diamondsuit, 7], [Diamondsuit, 8],

   [Diamondsuit, 9], [Diamondsuit, 10], [Heartsuit, 7],

   [Heartsuit, 8], [Heartsuit, 9], [Heartsuit, 10]}
  \end{Mexout}

  \eng{\Mwarn{The function \Mup{combinat::cartesian} is deprecated:}}
  \begin{Mexin}
old_val:=combinat::warnDeprecated(TRUE):
combinat::cartesian({Diamondsuit,Heartsuit,Spadesuit,Clubsuit},{7,8,9,10});
combinat::warnDeprecated(old_val):
  \end{Mexin}
  \begin{Mexout}
Warning: combinat::cartesian(s1,s2,...) is obsolete.
Please use 'combinat::cartesianProduct::list(s1,s2,...)' inste\
ad. [combinat::cartesian]

{[Clubsuit, 7], [Clubsuit, 8], [Clubsuit, 9], [Clubsuit, 10],

   [Spadesuit, 7], [Spadesuit, 8], [Spadesuit, 9],

   [Spadesuit, 10], [Diamondsuit, 7], [Diamondsuit, 8],

   [Diamondsuit, 9], [Diamondsuit, 10], [Heartsuit, 7],

   [Heartsuit, 8], [Heartsuit, 9], [Heartsuit, 10]}
  \end{Mexout}

  \eng{Here is the recommended replacement:}
  \begin{Mexin}
combinat::cartesianProduct::list({Diamondsuit,Heartsuit,Spadesuit,Clubsuit},{7,8,9,10})
  \end{Mexin}
  \begin{Mexout}
[[Diamondsuit, 7], [Diamondsuit, 8], [Diamondsuit, 9],

   [Diamondsuit, 10], [Heartsuit, 7], [Heartsuit, 8],

   [Heartsuit, 9], [Heartsuit, 10], [Spadesuit, 7],

   [Spadesuit, 8], [Spadesuit, 9], [Spadesuit, 10],

   [Clubsuit, 7], [Clubsuit, 8], [Clubsuit, 9], [Clubsuit, 10]]
  \end{Mexout}
  \eng{Note that the result is returned as a list.}
\end{MExample}

\begin{MExample}{ex2}
  \eng{The same as above, but with other numbers:}
  \begin{Mexin}
combinat::cartesian({Diamondsuit,Heartsuit,Spadesuit,Clubsuit},3)
  \end{Mexin}
  \begin{Mexout}
{[Clubsuit, 1], [Clubsuit, 2], [Clubsuit, 3], [Spadesuit, 1],

   [Spadesuit, 2], [Spadesuit, 3], [Diamondsuit, 1],

   [Diamondsuit, 2], [Diamondsuit, 3], [Heartsuit, 1],

   [Heartsuit, 2], [Heartsuit, 3]}
  \end{Mexout}

  \eng{Here is the recommended replacement:}
  \begin{Mexin}
combinat::cartesianProduct::list({Diamondsuit,Heartsuit,Spadesuit,Clubsuit},3)
  \end{Mexin}
  \begin{Mexout}
[[Diamondsuit, 1], [Diamondsuit, 2], [Diamondsuit, 3],

   [Heartsuit, 1], [Heartsuit, 2], [Heartsuit, 3],

   [Spadesuit, 1], [Spadesuit, 2], [Spadesuit, 3],

   [Clubsuit, 1], [Clubsuit, 2], [Clubsuit, 3]]
  \end{Mexout}
\end{MExample}

\begin{MExample}{ex-commutative}
  \eng{The cartesian product isn't commutative:}
  \begin{Mexin}
combinat::cartesian({Diamondsuit},2); combinat::cartesian(2,{Diamondsuit})
  \end{Mexin}
  \begin{Mexout}
             {[Diamondsuit, 1], [Diamondsuit, 2]}

             {[1, Diamondsuit], [2, Diamondsuit]}
  \end{Mexout}
\end{MExample}

\begin{MChanges}
  \version{2.0} 
  \none
  \version{2.5}%
  \eng[Deprecated function]{This function is temporarily retained for
    backward compatibility; however, its usage is strongly deprecated
    in favor of the library \Mup{combinat::cartesianProduct}. The
    emission of a warning can be controlled with
    \Mupc{combinat::warnDeprecated}{FALSE} or
    \Mupc{combinat::warnDeprecated}{TRUE}.}
\end{MChanges}

\end{Mhelppage}
