\HeaderA{char.expand}{Expand a String with Respect to a Target Table}{char.expand}
\keyword{character}{char.expand}
\begin{Description}\relax
Seeks a unique match of its first argument among the
elements of its second.  If successful, it returns this element;
otherwise, it performs an action specified by the third argument.
\end{Description}
\begin{Usage}
\begin{verbatim}char.expand(input, target, nomatch = stop("no match"))\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{input}] a character string to be expanded.
\item[\code{target}] a character vector with the values to be matched
against.
\item[\code{nomatch}] an \R{} expression to be evaluated in case expansion was
not possible.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This function is particularly useful when abbreviations are allowed in
function arguments, and need to be uniquely expanded with respect to a
target table of possible values.

Inputs with embedded nul bytes will be truncated at the first nul.
\end{Details}
\begin{Value}
A length-one character vector, one of the elements of \code{target}
(unless \code{nomatch} is changed to be a non-error, when it can be a
zero-length character string).
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{charmatch}{charmatch}} and \code{\LinkA{pmatch}{pmatch}} for performing
partial string matching.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
locPars <- c("mean", "median", "mode")
char.expand("me", locPars, warning("Could not expand!"))
char.expand("mo", locPars)
\end{ExampleCode}
\end{Examples}

