\Header{grep}{Pattern Matching and Replacement}
\alias{sub}{grep}
\alias{gsub}{grep}
\keyword{character}{grep}
\keyword{utilities}{grep}
\begin{Usage}
\begin{verbatim}
grep(pattern, x, ignore.case=FALSE, extended=TRUE, value=FALSE)
sub(pattern, replacement, x,
        ignore.case=FALSE, extended=TRUE)
gsub(pattern, replacement, x,
        ignore.case=FALSE, extended=TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{pattern}] character string containing a regular expression
to be matched in the vector of character string \texttt{vec}.
\item[\texttt{x}] a vector of character strings where matches are sought.
\item[\texttt{ignore.case}] if \texttt{FALSE}, the pattern matching is
\emph{case sensitive} and if \texttt{TRUE}, case is ignored during matching.
\item[\texttt{extended}] if \texttt{TRUE}, extended regular expression matching
is used, and if \texttt{FALSE} basic regular expressions are used.
\item[\texttt{value}] if \texttt{FALSE}, a vector containing the (\texttt{integer}) indices
of the matches determined by \texttt{grep} is returned,
and if \texttt{TRUE}, a vector containing the matching
elements themselves is returned.
\item[\texttt{replacement}] a replacement for matched pattern in
\texttt{sub} and \texttt{gsub}.
\end{ldescription}
\end{Arguments}
\begin{Description}
\texttt{grep} searches for matches to \texttt{pattern} (its first
argument) within the vector \texttt{x} of character strings (second argument).

\texttt{sub} and \texttt{gsub} perform replacement of matches
determined by regular expression matching.
The two functions differ only in that \texttt{sub} replaces only
the first occurence of a \texttt{pattern} whereas \texttt{gsub} replaces
all occurences.

The regular expressions used are those specified by POSIX 1003.2,
either extended or basic, depending on the value of the
\texttt{extended} argument.\end{Description}
\begin{Note}
This function is based on the \emph{regex} regular expression library
written by Henry Spencer of the University of Toronto.\end{Note}
\begin{SeeAlso}
\texttt{\Link{charmatch}}, \texttt{\Link{pmatch}}, \texttt{\Link{match}}.
\texttt{\Link{apropos}} uses regexps and has nice examples.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
grep("[a-z]", letters)

## Double all 'a' or 'b's;  "\bsl{}" must be escaped, i.e. `doubled'
gsub("([ab])", "\bsl{}\bsl{}1_\bsl{}\bsl{}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
all( txt[i] == grep("[gu]", txt, value = TRUE) )
(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
\end{ExampleCode}
\end{Examples}

