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 calls is returned.  'as.list' is generic, and as the
     default method calls 'as.vector(mode="list")' methods for
     'as.vector' may be invoked.  As from R 2.4.0, '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' iff its argument is a 'list' _or_ a
     'pairlist' of 'length' > 0. 'is.pairlist' returns 'TRUE' iff the
     argument is a pairlist or 'NULL' (see below).

     'is.list' and 'is.pairlist' are generic: you can write methods to
     handle specific classes of objects, see InternalMethods.

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

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

_E_x_a_m_p_l_e_s:

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

