grep {base} | R Documentation

## Pattern Matching and Replacement

### Description

`grep` searches for matches to `pattern` (its first argument) within the character vector `x` (second argument). `regexpr` and `gregexpr` do too, but return more detail in a different format.

`sub` and `gsub` perform replacement of matches determined by regular expression matching.

### Usage

    grep(pattern, x, ignore.case = FALSE, extended = TRUE,
         perl = FALSE, value = FALSE, fixed = FALSE, useBytes = FALSE)

    sub(pattern, replacement, x,
        ignore.case = FALSE, extended = TRUE, perl = FALSE,
        fixed = FALSE, useBytes = FALSE)

    gsub(pattern, replacement, x,
         ignore.case = FALSE, extended = TRUE, perl = FALSE,
         fixed = FALSE, useBytes = FALSE)

    regexpr(pattern, text, extended = TRUE, perl = FALSE,
            fixed = FALSE, useBytes = FALSE)

    gregexpr(pattern, text, extended = TRUE, perl = FALSE,
             fixed = FALSE, useBytes = FALSE)

### Arguments

`pattern` | character string containing a regular expression (or character string for `fixed = TRUE`) to be matched in the given character vector. Coerced to character if possible.
`x, text` | a character vector where matches are sought. Coerced to character if possible.
`ignore.case` | if `FALSE`, the pattern matching is case sensitive and if `TRUE`, case is ignored during matching.
`extended` | if `TRUE`, extended regular expression matching is used, and if `FALSE` basic regular expressions are used.
`perl` | logical. Should perl-compatible regexps be used? Has priority over `extended`.
`value` | if `FALSE`, a vector containing the (`integer`) indices of the matches determined by `grep` is returned, and if `TRUE`, a vector containing the matching elements themselves is returned.
`fixed` | logical. If `TRUE`, `pattern` is a string to be matched as is. Overrides all conflicting arguments.
`useBytes` | logical. If `TRUE` the matching is done byte-by-byte rather than character-by-character. See Details.
`replacement` | a replacement for matched pattern in `sub` and `gsub`. Coerced to character if possible. This can include backreferences `"\1"` to `"\9"` to parenthesized subexpressions of `pattern`. For `perl = TRUE` only, it can also contain `"\U"` or `"\L"` to convert the rest of the replacement to upper or lower case.

### Details

Arguments which should be character strings or character vectors are coerced to character if possible.

The two `*sub` functions differ only in that `sub` replaces only the first occurrence of a `pattern` whereas `gsub` replaces all occurrences.

For `regexpr` it is an error for `pattern` to be `NA`, otherwise `NA` is permitted and matches only itself.

The regular expressions used are those specified by POSIX 1003.2, either extended or basic, depending on the value of the `extended` argument, unless `perl = TRUE` when they are those of PCRE, ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/. (The exact set of patterns supported may depend on the version of PCRE installed on the system in use.)

`useBytes` is only used if `fixed = TRUE` or `perl = TRUE`. For `grep` its main effect is to avoid errors/warnings about invalid inputs, but for `regexpr` it changes the interpretation of the output.

### Value

For `grep` a vector giving either the indices of the elements of `x` that yielded a match or, if `value` is `TRUE`, the matched elements.
For `sub` and `gsub` a character vector of the same length as the original.
For `regexpr` an integer vector of the same length as `text` giving the starting position of the first match, or -1 if there is none, with attribute `"match.length"` giving the length of the matched text (or -1 for no match). In a multi-byte locale these quantities are in characters rather than bytes unless `useBytes = TRUE` is used with `fixed = TRUE` or `perl = TRUE`.
For `gregexpr` a list of the same length as `text` each element of which is an integer vector as in `regexpr`, except that the starting positions of every match are given.
If in a multi-byte locale the pattern or replacement is not a valid sequence of bytes, an error is thrown. An invalid string in `x` or `text` is a non-match with a warning for `grep` or `regexpr`, but an error for `sub` or `gsub`.

### Warning

The standard regular-expression code has been reported to be very slow when applied to extremely long character strings (tens of thousands of characters or more): the code used when `perl = TRUE` seems much faster and more reliable for such usages.

The standard version of `gsub` does not substitute correctly repeated word-boundaries (e.g. `pattern = "\b"`). Use `perl = TRUE` for such matches.

The `perl = TRUE` option is only implemented for single-byte and UTF-8 encodings, and will warn if used in a non-UTF-8 multi-byte locale (unless `useBytes = FALSE`).

### References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole (`grep`)

### See Also

regular expression (aka `regexp`) for the details of the pattern specification.

`agrep` for approximate matching.

`tolower`, `toupper` and `chartr` for character translations. `charmatch`, `pmatch`, `match`. `apropos` uses regexps and has nice examples.

### Examples

    grep("[a-z]", letters)

    txt <- c("arm","foot","lefroo", "bafoobar")
    if(any(i <- grep("foo",txt)))
       cat("'foo' appears at least once in\n\t",txt,"\n")
    i # 2 and 4
    txt[i]

    ## Double all 'a' or 'b's;  "\" must be escaped, i.e., 'doubled'
    gsub("([ab])", "\\1_\\1_", "abc and ABC")

    txt <- c("The", "licenses", "for", "most", "software", "are",
      "designed", "to", "take", "away", "your", "freedom",
      "to", "share", "and", "change", "it.",
       "", "By", "contrast,", "the", "GNU", "General", "Public", "License",
       "is", "intended", "to", "guarantee", "your", "freedom", "to",
       "share", "and", "change", "free", "software", "--",
       "to", "make", "sure", "the", "software", "is",
       "free", "for", "all", "its", "users")
    ( i <- grep("[gu]", txt) ) # indices
    stopifnot( txt[i] == grep("[gu]", txt, value = TRUE) )

    ## Note that in locales such as en_US this includes B as the
    ## collation order is aAbBcCdEe ...
    (ot <- sub("[b-e]",".", txt))
    txt[ot != gsub("[b-e]",".", txt)]#- gsub does "global" substitution

    txt[gsub("g","#", txt) !=
        gsub("g","#", txt, ignore.case = TRUE)] # the "G" words

    regexpr("en", txt)

    gregexpr("e", txt)

    ## trim trailing white space
    str = 'Now is the time      '
    sub(' +$', '', str)  ## spaces only
    sub('[[:space:]]+$', '', str) ## white space, POSIX-style
    sub('\\s+$', '', str, perl = TRUE) ## Perl-style white space

    ## capitalizing
    gsub("(\\w)(\\w*)", "\\U\\1\\L\\2", "a test of capitalizing", perl=TRUE)
    gsub("\\b(\\w)", "\\U\\1", "a test of capitalizing", perl=TRUE)

[Package base version 2.3.1 Index]