agrep
Approximate String Matching (Fuzzy Matching)

### Description

Searches for an approximate text pattern matching, as described by a character string or regular expression.

### Usage

    agrep(pattern, x, max.distance = 0.1, costs = NULL,
          ignore.case = FALSE, value = FALSE, fixed = TRUE, useBytes = FALSE)
    agrepl(pattern, x, max.distance = 0.1, costs = NULL,
           ignore.case = FALSE, fixed = TRUE, useBytes = FALSE)

### Arguments

pattern | a non-empty character string specifying the pattern to search for. It is interpreted as a literal sequence of characters if fixed is TRUE (the default). Otherwise, it is interpreted as a regular expression.
x | a vector of character strings in which to search.
max.distance | the maximum allowed match distances. It can be an integer, a fraction, or a list with the following five match distance components.
| match distance component |  | description
| "cost" |  | maximum allowed costs
| "insertions" |  | maximum allowed insertions
| "deletions" |  | maximum allowed deletions
| "substitutions" |  | maximum allowed substitutions
| "all" |  | total errors for all (insertions, deletions, and substitutions)
See the details section for more information.
costs | the integer cost of each inserted, deleted, or substituted character. It can be a numeric vector or a list with partially-matched names "insertions", "deletions", and "substitutions". Unspecified costs default to 1, so the default NULL value means that all three costs ("insertions", "deletions", and "substitutions") are 1.
ignore.case | a logical value. If TRUE, uppercase and lowercase characters are considered equivalent when matching. The default is FALSE.
value | a logical value. If TRUE, agrep returns the matched elements of x. If FALSE (the default), agrep returns the indices of the matched elements of x.
fixed | a logical value. If TRUE (the default), the pattern is represented as a literal sequence of characters. If FALSE, the pattern is represented as a regular expression.
useBytes | a logical value. If TRUE, the x and pattern strings are interpreted as a simple sequence of bytes. If FALSE (the default), the x and pattern strings are interpreted as a simple sequence of characters.

### Details

Approximate pattern matching allows matches to be close to the searched pattern under some measure of closeness.
agrep() uses TRE, a portable POSIX-compliant pattern-matching library that supports approximate (fuzzy) matching. If fixed is FALSE, the pattern is interpreted as a POSIX-extended regular expression, like grep when called with perl=FALSE.
agrep uses the edit-distance measure (also known as the Levenshtein distance) where characters can be inserted, deleted, or substituted in the searched text to get an exact match. Each insertion, deletion, or substitution adds to the distance, or cost, of the match. The cost for each insertion, deletion, or substitution can be set with the costs argument. agrep reports matches that have a total cost lower than the threshold value specified by max.distance.
Match distance components

- If max.distance is given as a single number, the number is assigned to the first match distance component "cost", and the other components are assigned as NA, representing no maximal limitation.
- If max.distance is given as zero, exact matching is done, rather than approximate pattern matching.
- If the match distance component "cost" is not given, it defaults to 0.1, and the default value of the match distance component "all" is assigned to 0.1. The other three components ("insertions", "deletions", and "substitutions") default to the value of the component "all".
- If a match distance component is given as an integer, it specifies the maximum costs, additions, and so on, allowed for a match.
- If a match distance component is given as a fraction between 0 and 1, it is converted to an integer by multiplying by the length of the pattern string, and rounding upwards with ceiling. In addition, a "cost" component between 0 and 1 is multiplied by the maximum costs value.
- If a match distance component is a non-integer greater than 1, it is rounded up with ceiling.

Value

agrep | if value=FALSE, returns a numeric vector indicating which elements of x matched pattern. (The return value numeric(0) indicates that there are no matches). If value=TRUE, returns the matching elements of x. (If the matching elements are not character data, they are converted to character data.)
agrepl | returns a logical vector indicating which elements of x matched pattern. These return values can be used as a subscript to retrieve the matching elements of x.

References
http://laurikari.net/tre, the official TRE website.
Also see http://en.wikipedia.org/wiki/TRE_(computing)
See Also
grep.
Examples

    agrep("life", "a live b")
    agrep("life", c("a live b", "a life b"))
    agrep("life", c("a live b", "a life b"), max = list(sub = 0))
    agrep("lifye", c("a live b", "a life b"), max = list(all = 0.1))
    agrep("lifye", c("a live b", "a life b"), max = list(all = 2))
    agrep("liyfe", c("a live", "A", "a Live"), max = 2)
    agrep("liyfe", c("a live", "A", "a Live"), max = list(all = 0.2))
    agrep("liyfe", c("a live", "A", "a LiVE"), max = 2, value = TRUE)
    agrep("liyfe", c("a live", "A", "a LIVE"), max = 2, ignore.case = TRUE)
    sName <-  c("Alabama", "Alaska", "Arizona", "Arkansas", "California",
                 "Colorado", "Louisiana", "Delaware", "Florida", "Georgia")
    agrep("ia$", sName, value=TRUE, fixed = FALSE)
    ## pattern is interpreted as a regular expression.
    ## returns all names that end in "ia" approximately, it is not equivalent to
    ## grep(), which returns the states that end in "ia" exactly!
    agrep("ia$", sName, value=TRUE, fixed = FALSE, max=0)
    ## with max=0, returns the same values as grep
    agrep("ia$", sName, value=TRUE)
    ## pattern is interpreted as literal character string, the result is also
    ## different from above example.

Package base version 6.1.5-18
Package Index