1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sub.R
\name{stri_sub_all}
\alias{stri_sub_all}
\alias{stri_sub_all<-}
\alias{stri_sub_replace_all}
\alias{stri_sub_all_replace}
\title{Extract or Replace Multiple Substrings}
\usage{
stri_sub_all(
str,
from = list(1L),
to = list(-1L),
length,
use_matrix = TRUE,
ignore_negative_length = TRUE
)
stri_sub_all(
str,
from = list(1L),
to = list(-1L),
length,
omit_na = FALSE,
use_matrix = TRUE
) <- value
stri_sub_replace_all(..., replacement, value = replacement)
stri_sub_all_replace(..., replacement, value = replacement)
}
\arguments{
\item{str}{character vector}
\item{from}{list of integer vector giving the start indexes; alternatively,
if \code{use_matrix=TRUE}, a list of two-column matrices of type
\code{cbind(from, to)}
(unnamed columns or the 2nd column named other than \code{length})
or \code{cbind(from, length=length)} (2nd column named \code{length})}
\item{to}{list of integer vectors giving the end indexes}
\item{length}{list of integer vectors giving the substring lengths}
\item{use_matrix}{single logical value; see \code{from}}
\item{ignore_negative_length}{single logical value; whether
negative lengths should be ignored or result in missing values}
\item{omit_na}{single logical value; indicates whether missing values
in any of the indexes or in \code{value} leave the part of the
corresponding input string
unchanged [replacement function only]}
\item{value}{a list of character vectors defining the replacement strings
[replacement function only]}
\item{...}{arguments to be passed to \code{stri_sub_all<-}}
\item{replacement}{alias of \code{value} [wherever applicable]}
}
\value{
\code{stri_sub_all} returns a list of character vectors.
Its replacement versions modify the input 'in-place'.
}
\description{
\code{stri_sub_all} extracts multiple substrings from each string.
Its replacement version substitutes (in-place) multiple substrings with the
corresponding replacement strings.
\code{stri_sub_replace_all} (alias \code{stri_sub_all_replace})
is its forward pipe operator-friendly variant, returning
a copy of the input vector.
For extracting/replacing single substrings from/within each string, see
\code{\link{stri_sub}}.
}
\details{
Vectorized over \code{str}, [\code{value}], \code{from} and
(\code{to} or \code{length}). Just like in \code{\link{stri_sub}}, parameters
\code{to} and \code{length} are mutually exclusive.
In one of the simplest scenarios, \code{stri_sub_all(str, from, to)},
the i-th element of the resulting list
generated like \code{stri_sub(str[i], from[[i]], to[[i]])}.
As usual, if one of the inputs is shorter than the others,
recycling rule is applied.
If any of \code{from}, \code{to}, \code{length},
or \code{value} is not a list,
it is wrapped into a list.
If \code{from} consists of a two-column matrix, then these two columns are
used as \code{from} and \code{to}, respectively,
unless the second column is named \code{length}.
Such types of index matrices are generated by
\code{\link{stri_locate_all}}.
If extraction or replacement based on \code{\link{stri_locate_first}}
or \code{\link{stri_locate_last}} is needed, see \code{\link{stri_sub}}.
In the replacement function, the index ranges must be sorted
with respect to \code{from} and must be mutually disjoint.
Negative \code{length} does not result in any altering of the
corresponding input string. On the other hand, in \code{stri_sub_all},
this make the corresponding chunk be ignored,
see \code{ignore_negative_length}, though.
}
\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'))
}
\seealso{
The official online manual of \pkg{stringi} at \url{https://stringi.gagolewski.com/}
Gagolewski M., \pkg{stringi}: Fast and portable character string processing in R, \emph{Journal of Statistical Software} 103(2), 2022, 1-59, \doi{10.18637/jss.v103.i02}
Other indexing:
\code{\link{stri_locate_all_boundaries}()},
\code{\link{stri_locate_all}()},
\code{\link{stri_sub}()}
}
\concept{indexing}
\author{
\href{https://www.gagolewski.com/}{Marek Gagolewski} and other contributors
}
|
