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

\item[\code{i, j, ...}] indices specifying elements to extract or replace.  Indices are
\code{numeric} or \code{character} vectors or empty (missing) or
\code{NULL}.  Numeric values are coerced to integer as by
\code{\LinkA{as.integer}{as.integer}} (and hence truncated towards zero).  For
extraction with \code{[[}, character vectors will be partially
matched to the \code{\LinkA{names}{names}} of the object based on the value
of the \code{exact} argument (also see under Environments).

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.  \code{i, j,
      ...} can also be negative integers, indicating elements/slices
to leave out of the selection.

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

An index value of \code{NULL} is treated as if it were \code{integer(0)}.

\item[\code{name}] A literal character string or a \LinkA{name}{name} (possibly \LinkA{backtick}{backtick}
quoted).  For extraction, this is normally (see under Environments)
partially matched to the \code{\LinkA{names}{names}} of the object.

\item[\code{drop}] For matrices and arrays.  If \code{TRUE} the result is
coerced to the lowest possible dimension (see the examples).  This
only works for extracting elements, not for the replacement.

\item[\code{exact}] Controls partial matching of \code{[[} when indexing with
character vectors.  The default value, \code{NA}, allows partial
matching, but issues a warning when it occurs.  When \code{TRUE}, no
partial matching is performed.  When \code{FALSE}, partial matching
is allowed and no warning is issued when it occurs.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
These operators are generic.  You can write methods to handle indexing
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.  Note that
separate methods are required for the replacement functions
\code{[<-}, \code{[[<-} and \code{\$<-} for use when indexing occurs on
the assignment side of an expression.

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.

The default methods work somewhat differently for atomic vectors,
matrices/arrays and for recursive (list-like, see
\code{\LinkA{is.recursive}{is.recursive}}) objects.  \code{\$} returns \code{NULL}
(with a warning) except 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.

Subsetting (except by an empty index) will drop all attributes except
\code{names}, \code{dim} and \code{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
\emph{subassignment}) then that part of \code{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 \code{names}, \code{dim} and \code{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.
\end{Details}
\begin{Section}{Atomic vectors}
The usual form of indexing is \code{"["}.  \code{"[["} can be used to
select a single element, but \code{"["} can also do so (but will not
partially match a character index).

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

An empty index selects all values: this is most often used to replace
all the entries but keep the \code{\LinkA{attributes}{attributes}}.
\end{Section}
\begin{Section}{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 \code{x} is one-dimensional
when it will be a one-dimensional array.

The most common form of indexing a \eqn{k}{}-dimensional array is to
specify \eqn{k}{} indices to \code{[}.  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 \code{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.  \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.

A vector obtained by matrix indexing will be unnamed unless \code{x}
is one-dimensional when the row names (if any) will be indexed to
provide names for the result.
\end{Section}
\begin{Section}{Recursive (list-like) objects}
Indexing by \code{[} is similar to atomic vectors and selects a list
of the specified element(s).

Both \code{[[} and \code{\$} select a single element of the list.  The
main difference is that \code{\$} does not allow computed indices,
whereas \code{[[} does.  \code{x\$name} is equivalent to
\code{x[["name", exact = FALSE]]}.  Also, the partial matching
behavior of \code{[[} can be controlled using the \code{exact} argument.

\code{[} and \code{[[} are sometimes applied to other recursive
objects such as \LinkA{call}{call}s and \LinkA{expression}{expression}s.  Pairlists are
coerced to lists for extraction by \code{[}, but all three operators
can be used for replacement.

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

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}.
\end{Section}
\begin{Section}{Environments}
Both \code{\$} and \code{[[} can be applied to environments.  Only
character indices are allowed and no partial matching is done. The
semantics of these operations are those of \code{get(i, env=x,
    inherits=FALSE)}.  If no match is found then \code{NULL} is
returned.  The replacement versions, \code{\$<-} and \code{[[<-}, can
also be used.  Again, only character arguments are allowed.  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}.
\end{Section}
\begin{Section}{NAs in indexing}
When extracting, a numerical, logical or character \code{NA} index 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.  (It returns \code{00} for a raw result.]

When replacing (that is using indexing 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, 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} to \code{m[1,2]}.

This may not be true for methods defined for them; for example it is
not true 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} and
\code{exact} must be named).
\end{Section}
\begin{Section}{S4 methods}
These operators are also S4 generic, but as primitives, S4 methods
will be dispatched only on S4 objects.

S4 methods for \code{\$} will be passed \code{name} as a character
vector: despite the message given by \code{getGeneric("\$")} you cannot
usefully write methods based on the class of \code{name}.
\end{Section}
\begin{Note}\relax
S uses partial matching when extracting by \code{[}
(Becker \emph{et al} p. 358) whereas \R{} does not.

The documented behaviour of S is that an \code{NA} replacement index
\sQuote{goes nowhere} but uses up an element of \code{value}
(Becker \emph{et al} p. 359).  However, that is not the current
behaviour of S-PLUS.

It is planned that the default for \code{exact} will become
\code{exact=TRUE} in \R{} 2.7.0: partial matching for \code{\$} will
remain the default.
\end{Note}
\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{options}{options}(warnPartialMatchAttr = TRUE)} causes partial
matches in \code{\$name} to give warnings.

\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, 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)
\end{ExampleCode}
\end{Examples}

