| % File src/library/base/man/grepRaw.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2016 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{grepRaw} |
| \title{Pattern Matching for Raw Vectors} |
| \alias{grepRaw} |
| \description{ |
| \code{grepRaw} searches for substring \code{pattern} matches within a |
| raw vector \code{x}. |
| } |
| \usage{ |
| grepRaw(pattern, x, offset = 1L, ignore.case = FALSE, |
| value = FALSE, fixed = FALSE, all = FALSE, invert = FALSE) |
| } |
| \arguments{ |
| \item{pattern}{raw vector containing a \link{regular expression} |
| (or fixed pattern for \code{fixed = TRUE}) to be matched in the |
| given raw vector. Coerced by \code{\link{charToRaw}} to a character |
| string if possible.} |
| \item{x}{a raw vector where matches are sought, or an object which can |
| be coerced by \code{charToRaw} to a raw vector. \link{Long vectors} |
| are not supported.} |
| \item{ignore.case}{if \code{FALSE}, the pattern matching is \emph{case |
| sensitive} and if \code{TRUE}, case is ignored during matching.} |
| \item{offset}{An integer specifying the offset from |
| which the search should start. Must be positive. The beginning of |
| line is defined to be at that offset so \code{"^"} will match there.} |
| \item{value}{logical. Determines the return value: see \sQuote{Value}.} |
| \item{fixed}{logical. If \code{TRUE}, \code{pattern} is a pattern to be |
| matched as is.} |
| \item{all}{logical. If \code{TRUE} all matches are returned, |
| otherwise just the first one.} |
| \item{invert}{logical. If \code{TRUE} return indices or values for |
| elements that do \emph{not} match. Ignored (with a warning) unless |
| \code{value = TRUE}.} |
| } |
| \details{ |
| Unlike \code{\link{grep}}, seeks matching patterns within the raw |
| vector \code{x} . This has implications especially in the \code{all = |
| TRUE} case, e.g., patterns matching empty strings are inherently |
| infinite and thus may lead to unexpected results. |
| |
| The argument \code{invert} is interpreted as asking to return the |
| complement of the match, which is only meaningful for \code{value = |
| TRUE}. Argument \code{offset} determines the start of the search, not |
| of the complement. Note that \code{invert = TRUE} with \code{all = |
| TRUE} will split \code{x} into pieces delimited by the pattern |
| including leading and trailing empty strings (consequently the use of |
| regular expressions with \code{"^"} or \code{"$"} in that case may |
| lead to less intuitive results). |
| |
| Some combinations of arguments such as \code{fixed = TRUE} with |
| \code{value = TRUE} are supported but are less meaningful. |
| } |
| |
| \value{ |
| \code{grepRaw(value = FALSE)} returns an integer vector of the offsets |
| at which matches have occurred. If \code{all = FALSE} then it will be |
| either of length zero (no match) or length one (first matching |
| position). |
| |
| \code{grepRaw(value = TRUE, all = FALSE)} returns a raw vector which |
| is either empty (no match) or the matched part of \code{x}. |
| |
| \code{grepRaw(value = TRUE, all = TRUE)} returns a (potentially |
| empty) list of raw vectors corresponding to the matched parts. |
| } |
| |
| \source{ |
| The TRE library of Ville Laurikari (\url{http://laurikari.net/tre/}) |
| is used except for \code{fixed = TRUE}. |
| } |
| |
| % the `aka' below is for ESS |
| \seealso{ |
| \link{regular expression} (aka \code{\link{regexp}}) for the details |
| of the pattern specification. |
| |
| \code{\link{grep}} for matching character vectors. |
| } |
| \examples{ |
| grepRaw("no match", "textText") # integer(0): no match |
| grepRaw("adf", "adadfadfdfadadf") # 3 - the first match |
| grepRaw("adf", "adadfadfdfadadf", all=TRUE, fixed=TRUE) |
| ## [1] 3 6 13 -- three matches |
| } |
| \keyword{utilities} |