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, exact = TRUE]]
     x[[i, j, ..., exact = TRUE]]
     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, ...: indices specifying elements to extract or replace.  Indices
          are 'numeric' or 'character' vectors or empty (missing) or
          'NULL'.  Numeric values are coerced to integer as by
          'as.integer' (and hence truncated towards zero). Character
          vectors will be matched to the 'names' of the object (or for
          matrices/arrays, the 'dimnames'): see 'Character indices'
          below for further details.

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

    name: A literal character string or a name (possibly backtick
          quoted).  For extraction, this is normally (see under
          'Environments') partially matched to the 'names' of the
          object. 

    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.  See
          'drop' for further details. 

   exact: Controls possible partial matching of '[[' when extracting by
          a character vector (for most objects, but see under
          'Environments').  The default is no partial matching.  Value
          'NA' allows partial matching but issues a warning when it
          occurs.  Value 'FALSE' allows partial matching without any
          warning.

_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.  '$' is only valid for recursive objects, and is only
     discussed in the section below on recursive objects.  Its use on
     non-recursive objects was deprecated in R 2.5.0 and removed in R
     2.7.0.

     Subsetting (except by an empty index) will drop all attributes
     except 'names', 'dim' and 'dimnames'.

     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 (known
     as _subassignment_) 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 character indices is done, and the left-hand-side is
     coerced as needed to accept the values.  Attributes are preserved
     (although 'names', 'dim' and 'dimnames' will be adjusted
     suitably).  Subassignment is done sequentially, so if an index is
     specified more than once the latest assigned value for an index
     will result.

     It is an error to apply any of these operators to an object which
     is not subsettable (e.g. a function).

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

     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", exact =
     FALSE]]'.  Also, the partial matching behavior of '[[' can be
     controlled using the 'exact' argument.

     '[' 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 either '[[' or '$' is used for replacement, a value of 'NULL'
     deletes the corresponding item of the 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
     indices 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 replacement
     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, 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' and
     'exact' must be named).

_S_4 _m_e_t_h_o_d_s:

     These operators are also S4 generic, but as primitives, S4 methods
     will be dispatched only on S4 objects.

     S4 methods for '$' will be passed 'name' as a character vector:
     despite the message given by 'getGeneric("$")' you cannot usefully
     write methods based on the class of 'name'.

_C_h_a_r_a_c_t_e_r _i_n_d_i_c_e_s:

     Character indices can in some circumstances be partially matched
     (see 'pmatch') to the names or dimnames of the object being
     subsetted (but never for subassignment).  Unlike S (Becker _et al_
     p. 358)), R has never used partial matching when extracting by
     '[', and as from R 2.7.0 partial matching is not by default used
     by '[[' (see argument 'exact').

     Thus the default behaviour is to use partial matching only when
     extracting from recursive objects (except environments) by '$'.
     Even in that case, warnings can be switched on by
     'options(warnPartialMatchAttr = TRUE)'.

     Neither empty ('""') nor 'NA' indices match any names, not even
     empty nor missing names.  If any object has no names or
     appropriate dimnames, they are taken as all '""' and so match
     nothing.

_N_o_t_e:

     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 has not been true of other
     implementations.

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

     'names' for details of matching to names, and 'pmatch' for partial
     matching.

     '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, nrow=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)