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

\Mproofread{stefanw}{5.6.00}{fertig}

\begin{MIntro}
  \eng{\Mthis(list) computes all the reorderings of the given list
  \Mpar{list}.}

  \eng{\Mthis(n) computes all the reorderings of the
  list \Mmath{[1,2,...,n]}{[1,2,\ldots,n]}.} 
 \de{\large !! Noch keine deutsche Doku vorhanden !!}
\end{MIntro}

\MDeclareOption{\Duplicate}{Duplicate}

\begin{MCalls}
  \Mcall{n}
  \Mcall{list}
  \Mcall{list,\Duplicate}
\end{MCalls}

\begin{MParameters}
  \param{n}
    \eng{a nonnegative integer}
  \param{list}
    \eng{a list}
\end{MParameters}

\begin{MOptions}
  \option{\Duplicate}
    \eng{The result may contain identical lists if there are
    duplicates in the given list \Mpar{list}.} 
\end{MOptions}

\begin{MReturnValue}
   \eng{A list of type \Mup{DOM_LIST} containing
   every reordered list as an element.} 
\end{MReturnValue}

\MKeywords{combinatorics}

\begin{MDetails}
  \eng{Without the option \Mpar{\Duplicate},
  all lists in the result are distinct.}
\end{MDetails}

\begin{MOptionDetails}{\Duplicate}
  \eng{If the given list contains k elements, then the resulting list
  contains \Mmath{k!}{k!} elements, which do not have to
  be  distinct. This means duplicates are not treated differently. Cf. examples
  \ref{ex-noduplicate} and \ref{ex-duplicate}.   }  
\end{MOptionDetails}

\begin{MExample}{ex1}
  \eng{There are exactly two ways of ordering two elements:}
  \begin{Mexin}
combinat::warnDeprecated(FALSE):
combinat::permute([a,b]) 
  \end{Mexin}
  \begin{Mexout}
                       [[a, b], [b, a]]
  \end{Mexout}


  \eng{\Mwarn{The function \Mup{combinat::permute} is deprecated:}}
  \begin{Mexin}
old_val:=combinat::warnDeprecated(TRUE):
combinat::permute([a,b]);
combinat::warnDeprecated(old_val):
  \end{Mexin}
  \begin{Mexout}
Warning: combinat::permute(l) is obsolete.
Please use 'combinat::permutations::list(l)' instead. [combina\
t::permute]

                       [[a, b], [b, a]]
  \end{Mexout}

  \eng{Here is the recommended replacement:}
  \begin{Mexin}
combinat::permutations::list([a,b])
  \end{Mexin}
  \begin{Mexout}
                       [[a, b], [b, a]]
  \end{Mexout}
\end{MExample}

\begin{MExample}{ex2}
  \eng{An integer argument $n$ is equivalent to the list of the first
    $n$ integers.}
  \begin{Mexin}
combinat::permute(3) 
  \end{Mexin}
  \begin{Mexout}
[[1, 2, 3], [1, 3, 2], [2, 1, 3], [2, 3, 1], [3, 1, 2],

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

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

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

\begin{MExample}{ex-noduplicate}
  \eng{By default, one gets all \emph{distinct} reorderings.} 
  \begin{Mexin}
combinat::permute([a,a,b]) 
  \end{Mexin}
  \begin{Mexout}
               [[a, a, b], [a, b, a], [b, a, a]]
  \end{Mexout}

  \eng{Here is the recommended replacement:}
  \begin{Mexin}
combinat::permutations::list([a,a,b])
  \end{Mexin}
  \begin{Mexout}
               [[a, a, b], [a, b, a], [b, a, a]]
  \end{Mexout}
\end{MExample}

\begin{MExample}{ex-duplicate}
  \eng{But if one wants to get a list with duplicated reordered
    entries, this is also possible.}
  \begin{Mexin}
combinat::permute([a,a,b],Duplicate) 
  \end{Mexin}
  \begin{Mexout}
[[a, a, b], [a, b, a], [a, a, b], [a, b, a], [b, a, a],

   [b, a, a]]
  \end{Mexout}

  \eng{Here is the recommended replacement:}
  \begin{Mexin}
combinat::permutations::list([a,a,b], Duplicate)
  \end{Mexin}
  \begin{Mexout}
[[a, a, b], [a, b, a], [a, a, b], [a, b, a], [b, a, a],

   [b, a, a]]
  \end{Mexout}
\end{MExample}

\begin{MExample}{ex4}
  \eng{Sets are not allowed as an argument.}
  \begin{Mexin}
combinat::permute({3,4}) 
  \end{Mexin}
  \begin{Mexout}
Error: Wrong type of 1. argument (type 'Type::Union(Type::NonN\
egInt, DOM_LIST)' expected,
       got argument '{3, 4}');
during evaluation of 'combinat::permute'
  \end{Mexout}
\end{MExample}

\begin{MChanges}
  \version{2.0} 
  \eng[Additional option Duplicate]{In older \mupad{} versions the
  option Duplicate was the default behavior of the function \Mthis().}
  \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::permutations}. The emission
    of a warning can be controlled with
    \Mupc{combinat::warnDeprecated}{FALSE} or
    \Mupc{combinat::warnDeprecated}{TRUE}.}
\end{MChanges}
\end{Mhelppage}
