

   PPaatttteerrnn MMaattcchhiinngg aanndd RReeppllaacceemmeenntt

        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)

   AArrgguummeennttss::

    pattern: character string containing a regular expression
             to be matched in the vector of character string
             `vec'.

          x: a vector of character strings where matches are
             sought.

   ignore.case: if `FALSE', the pattern matching is case sensi-
             tive and if `TRUE', case is ignored during match-
             ing.

   extended: if `TRUE', extended regular expression matching is
             used, and if `FALSE' basic regular expressions are
             used.

      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.

   replacement: a replacement for matched pattern in `sub' and
             `gsub'.

   DDeessccrriippttiioonn::

        `grep' searches for matches to `pattern' (its first
        argument) within the vector `x' of character strings
        (second argument).

        `sub' and `gsub' perform replacement of matches deter-
        mined by regular expression matching.  The two func-
        tions differ only in that `sub' replaces only the first
        occurence of a `pattern' whereas `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 `extended' argument.

   NNoottee::

        This function is based on the regex regular expression
        library written by Henry Spencer of the University of
        Toronto.

   SSeeee AAllssoo::

        `charmatch', `pmatch', `match'.

   EExxaammpplleess::

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

        ## 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
        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

