Extract
Extract or Replace Parts of an Object
Operators acting on vectors, matrices, arrays and lists to extract or replace parts.
Usage
x[i]
x[i, j, ... , drop = TRUE]
x[[i, exact = TRUE]]
x[[i, j, ..., exact = TRUE]]
x$name
getElement(object, name)
x[i] < value
x[i, j, ...] < value
x[[i]] < value
x$i < value
Arguments
 x, object
 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
orcharacter
vectors or empty (missing) orNULL
. Numeric values are coerced to integer as byas.integer
(and hence truncated towards zero). Character vectors will be matched to thenames
of the object (or for matrices/arrays, thedimnames
): 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 argumenti
can be a matrix with as many columns as there are dimensions ofx
; the result is then a vector with elements corresponding to the sets of indices in each row ofi
.An index value of
NULL
is treated as if it wereinteger(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. Seedrop
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. ValueNA
allows partial matching but issues a warning when it occurs. ValueFALSE
allows partial matching without any warning.  value
 typically an arraylike R object of a similar class as
x
.
Details
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 (listlike, see
is.recursive
) objects. $
is only valid for
recursive objects, and is only discussed in the section below on
recursive objects.
Subsetting (except by an empty index) will drop all attributes except
names
, dim
and dimnames
.
Indexing can occur on the righthandside of an expression for
extraction, or on the lefthandside 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 lefthandside is
coerced as needed to accept the values. For vectors, the answer will
be of the higher of the types of x
and value
in the
hierarchy raw < logical < integer < double < complex < character <
list < expression. 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).
Atomic vectors
The usual form of indexing is [
. [[
can be used to
select a single element dropping names
, whereas
[
keeps them, e.g., in c(abc = 123)[1]
. 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
.
Matrices and arrays
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 onedimensional
when it will be a onedimensional 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. Indexing via a character matrix with one column per dimensions is also
supported if the array has dimension names. As with numeric matrix
indexing, each row of the index matrix selects a single element of the
array. Indices are matched against the appropriate dimension names.
NA
is allowed and will produce an NA
in the result.
Unmatched indices as well as the empty string (""
) are not
allowed and will result in an error. A vector obtained by matrix indexing will be unnamed unless x
is onedimensional when the row names (if any) will be indexed to
provide names for the result.
Recursive (listlike) objects
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. getElement(x, name)
is a version of x[[name, exact = TRUE]]
which for formally classed (S4) objects returns slot(x, name)
,
hence providing access to even more general listlike objects. [
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. Note that in all three kinds of replacement, a value of NULL
deletes the corresponding item of the list. To set entries to
NULL
, you need x[i] < list(NULL)
. 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
zerolength vector of the type of value
.
Environments
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
.
NAs in indexing
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).
(The documented behaviour of S was that an NA
replacement index
‘goes nowhere’ but uses up an element of value
:
Becker et al p.\ifelse{latex}{\out{~}}{ } 359. However, that has not been true of
other implementations.)
Argument matching
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
which warn if i
or j
is named and have undocumented behaviour in that case. To avoid confusion, do not name index arguments (but drop
and
exact
must be named).
S4 methods
These operators are also implicit S4 generics, but as primitives, S4
methods will be dispatched only on S4 objects x
. The implicit generics for the $
and $<
operators do not
have name
in their signature because the grammar only allows
symbols or string constants for the name
argument.
Character indices
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.\ifelse{latex}{\out{~}}{ } 358)), R never uses partial matching when extracting by
[
, and 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(warnPartialMatchDollar = 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.
References
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
See Also
names
for details of matching to names, and
pmatch
for partial matching.
[.data.frame
and [.factor
for the
behaviour when applied to data.frame and factors.
Syntax
for operator precedence, and the
‘R Language Definition’ manual about indexing details.
NULL
for details of indexing null objects.
Examples
library(base)
x < 1:12
m < matrix(1:6, nrow = 2, dimnames = list(c("a", "b"), LETTERS[1:3]))
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 1row matrix
m[,c(TRUE,FALSE,TRUE)]# logical indexing
m[cbind(c(1,2,1),3:1)]# matrix numeric index
ci < cbind(c("a", "b", "a"), c("A", "C", "B"))
m[ci] # matrix character 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
## noninteger indices are truncated:
(i < 3.999999999) # "4" is printed
(1:5)[i] # 3
## named atomic vectors, compare "[" and "[[" :
nx < c(Abc = 123, pi = pi)
nx[1] ; nx["pi"] # keeps names, whereas "[[" does not:
nx[[1]] ; nx[["pi"]]
## 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)
## partial matching  possibly with warning :
stopifnot(identical(li$p, pi))
op < options(warnPartialMatchDollar = TRUE)
stopifnot( identical(li$p, pi), # a warning
inherits(tryCatch (li$p, warning = identity), "warning"))
## revert the warning option:
if(is.null(op[[1]])) op[[1]] < FALSE; options(op)