R: Extract or Replace Multiple Substrings

stri_sub_all {stringi} | R Documentation

## Extract or Replace Multiple Substrings

### Description

`stri_sub_all` extracts multiple substrings from each string. Its replacement version substitutes (in-place) multiple substrings with the corresponding replacement strings. `stri_sub_replace_all` (alias `stri_sub_all_replace`) is magrittr's pipe-operator-friendly variant, returning a copy of the input vector.

For extracting/replacing single substrings from/within each string, see `stri_sub`.

### Usage

    stri_sub_all(str, from = list(1L), to = list(-1L), length)

    stri_sub_all(str, from=list(1L), to=list(-1L), length, omit_na=FALSE) <- value

    stri_sub_replace_all(..., replacement, value = replacement)

    stri_sub_all_replace(..., replacement, value = replacement)

### Arguments

`str` | a character vector
`from` | a list of integer vectors giving the start indexes or a list of two-column matrices, each of type `cbind(from, to)`
`to` | a list of integer vectors giving the end indexes
`length` | a list of integer vectors giving the substring lengths
`omit_na` | a single logical value; indicates whether missing values in any of the indexes or in `value` leave the part of the corresponding input string unchanged [replacement function only]
`value` | a list of character vectors defining the replacement strings [replacement function only]
`...` | arguments to be passed to `stri_sub_all<-`
`replacement` | alias of `value` [wherever applicable]

### Details

Vectorized over `str`, [`value`], `from` and (`to` or `length`). Just like in `stri_sub`, parameters `to` and `length` are mutually exclusive.

In one of the simplest scenarios, `stri_sub_all(str, from, to)`, the i-th element of the resulting list is generated by calling, e.g., `stri_sub(str[i], from[[i]], to[[i]])`. As usual, if one of the inputs is of length smaller than the others, recycling rule is applied.

If any of `from`, `to`, `length`, or `value` is not a list, it is wrapped into a list.

`from` can be a list of two-column matrices. In such a case, the two columns play a role of `from` and `to`, respectively. Such types of index matrices are generated by `stri_locate_all`. If extraction or replacement based on `stri_locate_first` or `stri_locate_last` is needed, see `stri_sub`.

In the replacement function, the index ranges must be sorted with respect to `from` are must be mutually disjoint.

### Value

`stri_sub_all` returns a list of character vectors. Its replacement versions return a character vector.

### See Also

Other indexing: `stri_locate_all_boundaries()`, `stri_locate_all()`, `stri_sub()`

### Examples

    x <- c("12 3456 789", "abc", "", NA, "667")
    stri_sub_all(x, stri_locate_all_regex(x, "[0-9]+")) # see stri_extract_all
    stri_sub_all(x, stri_locate_all_regex(x, "[0-9]+", omit_no_match=TRUE))

    stri_sub_all(x, stri_locate_all_regex(x, "[0-9]+", omit_no_match=TRUE)) <- "***"
    print(x)

    stri_sub_replace_all("a b c", c(1, 3, 5), c(1, 3, 5), replacement=c("A", "B", "C"))

[Package stringi version 1.4.6 Index]