% $Id: composition.tex,v 1.1.1.1 2003/09/15 16:37:33 nthiery Exp $
\begin{Mhelppage}{composition}{Torsten Metzner}[ImplState=stable,TestState=stable,DocState=deprecated]
\begin{MInfo}
  \eng{$k$-composition of an integer (deprecated)}
  \de{$k$-Komposition einer ganzen Zahl}
\end{MInfo}

\Mproofread{stefanw}{5.6.00}{fertig}

\begin{MIntro}
  \eng{\Mthis\ computes a list of all distinct ordered $k$-tuples 
    \Mmath{(k\_1, ..., k\_n)}{(k_1, \ldots, k_n)}
    such that \Mmath{n\_1 + ... + n\_k = n}{\sum_{i=1}^k n_i = n} and
    \Mmath{n\_i >= 1, i=1..k}{n_i \ge 1, i=1\ldots k}.}
\end{MIntro}

\begin{MCalls}
  \Mcall{{n},{k}}
\end{MCalls}

\begin{MParameters}
  \param{n, k}
    \eng{integer}
\end{MParameters}

\begin{MReturnValue}
   \eng{A list of type \Mup{DOM_LIST} containing
   every computed $k$-tuple also as a list of type \Mup{DOM_LIST}. If there
   exist no $k$-tuple the empty list is returned.} 
\end{MReturnValue}

\MKeywords{combinatorics}

\begin{MDetails}
  \eng{\Mthis\Mex{(n, k)} returns an empty list if $n<1$ or
    $k<1$ or $n<k$.}%
\end{MDetails}

\begin{MExample}{composit-ex1}
  \eng{How can one write $5$ as a sum of two other positive integers?}
  \begin{Mexin}
combinat::warnDeprecated(FALSE):
combinat::composition(5,2)
  \end{Mexin}
  \begin{Mexout}
               [[1, 4], [2, 3], [3, 2], [4, 1]]
  \end{Mexout}

  \eng{\Mwarn{The function \Mup{combinat::composition} is deprecated:}}
  \begin{Mexin}
old_val:=combinat::warnDeprecated(TRUE):
combinat::composition(5,2);
combinat::warnDeprecated(old_val):
  \end{Mexin}
  \begin{Mexout}
Warning: combinat::composition(n,k) is obsolete.
Please use 'combinat::integerVector::list(n,k, MinPart=1)' ins\
tead. [combinat::composition]

               [[1, 4], [2, 3], [3, 2], [4, 1]]
  \end{Mexout}
  \eng{Here is the recommended replacement:}
  \begin{Mexin}
combinat::integerVectors::list(5,2, MinPart=1)
  \end{Mexin}
  \begin{Mexout}
               [[4, 1], [3, 2], [2, 3], [1, 4]]
  \end{Mexout}
  \eng{Note that the order is changed.}
\end{MExample}

\begin{MExample}{composit-ex2}
  \eng{There is no way to write $2$ as the sum of $5$ positive integers:}
  \begin{Mexin}
combinat::composition(2,5) 
  \end{Mexin}
  \begin{Mexout}
                              []
  \end{Mexout}
  \eng{Here is the recommended replacement:}
  \begin{Mexin}
combinat::integerVectors::list(2,5, MinPart=1)
  \end{Mexin}
  \begin{Mexout}
                              []
  \end{Mexout}
\end{MExample}

\begin{MExample}{composit-ex3}
  \eng{\Mthis\ does not handle symbolic expressions.}
  \begin{Mexin}
combinat::composition(xx,2) 
  \end{Mexin}
  \begin{Mexout}
Error: Wrong type of 1. argument (type 'Type::NonNegInt' expec\
ted,
       got argument 'xx');
during evaluation of 'combinat::composition'
  \end{Mexout}
\end{MExample}

%% \begin{MBackground}
%%    \eng{}
%%    \de{}
%% \end{MBackground}

\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::integerVectors}. The
    emission of a warning can be controlled with
    \Mupc{combinat::warnDeprecated}{FALSE} or
    \Mupc{combinat::warnDeprecated}{TRUE}.}
\end{MChanges}
\end{Mhelppage}
