\HeaderA{combn}{Generate All Combinations of n Elements, Taken m at a Time}{combn}
\keyword{utilities}{combn}
\keyword{iteration}{combn}
\begin{Description}\relax
Generate all combinations of the elements of \code{x} taken \code{m}
at a time.  If \code{x} is a positive integer, returns all
combinations of the elements of \code{seq(x)} taken \code{m} at a
time.  If argument \code{FUN} is not \code{NULL}, applies a function given
by the argument to each point.  If simplify is FALSE,  returns
a list; otherwise returns an \code{\LinkA{array}{array}}, typically a
\code{\LinkA{matrix}{matrix}}.  \code{...} are passed unchanged to the
\code{FUN} function, if specified.
\end{Description}
\begin{Usage}
\begin{verbatim}
combn(x, m, FUN = NULL, simplify = TRUE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] vector source for combinations, or integer \code{n} for
\code{x <- \LinkA{seq}{seq}(n)}.
\item[\code{m}] number of elements to choose.
\item[\code{FUN}] function to be applied to each combination; default
\code{NULL} means the identity, i.e., to return the combination
(vector of length \code{m}).
\item[\code{simplify}] logical indicating if the result should be simplified
to an \code{\LinkA{array}{array}} (typically a \code{\LinkA{matrix}{matrix}}); if
FALSE, the function returns a \code{\LinkA{list}{list}}.  Note that when
\code{simplify = TRUE} as by default, the dimension of the result is
simply determined from \code{FUN(\\emph\{<1st combination>\})}, for
efficiency reasons.  This will badly fail if \code{FUN(u)} is not of
constant length.
\item[\code{...}] optionally, further arguments to \code{FUN}.
\end{ldescription}
\end{Arguments}
\begin{Value}
a \code{\LinkA{list}{list}} or \code{\LinkA{array}{array}} (in nondegenerate cases),
see the \code{simplify} argument above.
\end{Value}
\begin{Author}\relax
Scott Chasalow wrote the original in 1994 for S;
R package \pkg{combinat} and documentation by Vince Carey
\email{stvjc@channing.harvard.edu};
small changes by the R core team, notably to return an array in all
cases of \code{simplify = TRUE}, e.g., for \code{combn(5,5)}.
\end{Author}
\begin{References}\relax
Nijenhuis, A. and Wilf, H.S. (1978)
\emph{Combinatorial Algorithms for Computers and Calculators};
Academic Press, NY.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{choose}{choose}} for fast computation of the \emph{number} of
combinations. \code{\LinkA{expand.grid}{expand.grid}} for creating a data frame from
all combinations of factors or vectors.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
combn(letters[1:4], 2)
(m <- combn(10, 5, min))   # minimum value in each combination
mm <- combn(15, 6, function(x) matrix(x, 2,3))
stopifnot(round(choose(10,5)) == length(m),
          c(2,3, round(choose(15,6))) == dim(mm))

## Different way of encoding points:
combn(c(1,1,1,1,2,2,2,3,3,4), 3, tabulate, nbins = 4)

## Compute support points and (scaled) probabilities for a
## Multivariate-Hypergeometric(n = 3, N = c(4,3,2,1)) p.f.:
# table.mat(t(combn(c(1,1,1,1,2,2,2,3,3,4), 3, tabulate,nbins=4)))
\end{ExampleCode}
\end{Examples}

