% File src/library/base/man/which.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2022 R Core Team
% Distributed under GPL 2 or later

\name{which}
\alias{which}
\alias{arrayInd}
\title{Which indices are TRUE?}
\description{
  Give the \code{TRUE} indices of a logical object, allowing for array
  indices.
}
\usage{
which(x, arr.ind = FALSE, useNames = TRUE)
arrayInd(ind, .dim, .dimnames = NULL, useNames = FALSE)
}
\arguments{
 \item{x}{a \code{\link{logical}} vector or array.  \code{\link{NA}}s
   are allowed and omitted (treated as if \code{FALSE}).}
 \item{arr.ind}{logical; should \bold{arr}ay \bold{ind}ices be returned
   when \code{x} is an array?  Anything other than a single true value
   is treated as false.}

 \item{ind}{integer-valued index vector, as resulting from
   \code{which(x)}.}
 \item{.dim}{\code{\link{dim}(.)} integer vector}
 \item{.dimnames}{optional list of character \code{\link{dimnames}(.)}.
   If \code{useNames} is true, to be used for constructing dimnames for
   \code{arrayInd()} (and hence, \code{which(*, arr.ind=TRUE)}).
   If \code{\link{names}(.dimnames)} is not empty, these are used as
   column names.  \code{.dimnames[[1]]} is used as row names.}
 \item{useNames}{logical indicating if the value of \code{arrayInd()}
   should have (non-null) dimnames at all.}
}
\value{
  If \code{arr.ind == FALSE} (the default), an integer vector,
  or a double vector if \code{x} is a \emph{\link{long vector}}, with
  \code{length} equal to \code{sum(x)}, i.e., to the number of
  \code{TRUE}s in \code{x}.

  Basically, the result is \code{(1:length(x))[x]} in typical cases;
  more generally, including when \code{x} has \code{\link{NA}}'s,
  \code{which(x)} is \code{seq_along(x)[!is.na(x) & x]} plus
  \code{\link{names}} when \code{x} has.

  If \code{arr.ind == TRUE} and \code{x} is an \code{\link{array}} (has
  a \code{\link{dim}} attribute), the result is
  \code{arrayInd(which(x), dim(x), dimnames(x))}, namely a matrix
  whose rows each are the indices of one element of \code{x}; see
  Examples below.
}
\note{
  Unlike most other base \R functions this does not coerce \code{x}
  to logical: only arguments with \code{\link{typeof}} logical are
  accepted and others give an error.
}
\author{Werner Stahel and Peter Holzer (ETH Zurich) proposed the
  \code{arr.ind} option.}
\seealso{\code{\link{Logic}}, \code{\link{which.min}} for the index of
  the minimum or maximum, and \code{\link{match}} for the first index of
  an element in a vector, i.e., for a scalar \code{a}, \code{match(a, x)}
  is equivalent to  \code{min(which(x == a))} but much more efficient.}
\examples{
which(LETTERS == "R")
which(ll <- c(TRUE, FALSE, TRUE, NA, FALSE, FALSE, TRUE)) #> 1 3 7
names(ll) <- letters[seq(ll)]
which(ll)
which((1:12)\%\%2 == 0) # which are even?
which(1:10 > 3, arr.ind = TRUE)

( m <- matrix(1:12, 3, 4) )
div.3 <- m \%\% 3 == 0
which(div.3)
which(div.3, arr.ind = TRUE)
rownames(m) <- paste("Case", 1:3, sep = "_")
which(m \%\% 5 == 0, arr.ind = TRUE)

dim(m) <- c(2, 2, 3); m
which(div.3, arr.ind = FALSE)
which(div.3, arr.ind = TRUE)

vm <- c(m)
dim(vm) <- length(vm) #-- funny thing with  length(dim(...)) == 1
which(div.3, arr.ind = TRUE)
\dontshow{
dimnames(m) <- list(X = c("U", "V"), Z = c("y","z"), three = LETTERS[1:3])
wm <- which(m \%\% 3 == 0, arr.ind = TRUE)
vn <- vm; dimnames(vn) <- list(LETTERS[1:12])
wv <- which(vn \%\% 3 == 0, arr.ind = TRUE)

stopifnot(identical(wv, array(3L*(1:4), dim = c(4, 1),
                              dimnames = list(c("C", "F", "I", "L"), "dim1"))),
          identical(wm, array(c(1:2, 1:2, 2:1, 1:2, 1:3, 3L),
                              dim = 4:3,
                              dimnames = list(rep(c("U","V"),2),
                                              c("X", "Z", "three"))))
)
}%dont
}
\keyword{logic}
\keyword{attribute}