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
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/search_subset_4.R
\name{stri_subset}
\alias{stri_subset}
\alias{stri_subset<-}
\alias{stri_subset_fixed}
\alias{stri_subset_fixed<-}
\alias{stri_subset_charclass}
\alias{stri_subset_charclass<-}
\alias{stri_subset_coll}
\alias{stri_subset_coll<-}
\alias{stri_subset_regex}
\alias{stri_subset_regex<-}
\title{Select Elements that Match a Given Pattern}
\usage{
stri_subset(str, ..., regex, fixed, coll, charclass)
stri_subset(str, ..., regex, fixed, coll, charclass) <- value
stri_subset_fixed(
str,
pattern,
omit_na = FALSE,
negate = FALSE,
...,
opts_fixed = NULL
)
stri_subset_fixed(str, pattern, negate=FALSE, ..., opts_fixed=NULL) <- value
stri_subset_charclass(str, pattern, omit_na = FALSE, negate = FALSE)
stri_subset_charclass(str, pattern, negate=FALSE) <- value
stri_subset_coll(
str,
pattern,
omit_na = FALSE,
negate = FALSE,
...,
opts_collator = NULL
)
stri_subset_coll(str, pattern, negate=FALSE, ..., opts_collator=NULL) <- value
stri_subset_regex(
str,
pattern,
omit_na = FALSE,
negate = FALSE,
...,
opts_regex = NULL
)
stri_subset_regex(str, pattern, negate=FALSE, ..., opts_regex=NULL) <- value
}
\arguments{
\item{str}{character vector; strings to search within}
\item{...}{supplementary arguments passed to the underlying functions,
including additional settings for \code{opts_collator}, \code{opts_regex},
\code{opts_fixed}, and so on}
\item{value}{non-empty character vector of replacement strings;
replacement function only}
\item{pattern, regex, fixed, coll, charclass}{character vector;
search patterns (no more than the length of \code{str});
for more details refer to \link{stringi-search}}
\item{omit_na}{single logical value; should missing values be excluded
from the result?}
\item{negate}{single logical value; whether a no-match is rather of interest}
\item{opts_collator, opts_fixed, opts_regex}{a named list used to tune up
the search engine's settings; see
\code{\link{stri_opts_collator}}, \code{\link{stri_opts_fixed}},
and \code{\link{stri_opts_regex}}, respectively; \code{NULL}
for the defaults}
}
\value{
The \code{stri_subset_*} functions return a character vector.
As usual, the output encoding is UTF-8.
The \code{stri_subset_*<-} functions modifies \code{str} 'in-place'.
}
\description{
These functions return or modify a sub-vector where there is a match to
a given pattern. In other words, they
are roughly equivalent (but faster and easier to use) to a call to
\code{str[\link{stri_detect}(str, ...)]} or
\code{str[\link{stri_detect}(str, ...)] <- value}.
}
\details{
Vectorized over \code{str} as well as partially over \code{pattern}
and \code{value},
with recycling of the elements in the shorter vector if necessary.
As the aim here is to subset \code{str}, \code{pattern}
cannot be longer than the former. Moreover, if the number of
items to replace is not a multiple of length of \code{value},
a warning is emitted and the unused elements are ignored.
Hence, the length of the output will be the same as length of \code{str}.
\code{stri_subset} and \code{stri_subset<-} are convenience functions.
They call either \code{stri_subset_regex},
\code{stri_subset_fixed}, \code{stri_subset_coll},
or \code{stri_subset_charclass},
depending on the argument used.
}
\examples{
stri_subset_regex(c('stringi R', '123', 'ID456', ''), '^[0-9]+$')
x <- c('stringi R', '123', 'ID456', '')
`stri_subset_regex<-`(x, '[0-9]+$', negate=TRUE, value=NA) # returns a copy
stri_subset_regex(x, '[0-9]+$') <- NA # modifies `x` in-place
print(x)
}
\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 search_subset:
\code{\link{about_search}}
}
\concept{search_subset}
\author{
\href{https://www.gagolewski.com/}{Marek Gagolewski} and other contributors
}
|
