\HeaderA{match.arg}{Argument Verification Using Partial Matching}{match.arg}
\keyword{programming}{match.arg}
\begin{Description}\relax
\code{match.arg} matches \code{arg} against a table of candidate
values as specified by \code{choices}, where \code{NULL} means to take
the first one.
\end{Description}
\begin{Usage}
\begin{verbatim}
match.arg(arg, choices, several.ok = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{arg}] a character vector (of length one unless \code{several.ok}
is \code{TRUE}) or \code{NULL}.
\item[\code{choices}] a character vector of candidate values
\item[\code{several.ok}] logical specifying if \code{arg} should be allowed
to have more than one element.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
In the one-argument form \code{match.arg(arg)}, the choices are
obtained from a default setting for the formal argument \code{arg} of
the function from which \code{match.arg} was called.  (Since default
argument matching will set \code{arg} to \code{choices}, this is
allowed as an exception to the \sQuote{length one unless
\code{several.ok} is \code{TRUE}} rule, and returns the first
element.)

Matching is done using \code{\LinkA{pmatch}{pmatch}}, so \code{arg} may be
abbreviated.
\end{Details}
\begin{Value}
The unabbreviated version of the exact or unique partial match if
there is one; otherwise, an error is signalled if \code{several.ok} is
false, as per default.  When \code{several.ok} is true and more than
one element of \code{arg} has a match, all unabbreviated versions of
matches are returned.
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{pmatch}{pmatch}},
\code{\LinkA{match.fun}{match.fun}},
\code{\LinkA{match.call}{match.call}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(stats)
## Extends the example for 'switch'
center <- function(x, type = c("mean", "median", "trimmed")) {
  type <- match.arg(type)
  switch(type,
         mean = mean(x),
         median = median(x),
         trimmed = mean(x, trim = .1))
}
x <- rcauchy(10)
center(x, "t")       # Works
center(x, "med")     # Works
try(center(x, "m"))  # Error
stopifnot(identical(center(x),       center(x, "mean")),
          identical(center(x, NULL), center(x, "mean")) )

## Allowing more than one match:
match.arg(c("gauss", "rect", "ep"),
          c("gaussian", "epanechnikov", "rectangular", "triangular"),
          several.ok = TRUE)
\end{ExampleCode}
\end{Examples}

