stri_replace_all: Replace Occurrences of a Pattern

Description

These functions replace with the given replacement string every/first/last substring of the input that matches the specified pattern.

Usage

stri_replace_all(str, replacement, ..., regex, fixed, coll, charclass)
stri_replace_first(str, replacement, ..., regex, fixed, coll, charclass)
stri_replace_last(str, replacement, ..., regex, fixed, coll, charclass)
stri_replace(str, replacement, ..., regex, fixed, coll, charclass,
  mode = c("first", "all", "last"))
stri_replace_all_charclass(str, pattern, replacement, merge = FALSE,
  vectorize_all = TRUE)
stri_replace_first_charclass(str, pattern, replacement)
stri_replace_last_charclass(str, pattern, replacement)
stri_replace_all_coll(str, pattern, replacement, vectorize_all = TRUE,
  opts_collator = NULL)
stri_replace_first_coll(str, pattern, replacement, opts_collator = NULL)
stri_replace_last_coll(str, pattern, replacement, opts_collator = NULL)
stri_replace_all_fixed(str, pattern, replacement, vectorize_all = TRUE)
stri_replace_first_fixed(str, pattern, replacement)
stri_replace_last_fixed(str, pattern, replacement)
stri_replace_all_regex(str, pattern, replacement, vectorize_all = TRUE,
  opts_regex = NULL)
stri_replace_first_regex(str, pattern, replacement, opts_regex = NULL)
stri_replace_last_regex(str, pattern, replacement, opts_regex = NULL)

Arguments

str

character vector with strings to search in

replacement

character vector with replacements for matched patterns

...

additional arguments passed to the underlying functions

mode

single string; one of: "first" (the default), "all", "last"

pattern,regex,fixed,coll,charclass

character vector defining search patterns; for more details refer to stringi-search

merge

single logical value; should consecutive matches be merged into one string; stri_replace_all_charclass only

vectorize_all

single logical value; should each occurrence of a pattern in every string be replaced by a corresponding replacement string?; stri_replace_all_* only

opts_collator

a named list with ICU Collator's settings as generated with stri_opts_collator; NULL for default settings; stri_replace_*_coll only

opts_regex

a named list with ICU Regex settings as generated with stri_opts_regex; NULL for default settings; stri_replace_*_regex only

Value

All the functions return a character vector.

Details

By default, all the functions are vectorized over str, pattern, replacement. Then these functions scan the input string for matches of the pattern. Input that is not part of any match is left unchanged; each match is replaced in the result by the replacement string.

However, for stri_replace_all*, if vectorize_all is FALSE, the each substring matching any of the supplied patterns is replaced by a corresponding replacement string. In such a case, the vectorization is over str, and - independently - over pattern and replacement. In other words, this is equivalent to something like for (i in 1:npatterns) str <- stri_replace_all(str, pattern[i], replacement[i]. Note that you must set length(pattern) >= length(replacement).

In case of stri_replace_*_regex, the replacement string may contain references to capture groups (in round parentheses). References are of the form $n, where n is the number of the capture group (their numbering starts from 1). In order to treat the $ character literally, escape it with a backslash.

stri_replace, stri_replace_all, stri_replace_first, and stri_replace_last are convenience functions. They just call stri_replace_*_*, depending on arguments used. Unless you are a very lazy person, please call the underlying functions directly for better performance.

If you would like to get rid of e.g. whitespaces from the start or end of a string, see stri_trim.

Examples

Run this code

stri_replace_all_charclass("aaaa", "[a]", "b", merge=c(TRUE, FALSE))

stri_replace_all_charclass("a\nb\tc   d", "\\p{WHITE_SPACE}", " ")
stri_replace_all_charclass("a\nb\tc   d", "\\p{WHITE_SPACE}", " ", merge=RUE)

s <- "Lorem ipsum dolor sit amet, consectetur adipisicing elit."
stri_replace_all_fixed(s, " ", "#")
stri_replace_all_fixed(s, "o", "0")

stri_replace_all_regex(s, " .*? ", "#")
stri_replace_all_regex(s, "(el|s)it", "1234")
stri_replace_all_regex('abaca', 'a', c('!', '*'))
stri_replace_all_regex('123|456|789', '(\\p{N}).(\\p{N})', '$2-$1')
stri_replace_all_regex(c("stringi R", "REXAMINE", "123"), '( R|R.)', ' r ')

# Compare the results:
stri_replace_all_fixed("The quick brown fox jumped over the lazy dog.",
     c("quick", "brown", "fox"), c("slow",  "black", "bear"), vectorize_all=TRUE)
stri_replace_all_fixed("The quick brown fox jumped over the lazy dog.",
     c("quick", "brown", "fox"), c("slow",  "black", "bear"), vectorize_all=FALSE)

# Compare the results:
stri_replace_all_fixed("The quicker brown fox jumped over the lazy dog.",
     c("quick", "brown", "fox"), c("slow",  "black", "bear"), vectorize_all=FALSE)
stri_replace_all_regex("The quicker brown fox jumped over the lazy dog.",
     "\\b"%s+%c("quick", "brown", "fox")%s+%"\\b", c("slow",  "black", "bear"), vectorize_all=FALSE)

Run the code above in your browser using DataLab

Get 50% off unlimited learning