\HeaderA{grep}{Pattern Matching and Replacement}{grep}
\aliasA{gregexpr}{grep}{gregexpr}
\aliasA{gsub}{grep}{gsub}
\aliasA{regexpr}{grep}{regexpr}
\aliasA{sub}{grep}{sub}
\keyword{character}{grep}
\keyword{utilities}{grep}
\begin{Description}\relax
\code{grep} searches for matches to \code{pattern} (its first
argument) within the character vector \code{x} (second argument).
\code{regexpr} and \code{gregexpr} do too, but return more detail in
a different format.

\code{sub} and \code{gsub} perform replacement of matches determined
by regular expression matching.
\end{Description}
\begin{Usage}
\begin{verbatim}
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, ignore.case = FALSE, extended = TRUE,
        perl = FALSE, fixed = FALSE, useBytes = FALSE)

gregexpr(pattern, text, ignore.case = FALSE, extended = TRUE,
         perl = FALSE, fixed = FALSE, useBytes = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{pattern}] character string containing a \LinkA{regular expression}{regular expression}
(or character string for \code{fixed = TRUE}) to be matched
in the given character vector.  Coerced by
\code{\LinkA{as.character}{as.character}} to a character string if possible.
\item[\code{x, text}] a character vector where matches are sought, or an
object which can be coerced by \code{as.character} to a character vector.
\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{extended}] if \code{TRUE}, extended regular expression matching
is used, and if \code{FALSE} basic regular expressions are used.
\item[\code{perl}] logical. Should perl-compatible regexps be used?
Has priority over \code{extended}.
\item[\code{value}] if \code{FALSE}, a vector containing the (\code{integer})
indices of the matches determined by \code{grep} is returned, and if
\code{TRUE}, a vector containing the matching elements themselves is
returned.
\item[\code{fixed}] logical.  If \code{TRUE}, \code{pattern} is a string to be
matched as is.  Overrides all conflicting arguments.
\item[\code{useBytes}] logical.  If \code{TRUE} the matching is done
byte-by-byte rather than character-by-character.  See \sQuote{Details}.
\item[\code{replacement}] a replacement for matched pattern in \code{sub} and
\code{gsub}.  Coerced to character if possible.  For \code{fixed =
      FALSE} this can include backreferences \code{"\bsl{}1"} to
\code{"\bsl{}9"} to parenthesized subexpressions of \code{pattern}.  For
\code{perl = TRUE} only, it can also contain \code{"\bsl{}U"} or
\code{"\bsl{}L"} to convert the rest of the replacement to upper or
lower case.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Arguments which should be character strings or character vectors are
coerced to character if possible.

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

For \code{regexpr} it is an error for \code{pattern} to be \code{NA},
otherwise \code{NA} is permitted and gives an \code{NA} match.

The regular expressions used are those specified by POSIX 1003.2,
either extended or basic, depending on the value of the
\code{extended} argument, unless \code{perl = TRUE} when they are
those of PCRE, \url{http://www.pcre.org/}.
(The exact set of patterns supported may depend on the version of
PCRE installed on the system in use if \R{} was configured to use the
system PCRE.)

\code{useBytes} is only used if \code{fixed = TRUE} or \code{perl = TRUE}.
Its main effect is to avoid errors/warnings about invalid inputs and
spurious matches, but for \code{regexpr} it changes the interpretation
of the output.

PCRE only supports caseless matching for a non-ASCII pattern in a
UTF-8 locale (and not for \code{useBytes = TRUE} in any locale).
\end{Details}
\begin{Value}
For \code{grep} a vector giving either the indices of the elements of
\code{x} that yielded a match or, if \code{value} is \code{TRUE}, the
matched elements of \code{x} (after coercion, preserving names but no
other attributes).

For \code{sub} and \code{gsub} a character vector of the same length
and with the same attributes as \code{x} (after possible coercion).
Elements of character vectors \code{x} which are not substituted will
be return unchanged (including any declared encoding).  If
\code{useBytes = FALSE}, either \code{perl = TRUE} or \code{fixed =
    TRUE} and any element of \code{pattern}, \code{replacement} and
\code{x} is declared to be in UTF-8, the result will be in UTF-8.
Otherwise changed elements of the result will be have the encoding
declared as that of the current locale (see \code{\LinkA{Encoding}{Encoding}} if
the corresponding input had a declared encoding and the current locale
is either Latin-1 or UTF-8.

For \code{regexpr} an integer vector of the same length as \code{text}
giving the starting position of the first match, or \eqn{-1}{} if there
is none, with attribute \code{"match.length"} giving the length of the
matched text (or \eqn{-1}{} for no match).  In a multi-byte locale these
quantities are in characters rather than bytes unless
\code{useBytes = TRUE} is used with \code{fixed = TRUE} or
\code{perl = TRUE}.

For \code{gregexpr} a list of the same length as \code{text} each
element of which is an integer vector as in \code{regexpr}, except
that the starting positions of every (disjoint) 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 \code{x}
or \code{text} is a non-match with a warning for \code{grep} or
\code{regexpr}, but an error for \code{sub} or \code{gsub}.
\end{Value}
\begin{Section}{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
\code{perl = TRUE} seems much faster and more reliable for such
usages.

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

The \code{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 \code{useBytes = TRUE}).
\end{Section}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole (\code{grep})
\end{References}
\begin{SeeAlso}\relax
\LinkA{regular expression}{regular expression} (aka \code{\LinkA{regexp}{regexp}}) for the details
of the pattern specification.

\code{\LinkA{glob2rx}{glob2rx}} to turn wildcard matches into regular expressions.

\code{\LinkA{agrep}{agrep}} for approximate matching.

\code{\LinkA{tolower}{tolower}}, \code{\LinkA{toupper}{toupper}} and \code{\LinkA{chartr}{chartr}}
for character translations.
\code{\LinkA{charmatch}{charmatch}}, \code{\LinkA{pmatch}{pmatch}}, \code{\LinkA{match}{match}}.
\code{\LinkA{apropos}{apropos}} uses regexps and has nice examples.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
grep("[a-z]", letters)

txt <- c("arm","foot","lefroo", "bafoobar")
if(length(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)
\end{ExampleCode}
\end{Examples}

