\HeaderA{pmatch}{Partial String Matching}{pmatch}
\keyword{character}{pmatch}
\begin{Description}\relax
\code{pmatch} seeks matches for the elements of its first argument
among those of its second.
\end{Description}
\begin{Usage}
\begin{verbatim}
pmatch(x, table, nomatch = NA, duplicates.ok = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] the values to be matched.
\item[\code{table}] the values to be matched against.
\item[\code{nomatch}] the value returned at non-matching or multiply
partially matching positions.
\item[\code{duplicates.ok}] should elements be in \code{table} be used more
than once?
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The behaviour differs by the value of \code{duplicates.ok}. Consider
first the case if this is true.  First exact matches are considered,
and the positions of the first exact matches are recorded. Then unique
partial matches are considered, and if found recorded. (A partial
match occurs if the whole of the element of \code{x} matches the
beginning of the element of \code{table}.)  Finally,
all remaining elements of \code{x} are regarded as unmatched.
In addition, an empty string can match nothing, not even an exact
match to an empty string.  This is the appropriate behaviour for
partial matching of character indices, for example.

If \code{duplicates.ok} is \code{FALSE}, values of \code{table} once
matched are excluded from the search for subsequent matches.  This
behaviour is equivalent to the \R{} algorithm for argument
matching, except for the consideration of empty strings (which in
argument matching are matched after exact and partial matching to any
remaining arguments).

\code{\LinkA{charmatch}{charmatch}} is similar to \code{pmatch} with
\code{duplicates.ok} true, the differences being that it
differentiates between no match and an ambiguous partial match,  it
does match empty strings, and it does not allow multiple exact matches.
\end{Details}
\begin{Value}
A numeric vector of integers (including \code{NA} if \code{nomatch =
    NA}) of the same length as \code{x}, giving the indices of the
elements in \code{table} which matched, or \code{nomatch}.
\end{Value}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.

Chambers, J. M. (1998)
\emph{Programming with Data. A Guide to the S Language}.
Springer.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{match}{match}}, \code{\LinkA{charmatch}{charmatch}} and
\code{\LinkA{match.arg}{match.arg}}, \code{\LinkA{match.fun}{match.fun}},
\code{\LinkA{match.call}{match.call}}, for function argument matching etc.,
\code{\LinkA{grep}{grep}} etc for more general (regexp) matching of strings.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
pmatch("", "")                             # returns NA
pmatch("m",   c("mean", "median", "mode")) # returns NA
pmatch("med", c("mean", "median", "mode")) # returns 2

pmatch(c("", "ab", "ab"), c("abc", "ab"), dup=FALSE)
pmatch(c("", "ab", "ab"), c("abc", "ab"), dup=TRUE)
## compare
charmatch(c("", "ab", "ab"), c("abc", "ab"))
\end{ExampleCode}
\end{Examples}

