R: Lists - Generic and Dotted Pairs http://127.0.0.1:13473/library/base/html/list.

html

list {base} R Documentation

Lists Generic and Dotted Pairs

Description

Functions to construct, coerce and check for both kinds of R lists.

Usage

list(...)
pairlist(...)

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

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

alist(...)

Arguments

...
objects, possibly named.

x
object to be coerced or tested.

all.names
a logical indicating whether to copy all values or (default) only those whose names do
not begin with a dot.

sorted
a logical indicating whether the names of the resulting list should be sorted
(increasingly). Note that this is somewhat costly, but may be useful for comparison of
environments.

Details

Almost all lists in R internally are Generic Vectors, whereas traditional dotted pair lists (as in
LISP) remain available but rarely seen by users (except as formals of functions).

The arguments to list or pairlist are of the form value or 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.

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 list simply ignores them.
alist is most often used in conjunction with formals.

1 of 3 16/Sep/2017, 4:54 PM
R: Lists - Generic and Dotted Pairs http://127.0.0.1:13473/library/base/html/list.html

as.list attempts to coerce its argument to a list. For functions, this returns the concatenation of
the list of formal arguments and the function body. For expressions, the list of constituent elements
is returned. as.list is generic, and as the default method calls as.vector(mode = "list") for a
non-list, methods for as.vector may be invoked. as.list turns a factor into a list of one-element
factors. Attributes may be dropped unless the argument already is a list or expression. (This is
inconsistent with functions such as as.character which always drop attributes, and is for
efficiency since lists can be expensive to copy.)

is.list returns TRUE if and only if its argument is a list or a pairlist of length > 0.
is.pairlist returns TRUE if and only if the argument is a pairlist or NULL (see below).

The "environment" method for 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. Unless sorted = TRUE, the list is in no particular order (the order depends on the order of
creation of objects and whether the environment is hashed). No enclosing environments are
searched. (Objects copied are duplicated so this can be an expensive operation.) Note that there is
an inverse operation, the as.environment() method for list objects.

An empty pairlist, pairlist() is the same as NULL. This is different from list(): some but not all
operations will promote an empty pairlist to an empty list.

as.pairlist is implemented as as.vector(x, "pairlist"), and hence will dispatch methods

for the generic function as.vector. Lists are copied element-by-element into a pairlist and the
names of the list used as tags for the pairlist: the return value for other types of argument is
undocumented.

list, is.list and is.pairlist are primitive functions.

References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth &
Brooks/Cole.

See Also

vector("list", length) for creation of a list with empty components; c, for concatenation;
formals. unlist is an approximate inverse to as.list().

plotmath for the use of list in plot annotation.

Examples

require(graphics)

# 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

2 of 3 16/Sep/2017, 4:54 PM
R: Lists - Generic and Dotted Pairs http://127.0.0.1:13473/library/base/html/list.html

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)

[Package base version 3.4.1 Index]

3 of 3 16/Sep/2017, 4:54 PM