stri_replace_all {stringi} | R Documentation

## 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, ...,
      opts_fixed = NULL)

    stri_replace_first_fixed(str, pattern, replacement, ..., opts_fixed = NULL)

    stri_replace_last_fixed(str, pattern, replacement, ..., opts_fixed = NULL)

    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
`...` | supplementary arguments passed to the underlying functions, including additional settings for `opts_collator`, `opts_regex`, `opts_fixed`, and so on
`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, opts_fixed, opts_regex` | a named list used to tune up a search engine's settings; see `stri_opts_collator`, `stri_opts_fixed`, and `stri_opts_regex`, respectively; `NULL` for default settings;

### 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 `pattern`s 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. Moreover, `${name}` are used for named capture groups.

`stri_replace`, `stri_replace_all`, `stri_replace_first`, and `stri_replace_last` are convenience functions; they just call `stri_replace_*_*` variants, depending on the arguments used. Using the underlying `stri_replace` functions will result in code running slightly faster.

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

### Value

All the functions return a character vector.

### See Also

Other search_replace: `stri_replace_na`, `stri_trim_both`, `stringi-search`

### Examples

    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=TRUE)

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

    stri_replace_all_fixed(c("1", "NULL", "3"), "NULL", NA)

    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 ')

    ## Not run:
    # named capture groups available since ICU 55
    stri_replace_all_regex("words 123 and numbers 456",
       "(?<numbers>[0-9]+)", "!${numbers}!")

    ## End(Not run)

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

[Package stringi version 1.2.4 Index]