% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/character.r
\name{sub-wrappers}
\alias{sub-wrappers}
\alias{subf}
\alias{subi}
\alias{gsubf}
\alias{gsubi}
\title{Pattern Replacement Wrappers}
\usage{
subf(pattern, replacement, x, useBytes = FALSE)

subi(pattern, replacement, x, perl = FALSE, useBytes = FALSE)

gsubf(pattern, replacement, x, useBytes = FALSE)

gsubi(pattern, replacement, x, perl = FALSE, useBytes = FALSE)
}
\arguments{
\item{pattern}{character string containing a regular expression (or character string
for \code{fixed = TRUE} to be matched in the given character vector.
Coerced by \link{as.character} to a character string if possible.
If a character vector of length \code{2} or more is supplied, the first
element is used with a warning. Missing values are allowed.}

\item{replacement}{a replacement for the matched pattern in sub and gsub. Coerced
to character if possible. For \code{fixed = FALSE} this can include
backreferences \code{"\\1"} to \code{"\\9"} to parenthesized subexpressions
of pattern. For \code{perl = TRUE} only, it can also contain \code{"\\U"}
or \code{"\\L"} to convert the rest of the replacement to upper or
lower case and \code{"\\E"} to end case conversion. If a character
vector of length 2 or more is supplied, the first element is
used with a warning. If NA, all elements in the result
corresponding to matches will be set to \code{NA}.}

\item{x}{a character vector where matches are sought, or an object
which can be coerced by \link{as.character} to a character vector.
Long vectors are supported.}

\item{useBytes}{logical. If \code{TRUE} the matching is done byte-by-byte rather
than character-by-character.}

\item{perl}{logical. Should Perl-compatible regexps be used?}
}
\value{
a character vector of the same length and with the same attributes
as \code{x} (after possible coercion to character). Elements of
character vectors \code{x} which are not substituted will be returned
unchanged (including any declared encoding if \code{useBytes = FALSE}).
If \code{useBytes = FALSE} a non-ASCII substituted result will often be
in UTF-8 with a marked encoding (e.g., if there is a UTF-8 input,
and in a multibyte locale unless \code{fixed = TRUE}). Such strings can
be re-encoded by \code{\link{enc2native}}. If any of the inputs is marked as
"bytes", elements of character vectors \code{x} which are substituted
will be returned marked as "bytes", but the encoding flag on
elements not substituted is unspecified (it may be the original or
"bytes"). If none of the inputs is marked as "bytes", but
\code{useBytes = TRUE} is given explicitly, the encoding flag is
unspecified even on the substituted elements (it may be "bytes" or
"unknown", possibly invalid in the current encoding). Mixed use of
"bytes" and other marked encodings is discouraged, but if still
desired one may use \code{\link{iconv}} to re-encode the result e.g. to UTF-8
with suitably substituted invalid bytes.
}
\description{
Strongly typed wrappers around \code{\link{sub}} and \code{\link{gsub}} that have the
\code{fixed} and \code{ignore.case} arguments set internally (as well as
the conflicting arguments).
}
\details{
\verb{*f()} suffixed functions have \code{fixed = TRUE} and conflicting
arguments (\code{perl} and \code{ignore.case}) set as \code{FALSE}.

\verb{*i()} suffixed functions have \code{ignore.case = TRUE} and the
conflicting \code{fixed} argument set as \code{FALSE}.

For full documentation of the wrapped functions, see the help
pages for \code{\link{grep}}.
}
\examples{
subf("foo", "X", c("foo", "Foo", "bar"))
subi("foo", "X", c("foo", "Foo", "bar"))

gsubf("foo", "X", c("foo foo", "Foo", "bar"))
gsubi("foo", "X", c("foo foo", "Foo", "bar"))
}
\seealso{
Other pattern-match-replacement-wrappers:
\code{\link{grep-wrappers}},
\code{\link{grepl-wrappers}},
\code{\link{grepv-wrappers}}
}
\concept{pattern-match-replacement-wrappers}
