Extract                 package:base                 R Documentation

Extract or Replace Parts of an Object

Description:

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

Usage:

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

     .subset(x, ...)
     .subset2(x, ...)

Arguments:

       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.

Details:

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

     The functions '.subset' and '.subset2' are essentially equivalent
     to the '[' and '[[' operators, except that methods dispatch does
     not take place.  This is to avoid expensive unclassing when
     applying the default method to an object.  They should not
     normally be invoked by end users.

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

References:

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

See Also:

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

Examples:

     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)

