\HeaderA{Extract}{Extract or Replace Parts of an Object}{Extract}
\aliasA{\$}{Extract}{.Rdol.}
\aliasA{\$<\Rdash}{Extract}{.Rdol.<.Rdash.}
\aliasA{Subscript}{Extract}{Subscript}
\aliasA{[}{Extract}{[}
\aliasA{[<\Rdash}{Extract}{[<.Rdash.}
\aliasA{[[}{Extract}{[[}
\aliasA{[[<\Rdash}{Extract}{[[<.Rdash.}
\keyword{array}{Extract}
\keyword{list}{Extract}
\begin{Description}\relax
Operators acting on vectors, arrays and lists to extract or
replace subsets.
\end{Description}
\begin{Usage}
\begin{verbatim}
x[i]
x[i, j, ... , drop = TRUE]
x[[i]]
x[[i, j, ...]]
x$name
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] object from which to extract elements or in which to replace elements.

\item[\code{i, j, ..., name}] indices specifying elements to extract or replace.  \code{i, j} are
\code{numeric} or \code{character} or empty whereas \code{name} must be
character or an (unquoted) name.  Numeric values are coerced to
integer as by \code{\LinkA{as.integer}{as.integer}}.  For \code{[[} and \code{\$}
character strings are normally partially matched to the names of the
object if exact matching does not succeed.

For \code{[}-indexing only: \code{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, \code{i} can be a (single) matrix with as many
columns as there are dimensions of \code{x}; the result is then a
vector with elements corresponding to the sets of indices in each
row of \code{i}.

\code{i, j, ...} can also be negative integers, indicating
elements/slices to leave out of the selection.

\item[\code{drop}] For matrices, and arrays.  If \code{TRUE} the
result is coerced to the lowest possible dimension (see examples
below). This only works for extracting elements, not for the
replacement forms.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
These operators are generic.  You can write methods to handle subsetting
of specific classes of objects, see \LinkA{InternalMethods}{InternalMethods} as well as
\code{\LinkA{[.data.frame}{[.data.frame}} and \code{\LinkA{[.factor}{[.factor}}.  The
descriptions here apply only to the default methods.

The most important distinction between \code{[}, \code{[[} and
\code{\$} is that the \code{[} can select more than one element whereas
the other two select a single element.  \code{\$} does not allow
computed indices, whereas \code{[[} does.  \code{x\$name} is equivalent
to \code{x[["name"]]} if \code{x} is recursive
(see \code{\LinkA{is.recursive}{is.recursive}}) and \code{NULL} otherwise.

The \code{[[} operator requires all relevant subscripts to be supplied.
With the \code{[} 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 \code{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 \code{\LinkA{factor}{factor}}) and not by the character
values which are printed (for which use \code{[as.character(i)]}).

When operating on a list, the \code{[[} operator gives the specified
element of the list while the \code{[} operator returns a list with
the specified element(s) in it.

As from \R{} 1.7.0 \code{[[} can be applied recursively to lists, so
that if the single index \code{i} is a vector of length \code{p},
\code{alist[[i]]} is equivalent to \code{alist[[i1]]...[[ip]]}
providing all but the final indexing results in a list.

The operators \code{\$} and \code{\$<-} 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 \code{\$<-} is applied to a \code{NULL} \code{x}, it first coerces
\code{x} to \code{list()}.  This is what also happens with \code{[[<-}
if the replacement value \code{value} is of length greater than one:
if \code{value} has length 1 or 0, \code{x} is first coerced to a
zero-length vector of the type of \code{value}.

As from \R{} 1.9.0 both \code{\$} and \code{[[} 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 \code{get(i, env=x,
    inherits=FALSE)}.  If no match is found then \code{NULL} is
returned.  The assignment versions, \code{\$<-} and
\code{[[<-}, can also be used.  Again, only character arguments are
allowed and no partial matching is done.  The semantics in this case
are those of \code{assign(i, value, env=x, inherits=FALSE)}.  Such an
assignment will either create a new binding or change the existing
binding in \code{x}.

Negative indices are not allowed in index matrices. \code{NA} and zero
values are allowed: rows of an index matrix containing a zero are
ignored, whereas rows containing an \code{NA} produce an \code{NA} in
the result.
\end{Details}
\begin{Section}{NAs in indexing}
When subscripting, a numerical, logical or character \code{NA} picks
an unknown element and so returns \code{NA} in the corresponding
element of a logical, integer, numeric, complex or character result,
and \code{NULL} for a list.

When replacing (that is using subscripting on the lhs of an
assignment) \code{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).
\end{Section}
\begin{Section}{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 \code{m[j=2,i=1]} is equivalent to \code{m[2,1]} and
\strong{not} \code{m[1,2]}.

This may not be true for methods defined for them; for example it is
not for the \code{data.frame} methods described in
\code{\LinkA{[.data.frame}{[.data.frame}}.

To avoid confusion, do not name index arguments
(but \code{drop} must be named).
\end{Section}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{list}{list}}, \code{\LinkA{array}{array}}, \code{\LinkA{matrix}{matrix}}.

\code{\LinkA{[.data.frame}{[.data.frame}} and \code{\LinkA{[.factor}{[.factor}} for the
behaviour when applied to data.frame and factors.

\code{\LinkA{Syntax}{Syntax}} for operator precedence, and the
\emph{R Language} reference manual about indexing details.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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)
\end{ExampleCode}
\end{Examples}

