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, matrices, arrays and lists to extract
     or replace parts.

_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 element(s) or in which to
          replace element(s). 

i, j, ..., name: indices specifying elements to extract or replace. 
          'i, j' are 'numeric' or 'character' vectors or empty
          (missing) or 'NULL' whereas 'name' must be a character string
          or an (unquoted or backtick quoted) name.  Numeric values are
          coerced to integer as by 'as.integer'.  For extraction with
          '[[' and '$' character strings are normally (see under
          Environments) 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. 'i,
          j, ...' can also be negative integers, indicating
          elements/slices to leave out of the selection.

          When indexing arrays by '[' a single argument 'i' can be a
          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'.

          An index value of 'NULL' is treated as if it were
          'integer(0)'. 

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

_D_e_t_a_i_l_s:

     These operators are generic.  You can write methods to handle
     indexing of specific classes of objects, see InternalMethods as
     well as '[.data.frame' and '[.factor'.  The descriptions here
     apply only to the default methods.  Note that separate methods are
     required for the replacement functions '[<-', '[[<-' and '$<-' for
     use when indexing occurs on the assignment side of an expression.

     The most important distinction between '[', '[[' and '$' is that
     the '[' can select more than one element whereas the other two
     select a single element.

     The default methods work somewhat differently for atomic vectors,
     matrices/arrays and for recursive (list-like, see 'is.recursive')
     objects.  '$' returns 'NULL' except for recursive objects, and is
     only discussed in the section below on recursive objects.

     Indexing can occur on the right-hand-side of an expression for
     extraction, or on the left-hand-side for replacement. When an
     index expression 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.  In this case no partial matching of indices is done. 
     The left-hand-side is coerced as needed to accept the values.

_A_t_o_m_i_c _v_e_c_t_o_r_s:

     The usual form of indexing is '"["'.  '"[["' can be used to select
     a single element, but '"["' can also do so (but will not partially
     match a character index).

     The index object 'i' can be numeric, logical, character or empty.
     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)]').

     An empty index selects all values: this is most often used to
     replace all the entries but keep the 'attributes'.

_M_a_t_r_i_c_e_s _a_n_d _a_r_r_a_y_s:

     Matrices and arrays are vectors with a dimension attribute and so
     all the vector forms of indexing can be used with a single index. 
     The result will be an unnamed vector unless 'x' is one-dimensional
     when it will be a one-dimensional array.

     The most common form of indexing a k-dimensional array is to
     specify k indices to '['.  As for vector indexing, the indices can
     be numeric, logical, character, empty or even factor. An empty
     index (a comma separated blank) indicates that all entries in that
     dimension are selected. The argument 'drop' applies to this form
     of indexing.

     A third form of indexing is via a numeric matrix with the one
     column for each dimension: each row of the index matrix then
     selects a single element of the array, and the result is a vector.
      Negative indices are not allowed in the index matrix.  '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.

     A vector obtained by matrix indexing will be unnamed unless 'x' is
     one-dimensional when the row names (if any) will be indexed to
     provide names for the result.

_R_e_c_u_r_s_i_v_e (_l_i_s_t-_l_i_k_e) _o_b_j_e_c_t_s:

     Indexing by '[' is similar to atomic vectors and selects a list of
     the specified element(s).

     Both '[[' and '$' select a single element of the list.  The main
     difference is that '$' does not allow computed indices, whereas
     '[[' does.  'x$name' is equivalent to 'x[["name"]]'.

     '[' and '[[' are sometimes applied to other recursive objects such
     as calls and expressions.  Pairlists are coerced to lists for
     extraction by '[', but all three operators can be used for
     replacement.

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

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

_E_n_v_i_r_o_n_m_e_n_t_s:

     Both '$' and '[[' can be applied to environments.  Only character
     arguments are allowed and no partial matching is done. The
     semantics of these operations are those 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.  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 extracting, a numerical, logical or character 'NA' index
     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.  (It returns '00' for a raw
     result.]

     When replacing (that is using indexing 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* to 'm[1,2]'.

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

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

_N_o_t_e:

     S uses partial matching when extracting by '[' (Becker _et al_ p.
     358) whereas R does not.

     The documented behaviour of S is that an 'NA' replacement index
     'goes nowhere' but uses up an element of 'value' (Becker _et al_
     p. 359).  However, that is not the current behaviour of S-PLUS.

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

