\HeaderA{agrep}{Approximate String Matching (Fuzzy Matching)}{agrep}
\aliasA{fuzzy matching}{agrep}{fuzzy matching}
\keyword{character}{agrep}
\begin{Description}\relax
Searches for approximate matches to \code{pattern} (the first argument)
within the string \code{x} (the second argument) using the Levenshtein
edit distance.
\end{Description}
\begin{Usage}
\begin{verbatim}
agrep(pattern, x, ignore.case = FALSE, value = FALSE,
      max.distance = 0.1, useBytes = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{pattern}] a non-empty character string to be matched (\emph{not}
a regular expression!).  Coerced by \code{as.character} to a string
if possible.
\item[\code{x}] character vector where matches are sought.  Coerced by
\code{as.character} to a character vector if possible.
\item[\code{ignore.case}] if \code{FALSE}, the pattern matching is \emph{case
sensitive} and if \code{TRUE}, case is ignored during matching.
\item[\code{value}] if \code{FALSE}, a vector containing the (integer)
indices of the matches determined is returned and if \code{TRUE}, a
vector containing the matching elements themselves is returned.
\item[\code{max.distance}] Maximum distance allowed for a match.  Expressed
either as integer, or as a fraction of the \emph{pattern} length (will be
replaced by the smallest integer not less than the corresponding
fraction of the pattern length), or a list with possible components
\describe{
\item[\code{all}:] maximal (overall) distance
\item[\code{insertions}:] maximum number/fraction of insertions
\item[\code{deletions}:] maximum number/fraction of deletions
\item[\code{substitutions}:] maximum number/fraction of
substitutions
}
If \code{all} is missing, it is set to 10\%, the other components
default to \code{all}.  The component names can be abbreviated.

\item[\code{useBytes}] logical. in a multibyte locale, should the comparison
be character-by-chracter (the default) or byte-by-byte.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The Levenshtein edit distance is used as measure of approximateness:
it is the total number of insertions, deletions and substitutions
required to transform one string into another.

The function is a simple interface to the \code{apse} library
developed by Jarkko Hietaniemi (also used in the Perl String::Approx
module), modified to work with multibyte character sets.  To save
space it only supports the first 65536 characters of UTF-8 (where all
the characters for human languages lie).  Note that it can be quite
slow in UTF-8, and \code{useBytes = TRUE} will be much faster.

Inputs with embedded nul bytes will be truncated at the first nul.
\end{Details}
\begin{Value}
Either a vector giving the indices of the elements that yielded a
match, or, if \code{value} is \code{TRUE}, the matched elements (after
coercion, preserving names but no other attributes).
\end{Value}
\begin{Author}\relax
Original version by David Meyer, based on C code by Jarkko Hietaniemi.
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{grep}{grep}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
agrep("lasy", "1 lazy 2")
agrep("lasy", c(" 1 lazy 2", "1 lasy 2"), max = list(sub = 0))
agrep("laysy", c("1 lazy", "1", "1 LAZY"), max = 2)
agrep("laysy", c("1 lazy", "1", "1 LAZY"), max = 2, value = TRUE)
agrep("laysy", c("1 lazy", "1", "1 LAZY"), max = 2, ignore.case = TRUE)
\end{ExampleCode}
\end{Examples}

