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: 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 '['-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 coerces 'x' to 'list()'.
      This is what happens with '[[<-' is 'y' is of length greater than
     one: if 'y' has length 1 or 0, 'x' is 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'.

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

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

