% $Id: powerset.tex,v 1.1.1.2 2003/09/22 18:04:43 nthiery Exp $
\begin{Mhelppage}{powerset}{Torsten Metzner}[ImplState=stable,TestState=stable,DocState=stable]
\begin{MInfo}
  \eng{power set of a set or list (deprecated)}
  \de{}
\end{MInfo}

\Mproofread{stefanw}{5.6.00}{fertig}

\begin{todo}
  Texte zu den Beispielen!
\end{todo}

\begin{MIntro}
  \eng{\Mthis\Mex{(set)} computes the powerset of the given set \Mpar{set},
    that is, the set of all subsets of \Mpar{set}.}
  
  \eng{\Mthis\Mex{(list)} computes the powerset of the given list \Mpar{list},
    that is, the set of all sublists of \Mpar{list}. In this context,
    lists are understood as multisets.}

  \eng{\Mthis\Mex{(n)} computes the powerset of the set
    \Mmath{{1,2,...,n}}{\{1,2,\ldots,n\}}.}

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

\begin{MCalls}
  \Mcall{n}
  \Mcall{set}
  \Mcall{list}
\end{MCalls}

\begin{MParameters}
  \param{n}
    \eng{a nonnegative integer}
    \de{}
  \param{set}
    \eng{a set of domain type \Mup{DOM_SET}}
    \de{}
  \param{list}
    \eng{a list of domain type \Mup{DOM_LIST}}
    \de{}
\end{MParameters}

\begin{MReturnValue}
   \eng{A set of domain type \Mup{DOM_SET} which contains the
     computed subsets.}
   \de{}
\end{MReturnValue}

\MOverloading{set}

\MRelatedFunctions{combinat::choose}

\MKeywords{combinatorics}

\begin{MDetails}
  \eng{If the argument of \Mthis\ is a list, it is treated like a
       multiset. This means that sublists that contain the same
       elements the same number of times are treated as equal, even if
       the elements appear in a different order. 
       Cf.\ Example~\ref{ex3}. }
  \de{}
\end{MDetails}


\begin{MExample}{ex1}
  \eng{The powerset of the set \Mex{{a,b,c}}:}
  \de{}
  \begin{Mexin}
combinat::warnDeprecated(FALSE):
combinat::powerset({a, b, c})
  \end{Mexin}
  \begin{Mexout}
    {{}, {a}, {b}, {c}, {a, b}, {a, c}, {b, c}, {a, b, c}}
  \end{Mexout}

  \eng{\Mwarn{The function \Mup{combinat::powerset} is deprecated:}}
  \begin{Mexin}
old_val:=combinat::warnDeprecated(TRUE):
combinat::powerset({a, b, c});
combinat::warnDeprecated(old_val):
  \end{Mexin}
  \begin{Mexout}
Warning: combinat::powerset is obsolete.
Please use 'combinat::subsets' and 'combinat::subwords' instea\
d. [combinat::powerset]

    {{}, {a}, {b}, {c}, {a, b}, {a, c}, {b, c}, {a, b, c}}
  \end{Mexout}
  \eng{Here is the recommended replacement:}
  \begin{Mexin}
combinat::subsets::list({a,b,c})
  \end{Mexin}
  \begin{Mexout}
    [{}, {a}, {b}, {c}, {a, b}, {a, c}, {b, c}, {a, b, c}]
  \end{Mexout}
  \eng{Note that the result is returned as a list.}
\end{MExample}

\begin{MExample}{ex2}
  \eng{The powerset of the set \Mex{\{1,2,3\}}:}
  \begin{Mexin}
combinat::powerset(3)
  \end{Mexin}
  \begin{Mexout}
    {{}, {1}, {2}, {3}, {1, 2}, {1, 3}, {2, 3}, {1, 2, 3}}
  \end{Mexout}
  \eng{Here is the recommended replacement:}
  \begin{Mexin}
combinat::subsets::list(3)
  \end{Mexin}
  \begin{Mexout}
    [{}, {1}, {2}, {3}, {1, 2}, {1, 3}, {2, 3}, {1, 2, 3}]
  \end{Mexout}
\end{MExample}

\begin{MExample}{ex3}
  \eng{Here you can see that lists are treated as multisets. 
       There is no sublist \Mmath{[2, 1]}{[2, 1]} since it is
       identified with the list  
       \Mmath{[1,2]}{[1,2]} which is in the powerset.}
  \begin{Mexin}
combinat::powerset([2, 1, 2])
  \end{Mexin}
  \begin{Mexout}
           {[], [1], [2], [1, 2], [2, 2], [1, 2, 2]}
  \end{Mexout}
  \eng{Here is the recommended replacement:}
  \begin{Mexin}
{op(combinat::subwords::list(sort([2, 1, 2])))}
  \end{Mexin}
  \begin{Mexout}
           {[], [1], [2], [1, 2], [2, 2], [1, 2, 2]}
  \end{Mexout}
\end{MExample}

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

\end{Mhelppage}
