Extract                 package:base                 R Documentation

_E_x_t_r_a_c_t _o_r _R_e_p_l_a_c_e _P_a_r_t_s _o_f _a_n _O_b_j_e_c_t

_D_e_s_c_r_i_p_t_i_o_n:

     Operators acting on vectors, arrays and lists to extract or
     replace subsets.

_U_s_a_g_e:

     x[i]
     x[i, j, ... , drop = TRUE]
     x[[i]]
     x[[i, j, ...]]
     x$name

_A_r_g_u_m_e_n_t_s:

       x: object from which to extract elements or in which to replace
          elements. 

i, j, ..., name: indices specifying elements to extract or replace. 
          'i, j' are 'numeric' or 'character' or empty whereas 'name'
          must be character or an (unquoted) name.  Numeric values are
          coerced to integer as by 'as.integer'.  For '[[' and '$'
          character strings are normally partially matched to the names
          of the object if exact matching does not succeed.

          For '['-indexing only: 'i, j, ...' can be logical vectors,
          indicating elements/slices to select.  Such vectors are
          recycled if necessary to match the corresponding extent. 
          When indexing arrays, 'i' can be a (single) matrix with as
          many columns as there are dimensions of 'x'; the result is
          then a vector with elements corresponding to the sets of
          indices in each row of 'i'.

          'i, j, ...' can also be negative integers, indicating
          elements/slices to leave out of the selection. 

    drop: For matrices, and arrays.  If 'TRUE' the result is coerced to
          the lowest possible dimension (see examples below). This only
          works for extracting elements, not for the replacement forms.

_D_e_t_a_i_l_s:

     These operators are generic.  You can write methods to handle
     subsetting of specific classes of objects, see InternalMethods as
     well as '[.data.frame' and '[.factor'.  The descriptions here
     apply only to the default methods.

     The most important distinction between '[', '[[' and '$' is that
     the '[' can select more than one element whereas the other two
     select a single element.  '$' does not allow computed indices,
     whereas '[[' does.  'x$name' is equivalent to 'x[["name"]]' if 'x'
     is recursive (see 'is.recursive') and 'NULL' otherwise.

     The '[[' operator requires all relevant subscripts to be supplied.
     With the '[' operator an empty index (a comma separated blank)
     indicates that all entries in that dimension are selected.

     If one of these expressions appears on the left side of an
     assignment then that part of 'x' is set to the value of the right
     hand side of the assignment.

     Indexing by factors is allowed and is equivalent to indexing by
     the numeric codes (see 'factor') and not by the character values
     which are printed (for which use '[as.character(i)]').

     When operating on a list, the '[[' operator gives the specified
     element of the list while the '[' operator returns a list with the
     specified element(s) in it.

     As from R 1.7.0 '[[' can be applied recursively to lists, so that
     if the single index 'i' is a vector of length 'p', 'alist[[i]]' is
     equivalent to 'alist[[i1]]...[[ip]]' providing all but the final
     indexing results in a list.

     The operators '$' and '$<-' do not evaluate their second argument.
      It is translated to a string and that string is used to locate
     the correct component of the first argument.

     When '$<-' is applied to a 'NULL' 'x', it first coerces 'x' to
     'list()'.  This is what also happens with '[[<-' if the
     replacement value 'value' is of length greater than one: if
     'value' has length 1 or 0, 'x' is first coerced to a zero-length
     vector of the type of 'value'.

     As from R 1.9.0 both '$' and '[[' can be applied to environments. 
     Only character arguments are allowed and no partial matching is
     done (this is in contrast to the behavior for lists). The
     semantics of these operations is basically that of 'get(i, env=x,
     inherits=FALSE)'.  If no match is found then 'NULL' is returned. 
     The assignment versions, '$<-' and '[[<-', can also be used. 
     Again, only character arguments are allowed and no partial
     matching is done.  The semantics in this case are those of
     'assign(i, value, env=x, inherits=FALSE)'.  Such an assignment
     will either create a new binding or change the existing binding in
     'x'.

     Negative indices are not allowed in index matrices. 'NA' and zero
     values are allowed: rows of an index matrix containing a zero are
     ignored, whereas rows containing an 'NA' produce an 'NA' in the
     result.

_N_A_s _i_n _i_n_d_e_x_i_n_g:

     When subscripting, a numerical, logical or character 'NA' picks an
     unknown element and so returns 'NA' in the corresponding element
     of a logical, integer, numeric, complex or character result, and
     'NULL' for a list.

     When replacing (that is using subscripting on the lhs of an
     assignment) 'NA' does not select any element to be replaced.  As
     there is ambiguity as to whether an element of the rhs should be
     used or not (and R handled this inconsistently prior to R 2.0.0),
     this is only allowed if the rhs value is of length one (so the two
     interpretations would have the same outcome).

_A_r_g_u_m_e_n_t _m_a_t_c_h_i_n_g:

     Note that these operations do not match their index arguments in
     the standard way: argument names are ignored and positional
     matching only is used. So 'm[j=2,i=1]' is equivalent to 'm[2,1]'
     and *not* 'm[1,2]'.

     This may not be true for methods defined for them; for example it
     is not for the 'data.frame' methods described in '[.data.frame'.

     To avoid confusion, do not name index arguments (but 'drop' must
     be named).

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

     'list', 'array', 'matrix'.

     '[.data.frame' and '[.factor' for the behaviour when applied to
     data.frame and factors.

     'Syntax' for operator precedence, and the _R Language_ reference
     manual about indexing details.

_E_x_a_m_p_l_e_s:

     x <- 1:12; m <- matrix(1:6,nr=2); li <- list(pi=pi, e = exp(1))
     x[10]                 # the tenth element of x
     x <- x[-1]            # delete the 1st element of x
     m[1,]                 # the first row of matrix m
     m[1, , drop = FALSE]  # is a 1-row matrix
     m[,c(TRUE,FALSE,TRUE)]# logical indexing
     m[cbind(c(1,2,1),3:1)]# matrix index
     m <- m[,-1]           # delete the first column of m
     li[[1]]               # the first element of list li
     y <- list(1,2,a=4,5)
     y[c(3,4)]             # a list containing elements 3 and 4 of y
     y$a                   # the element of y named a

     ## non-integer indices are truncated:
     (i <- 3.999999999) # "4" is printed
     (1:5)[i]  # 3

     ## recursive indexing into lists
     z <- list( a=list( b=9, c='hello'), d=1:5)
     unlist(z)
     z[[c(1, 2)]]
     z[[c(1, 2, 1)]]  # both "hello"
     z[[c("a", "b")]] <- "new"
     unlist(z)

     ## check $ and [[ for environments
     e1 <- new.env()
     e1$a <- 10
     e1[["a"]]
     e1[["b"]] <- 20
     e1$b
     ls(e1)

