list                  package:base                  R Documentation

_L_i_s_t_s - _G_e_n_e_r_i_c _a_n_d _D_o_t_t_e_d _P_a_i_r_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     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(...)

_A_r_g_u_m_e_n_t_s:

     ...: 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.

_D_e_t_a_i_l_s:

     Most lists in R internally are _Generic Vectors_, whereas
     traditional _dotted pair_ lists (as in LISP) are 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'.

     '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")' methods for
     'as.vector' may be invoked.  'as.list' turns a factor into a list
     of one-element factors.  All attributes will be dropped unless the
     argument already is a list.  (This is inconsistent with functions
     such as 'as.character', 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.  The list is in no particular order (the order depends on
     the order of creation of objects and whether the environment is
     hashed).  No parent environments are searched.  (Objects copied
     are duplicated so this can be an expensive operation.)

     An empty pairlist, 'pairlist()' is the same as 'NULL'.  This is
     different from 'list()'.

     'as.pairlist' is implemented as 'as.vector(x, "pairlist")', and
     hence will dispatch methods for the generic function 'as.vector'.

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

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

     '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.

_E_x_a_m_p_l_e_s:

     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
     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)