\HeaderA{list}{Lists -- Generic and Dotted Pairs}{list}
\aliasA{alist}{list}{alist}
\aliasA{as.list}{list}{as.list}
\methaliasA{as.list.data.frame}{list}{as.list.data.frame}
\methaliasA{as.list.default}{list}{as.list.default}
\methaliasA{as.list.environment}{list}{as.list.environment}
\aliasA{as.pairlist}{list}{as.pairlist}
\aliasA{is.list}{list}{is.list}
\aliasA{is.pairlist}{list}{is.pairlist}
\aliasA{pairlist}{list}{pairlist}
\keyword{list}{list}
\keyword{manip}{list}
\begin{Description}\relax
Functions to construct, coerce and check for all kinds of \R{} lists.
\end{Description}
\begin{Usage}
\begin{verbatim}
list(...)
pairlist(...)

as.list(x, ...)
## S3 method for class 'environment':
as.list(x, all.names = FALSE, ...)
as.pairlist(x)

is.list(x)
is.pairlist(x)

alist(...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{...}] objects.
\item[\code{x}] object to be coerced or tested.
\item[\code{all.names}] a logical indicating whether to copy all values or
(default) only those whose names do not begin with a dot.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Most lists in \R{} internally are \emph{Generic Vectors}, whereas
traditional \emph{dotted pair} lists (as in LISP) are available
but rarely seen by users (except as \code{\\list\{formals\}} of functions).

The arguments to \code{list} or \code{pairlist} are of the form
\code{value} or \code{tag=value}.  The functions return a list or
dotted pair list composed of its arguments with each value either
tagged or untagged, depending on how the argument was specified.

\code{alist} handles its arguments as if they described function
arguments.  So the values are not evaluated, and tagged arguments with
no value are allowed whereas \code{list} simply ignores them.
\code{alist} is most often used in conjunction with \code{\LinkA{formals}{formals}}.

\code{as.list} attempts to coerce its argument to list type.
For functions, this returns the concatenation of the list of formal
arguments and the function body.  For expressions, the list of
constituent calls is returned.

\code{is.list} returns \code{TRUE} iff its argument
is a \code{list} \emph{or} a \code{pairlist} of \code{length} \eqn{> 0}{}.
\code{is.pairlist} returns \code{TRUE} iff the argument is a pairlist
or \code{NULL} (see below).

\code{is.list} and \code{is.pairlist} are generic: you can write
methods to handle specific classes of objects, see \LinkA{InternalMethods}{InternalMethods}.

The \code{"\LinkA{environment}{environment}"} method for \code{as.list} copies the
name-value pairs (for names not beginning with a dot) from an
environment to a named list.  The user can request that all named
objects are copied.  The list is in no particular order (the order
depends on the order of creation of objects and whether the
environmnent is hashed).  No parent environments are searched.  (Objects
copied are duplicated so this can be an expensive operation.)

An empty pairlist, \code{pairlist()} is the same as \code{NULL}.  This
is different from \code{list()}.
\end{Details}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{vector}{vector}("list", length)} for creation of a list with empty
components; \code{\LinkA{c}{c}}, for concatenation; \code{\LinkA{formals}{formals}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
# create a plotting structure
pts <- list(x=cars[,1], y=cars[,2])
plot(pts)

is.pairlist(.Options)  # a user-level pairlist

## "pre-allocate" an empty list of length 5
vector("list", 5)

# Argument lists
f <- function() x
# Note the specification of a "..." argument:
formals(f) <- al <- alist(x=, y=2+3, ...=)
f
al

## environment->list coercion

e1 <- new.env()
e1$a <- 10
e1$b <- 20
as.list(e1)
\end{ExampleCode}
\end{Examples}

