", "", NA)
#' str_match(x, "<(.*?)> <(.*?)>")
#' str_match_all(x, "<(.*?)>")
#'
#' str_extract(x, "<.*?>")
#' str_extract_all(x, "<.*?>")
str_match <- function(string, pattern) {
check_lengths(string, pattern)
if (type(pattern) != "regex") {
cli::cli_abort("`pattern` must be a regular expression.")
}
stri_match_first_regex(string,
pattern,
opts_regex = opts(pattern)
)
}
#' @rdname str_match
#' @export
str_match_all <- function(string, pattern) {
check_lengths(string, pattern)
if (type(pattern) != "regex") {
cli::cli_abort("`pattern` must be a regular expression.")
}
stri_match_all_regex(string,
pattern,
omit_no_match = TRUE,
opts_regex = opts(pattern)
)
}
stringr/R/stringr-package.R 0000644 0001762 0000144 00000000276 14316043620 015353 0 ustar ligges users #' @keywords internal
"_PACKAGE"
## usethis namespace: start
#' @import stringi
#' @import rlang
#' @importFrom glue glue
#' @importFrom lifecycle deprecated
## usethis namespace: end
NULL
stringr/R/compat-purrr.R 0000644 0001762 0000144 00000010671 14316043620 014725 0 ustar ligges users # nocov start - compat-purrr (last updated: rlang 0.3.2.9000)
# This file serves as a reference for compatibility functions for
# purrr. They are not drop-in replacements but allow a similar style
# of programming. This is useful in cases where purrr is too heavy a
# package to depend on. Please find the most recent version in rlang's
# repository.
map <- function(.x, .f, ...) {
lapply(.x, .f, ...)
}
map_mold <- function(.x, .f, .mold, ...) {
out <- vapply(.x, .f, .mold, ..., USE.NAMES = FALSE)
names(out) <- names(.x)
out
}
map_lgl <- function(.x, .f, ...) {
map_mold(.x, .f, logical(1), ...)
}
map_int <- function(.x, .f, ...) {
map_mold(.x, .f, integer(1), ...)
}
map_dbl <- function(.x, .f, ...) {
map_mold(.x, .f, double(1), ...)
}
map_chr <- function(.x, .f, ...) {
map_mold(.x, .f, character(1), ...)
}
map_cpl <- function(.x, .f, ...) {
map_mold(.x, .f, complex(1), ...)
}
walk <- function(.x, .f, ...) {
map(.x, .f, ...)
invisible(.x)
}
pluck <- function(.x, .f) {
map(.x, `[[`, .f)
}
pluck_lgl <- function(.x, .f) {
map_lgl(.x, `[[`, .f)
}
pluck_int <- function(.x, .f) {
map_int(.x, `[[`, .f)
}
pluck_dbl <- function(.x, .f) {
map_dbl(.x, `[[`, .f)
}
pluck_chr <- function(.x, .f) {
map_chr(.x, `[[`, .f)
}
pluck_cpl <- function(.x, .f) {
map_cpl(.x, `[[`, .f)
}
map2 <- function(.x, .y, .f, ...) {
out <- mapply(.f, .x, .y, MoreArgs = list(...), SIMPLIFY = FALSE)
if (length(out) == length(.x)) {
set_names(out, names(.x))
} else {
set_names(out, NULL)
}
}
map2_lgl <- function(.x, .y, .f, ...) {
as.vector(map2(.x, .y, .f, ...), "logical")
}
map2_int <- function(.x, .y, .f, ...) {
as.vector(map2(.x, .y, .f, ...), "integer")
}
map2_dbl <- function(.x, .y, .f, ...) {
as.vector(map2(.x, .y, .f, ...), "double")
}
map2_chr <- function(.x, .y, .f, ...) {
as.vector(map2(.x, .y, .f, ...), "character")
}
map2_cpl <- function(.x, .y, .f, ...) {
as.vector(map2(.x, .y, .f, ...), "complex")
}
args_recycle <- function(args) {
lengths <- map_int(args, length)
n <- max(lengths)
stopifnot(all(lengths == 1L | lengths == n))
to_recycle <- lengths == 1L
args[to_recycle] <- map(args[to_recycle], function(x) rep.int(x, n))
args
}
pmap <- function(.l, .f, ...) {
args <- args_recycle(.l)
do.call("mapply", c(
FUN = list(quote(.f)),
args, MoreArgs = quote(list(...)),
SIMPLIFY = FALSE, USE.NAMES = FALSE
))
}
probe <- function(.x, .p, ...) {
if (is_logical(.p)) {
stopifnot(length(.p) == length(.x))
.p
} else {
map_lgl(.x, .p, ...)
}
}
keep <- function(.x, .f, ...) {
.x[probe(.x, .f, ...)]
}
discard <- function(.x, .p, ...) {
sel <- probe(.x, .p, ...)
.x[is.na(sel) | !sel]
}
map_if <- function(.x, .p, .f, ...) {
matches <- probe(.x, .p)
.x[matches] <- map(.x[matches], .f, ...)
.x
}
compact <- function(.x) {
Filter(length, .x)
}
transpose <- function(.l) {
inner_names <- names(.l[[1]])
if (is.null(inner_names)) {
fields <- seq_along(.l[[1]])
} else {
fields <- set_names(inner_names)
}
map(fields, function(i) {
map(.l, .subset2, i)
})
}
every <- function(.x, .p, ...) {
for (i in seq_along(.x)) {
if (!rlang::is_true(.p(.x[[i]], ...))) return(FALSE)
}
TRUE
}
some <- function(.x, .p, ...) {
for (i in seq_along(.x)) {
if (rlang::is_true(.p(.x[[i]], ...))) return(TRUE)
}
FALSE
}
negate <- function(.p) {
function(...) !.p(...)
}
reduce <- function(.x, .f, ..., .init) {
f <- function(x, y) .f(x, y, ...)
Reduce(f, .x, init = .init)
}
reduce_right <- function(.x, .f, ..., .init) {
f <- function(x, y) .f(y, x, ...)
Reduce(f, .x, init = .init, right = TRUE)
}
accumulate <- function(.x, .f, ..., .init) {
f <- function(x, y) .f(x, y, ...)
Reduce(f, .x, init = .init, accumulate = TRUE)
}
accumulate_right <- function(.x, .f, ..., .init) {
f <- function(x, y) .f(y, x, ...)
Reduce(f, .x, init = .init, right = TRUE, accumulate = TRUE)
}
detect <- function(.x, .f, ..., .right = FALSE, .p = is_true) {
for (i in index(.x, .right)) {
if (.p(.f(.x[[i]], ...))) {
return(.x[[i]])
}
}
NULL
}
detect_index <- function(.x, .f, ..., .right = FALSE, .p = is_true) {
for (i in index(.x, .right)) {
if (.p(.f(.x[[i]], ...))) {
return(i)
}
}
0L
}
index <- function(x, right = FALSE) {
idx <- seq_along(x)
if (right) {
idx <- rev(idx)
}
idx
}
imap <- function(.x, .f, ...) {
map2(.x, vec_index(.x), .f, ...)
}
vec_index <- function(x) {
names(x) %||% seq_along(x)
}
# nocov end
stringr/R/replace.R 0000644 0001762 0000144 00000014143 14524701211 013701 0 ustar ligges users #' Replace matches with new text
#'
#' `str_replace()` replaces the first match; `str_replace_all()` replaces
#' all matches.
#'
#' @inheritParams str_detect
#' @param pattern Pattern to look for.
#'
#' The default interpretation is a regular expression, as described
#' in [stringi::about_search_regex]. Control options with
#' [regex()].
#'
#' For `str_replace_all()` this can also be a named vector
#' (`c(pattern1 = replacement1)`), in order to perform multiple replacements
#' in each element of `string`.
#'
#' Match a fixed string (i.e. by comparing only bytes), using
#' [fixed()]. This is fast, but approximate. Generally,
#' for matching human text, you'll want [coll()] which
#' respects character matching rules for the specified locale.
#' @param replacement The replacement value, usually a single string,
#' but it can be the a vector the same length as `string` or `pattern`.
#' References of the form `\1`, `\2`, etc will be replaced with
#' the contents of the respective matched group (created by `()`).
#'
#' Alternatively, supply a function, which will be called once for each
#' match (from right to left) and its return value will be used to replace
#' the match.
#' @return A character vector the same length as
#' `string`/`pattern`/`replacement`.
#' @seealso [str_replace_na()] to turn missing values into "NA";
#' [stri_replace()] for the underlying implementation.
#' @export
#' @examples
#' fruits <- c("one apple", "two pears", "three bananas")
#' str_replace(fruits, "[aeiou]", "-")
#' str_replace_all(fruits, "[aeiou]", "-")
#' str_replace_all(fruits, "[aeiou]", toupper)
#' str_replace_all(fruits, "b", NA_character_)
#'
#' str_replace(fruits, "([aeiou])", "")
#' str_replace(fruits, "([aeiou])", "\\1\\1")
#'
#' # Note that str_replace() is vectorised along text, pattern, and replacement
#' str_replace(fruits, "[aeiou]", c("1", "2", "3"))
#' str_replace(fruits, c("a", "e", "i"), "-")
#'
#' # If you want to apply multiple patterns and replacements to the same
#' # string, pass a named vector to pattern.
#' fruits %>%
#' str_c(collapse = "---") %>%
#' str_replace_all(c("one" = "1", "two" = "2", "three" = "3"))
#'
#' # Use a function for more sophisticated replacement. This example
#' # replaces colour names with their hex values.
#' colours <- str_c("\\b", colors(), "\\b", collapse="|")
#' col2hex <- function(col) {
#' rgb <- col2rgb(col)
#' rgb(rgb["red", ], rgb["green", ], rgb["blue", ], max = 255)
#' }
#'
#' x <- c(
#' "Roses are red, violets are blue",
#' "My favourite colour is green"
#' )
#' str_replace_all(x, colours, col2hex)
str_replace <- function(string, pattern, replacement) {
if (!missing(replacement) && is_replacement_fun(replacement)) {
replacement <- as_function(replacement)
return(str_transform(string, pattern, replacement))
}
check_lengths(string, pattern, replacement)
switch(type(pattern),
empty = no_empty(),
bound = no_boundary(),
fixed = stri_replace_first_fixed(string, pattern, replacement,
opts_fixed = opts(pattern)),
coll = stri_replace_first_coll(string, pattern, replacement,
opts_collator = opts(pattern)),
regex = stri_replace_first_regex(string, pattern, fix_replacement(replacement),
opts_regex = opts(pattern))
)
}
#' @export
#' @rdname str_replace
str_replace_all <- function(string, pattern, replacement) {
if (!missing(replacement) && is_replacement_fun(replacement)) {
replacement <- as_function(replacement)
return(str_transform_all(string, pattern, replacement))
}
if (!is.null(names(pattern))) {
vec <- FALSE
replacement <- unname(pattern)
pattern[] <- names(pattern)
} else {
check_lengths(string, pattern, replacement)
vec <- TRUE
}
switch(type(pattern),
empty = cli::cli_abort("{.arg pattern} can't be empty."),
bound = cli::cli_abort("{.arg pattern} can't be a boundary."),
fixed = stri_replace_all_fixed(string, pattern, replacement,
vectorize_all = vec, opts_fixed = opts(pattern)),
coll = stri_replace_all_coll(string, pattern, replacement,
vectorize_all = vec, opts_collator = opts(pattern)),
regex = stri_replace_all_regex(string, pattern, fix_replacement(replacement),
vectorize_all = vec, opts_regex = opts(pattern))
)
}
is_replacement_fun <- function(x) {
is.function(x) || is_formula(x)
}
fix_replacement <- function(x, error_call = caller_env()) {
check_character(x, arg = "replacement", call = error_call)
vapply(x, fix_replacement_one, character(1), USE.NAMES = FALSE)
}
fix_replacement_one <- function(x) {
if (is.na(x)) {
return(x)
}
chars <- str_split(x, "")[[1]]
out <- character(length(chars))
escaped <- logical(length(chars))
in_escape <- FALSE
for (i in seq_along(chars)) {
escaped[[i]] <- in_escape
char <- chars[[i]]
if (in_escape) {
# Escape character not printed previously so must include here
if (char == "$") {
out[[i]] <- "\\\\$"
} else if (char >= "0" && char <= "9") {
out[[i]] <- paste0("$", char)
} else {
out[[i]] <- paste0("\\", char)
}
in_escape <- FALSE
} else {
if (char == "$") {
out[[i]] <- "\\$"
} else if (char == "\\") {
in_escape <- TRUE
} else {
out[[i]] <- char
}
}
}
# tibble::tibble(chars, out, escaped)
paste0(out, collapse = "")
}
#' Turn NA into "NA"
#'
#' @inheritParams str_replace
#' @param replacement A single string.
#' @export
#' @examples
#' str_replace_na(c(NA, "abc", "def"))
str_replace_na <- function(string, replacement = "NA") {
check_string(replacement)
stri_replace_na(string, replacement)
}
str_transform <- function(string, pattern, replacement) {
loc <- str_locate(string, pattern)
str_sub(string, loc, omit_na = TRUE) <- replacement(str_sub(string, loc))
string
}
str_transform_all <- function(string, pattern, replacement) {
locs <- str_locate_all(string, pattern)
for (i in seq_along(string)) {
for (j in rev(seq_len(nrow(locs[[i]])))) {
loc <- locs[[i]]
str_sub(string[[i]], loc[j, 1], loc[j, 2]) <- replacement(str_sub(string[[i]], loc[j, 1], loc[j, 2]))
}
}
string
}
stringr/R/c.R 0000644 0001762 0000144 00000004434 14520174727 012526 0 ustar ligges users #' Join multiple strings into one string
#'
#' @description
#' `str_c()` combines multiple character vectors into a single character
#' vector. It's very similar to [paste0()] but uses tidyverse recycling and
#' `NA` rules.
#'
#' One way to understand how `str_c()` works is picture a 2d matrix of strings,
#' where each argument forms a column. `sep` is inserted between each column,
#' and then each row is combined together into a single string. If `collapse`
#' is set, it's inserted between each row, and then the result is again
#' combined, this time into a single string.
#'
#' @param ... One or more character vectors.
#'
#' `NULL`s are removed; scalar inputs (vectors of length 1) are recycled to
#' the common length of vector inputs.
#'
#' Like most other R functions, missing values are "infectious": whenever
#' a missing value is combined with another string the result will always
#' be missing. Use [dplyr::coalesce()] or [str_replace_na()] to convert to
#' the desired value.
#' @param sep String to insert between input vectors.
#' @param collapse Optional string used to combine output into single
#' string. Generally better to use [str_flatten()] if you needed this
#' behaviour.
#' @return If `collapse = NULL` (the default) a character vector with
#' length equal to the longest input. If `collapse` is a string, a character
#' vector of length 1.
#' @export
#' @examples
#' str_c("Letter: ", letters)
#' str_c("Letter", letters, sep = ": ")
#' str_c(letters, " is for", "...")
#' str_c(letters[-26], " comes before ", letters[-1])
#'
#' str_c(letters, collapse = "")
#' str_c(letters, collapse = ", ")
#'
#' # Differences from paste() ----------------------
#' # Missing inputs give missing outputs
#' str_c(c("a", NA, "b"), "-d")
#' paste0(c("a", NA, "b"), "-d")
#' # Use str_replace_NA to display literal NAs:
#' str_c(str_replace_na(c("a", NA, "b")), "-d")
#'
#' # Uses tidyverse recycling rules
#' \dontrun{str_c(1:2, 1:3)} # errors
#' paste0(1:2, 1:3)
#'
#' str_c("x", character())
#' paste0("x", character())
str_c <- function(..., sep = "", collapse = NULL) {
check_string(sep)
check_string(collapse, allow_null = TRUE)
dots <- list(...)
dots <- dots[!map_lgl(dots, is.null)]
vctrs::vec_size_common(!!!dots)
inject(stri_c(!!!dots, sep = sep, collapse = collapse))
}
stringr/NEWS.md 0000644 0001762 0000144 00000032656 14524706116 013062 0 ustar ligges users # stringr 1.5.1
* Some minor documentation improvements.
* `str_trunc()` now correctly truncates strings when `side` is `"left"` or
`"center"` (@UchidaMizuki, #512).
# stringr 1.5.0
## Breaking changes
* stringr functions now consistently implement the tidyverse recycling rules
(#372). There are two main changes:
* Only vectors of length 1 are recycled. Previously, (e.g.)
`str_detect(letters, c("x", "y"))` worked, but it now errors.
* `str_c()` ignores `NULLs`, rather than treating them as length 0
vectors.
Additionally, many more arguments now throw errors, rather than warnings,
if supplied the wrong type of input.
* `regex()` and friends now generate class names with `stringr_` prefix (#384).
* `str_detect()`, `str_starts()`, `str_ends()` and `str_subset()` now error
when used with either an empty string (`""`) or a `boundary()`. These
operations didn't really make sense (`str_detect(x, "")` returned `TRUE`
for all non-empty strings) and made it easy to make mistakes when programming.
## New features
* Many tweaks to the documentation to make it more useful and consistent.
* New `vignette("from-base")` by @sastoudt provides a comprehensive comparison
between base R functions and their stringr equivalents. It's designed to
help you move to stringr if you're already familiar with base R string
functions (#266).
* New `str_escape()` escapes regular expression metacharacters, providing
an alternative to `fixed()` if you want to compose a pattern from user
supplied strings (#408).
* New `str_equal()` compares two character vectors using unicode rules,
optionally ignoring case (#381).
* `str_extract()` can now optionally extract a capturing group instead of
the complete match (#420).
* New `str_flatten_comma()` is a special case of `str_flatten()` designed for
comma separated flattening and can correctly apply the Oxford commas
when there are only two elements (#444).
* New `str_split_1()` is tailored for the special case of splitting up a single
string (#409).
* New `str_split_i()` extract a single piece from a string (#278, @bfgray3).
* New `str_like()` allows the use of SQL wildcards (#280, @rjpat).
* New `str_rank()` to complete the set of order/rank/sort functions (#353).
* New `str_sub_all()` to extract multiple substrings from each string.
* New `str_unique()` is a wrapper around `stri_unique()` and returns unique
string values in a character vector (#249, @seasmith).
* `str_view()` uses ANSI colouring rather than an HTML widget (#370). This
works in more places and requires fewer dependencies. It includes a number
of other small improvements:
* It no longer requires a pattern so you can use it to display strings with
special characters.
* It highlights unusual whitespace characters.
* It's vectorised over both string` and `pattern` (#407).
* It defaults to displaying all matches, making `str_view_all()` redundant
(and hence deprecated) (#455).
* New `str_width()` returns the display width of a string (#380).
* stringr is now licensed as MIT (#351).
## Minor improvements and bug fixes
* Better error message if you supply a non-string pattern (#378).
* A new data source for `sentences` has fixed many small errors.
* `str_extract()` and `str_exctract_all()` now work correctly when `pattern`
is a `boundary()`.
* `str_flatten()` gains a `last` argument that optionally override the
final separator (#377). It gains a `na.rm` argument to remove missing
values (since it's a summary function) (#439).
* `str_pad()` gains `use_width` argument to control whether to use the total
code point width or the number of code points as "width" of a string (#190).
* `str_replace()` and `str_replace_all()` can use standard tidyverse formula
shorthand for `replacement` function (#331).
* `str_starts()` and `str_ends()` now correctly respect regex operator
precedence (@carlganz).
* `str_wrap()` breaks only at whitespace by default; set
`whitespace_only = FALSE` to return to the previous behaviour (#335, @rjpat).
* `word()` now returns all the sentence when using a negative `start` parameter
that is greater or equal than the number of words. (@pdelboca, #245)
# stringr 1.4.1
Hot patch release to resolve R CMD check failures.
# stringr 1.4.0
* `str_interp()` now renders lists consistently independent on the presence of
additional placeholders (@amhrasmussen).
* New `str_starts()` and `str_ends()` functions to detect patterns at the
beginning or end of strings (@jonthegeek, #258).
* `str_subset()`, `str_detect()`, and `str_which()` get `negate` argument,
which is useful when you want the elements that do NOT match (#259,
@yutannihilation).
* New `str_to_sentence()` function to capitalize with sentence case
(@jonthegeek, #202).
# stringr 1.3.1
* `str_replace_all()` with a named vector now respects modifier functions (#207)
* `str_trunc()` is once again vectorised correctly (#203, @austin3dickey).
* `str_view()` handles `NA` values more gracefully (#217). I've also
tweaked the sizing policy so hopefully it should work better in notebooks,
while preserving the existing behaviour in knit documents (#232).
# stringr 1.3.0
## API changes
* During package build, you may see
`Error : object ‘ignore.case’ is not exported by 'namespace:stringr'`.
This is because the long deprecated `str_join()`, `ignore.case()` and
`perl()` have now been removed.
## New features
* `str_glue()` and `str_glue_data()` provide convenient wrappers around
`glue` and `glue_data()` from the [glue](https://glue.tidyverse.org/) package
(#157).
* `str_flatten()` is a wrapper around `stri_flatten()` and clearly
conveys flattening a character vector into a single string (#186).
* `str_remove()` and `str_remove_all()` functions. These wrap
`str_replace()` and `str_replace_all()` to remove patterns from strings.
(@Shians, #178)
* `str_squish()` removes spaces from both the left and right side of strings,
and also converts multiple space (or space-like characters) to a single
space within strings (@stephlocke, #197).
* `str_sub()` gains `omit_na` argument for ignoring `NA`. Accordingly,
`str_replace()` now ignores `NA`s and keeps the original strings.
(@yutannihilation, #164)
## Bug fixes and minor improvements
* `str_trunc()` now preserves NAs (@ClaytonJY, #162)
* `str_trunc()` now throws an error when `width` is shorter than `ellipsis`
(@ClaytonJY, #163).
* Long deprecated `str_join()`, `ignore.case()` and `perl()` have now been
removed.
# stringr 1.2.0
## API changes
* `str_match_all()` now returns NA if an optional group doesn't match
(previously it returned ""). This is more consistent with `str_match()`
and other match failures (#134).
## New features
* In `str_replace()`, `replacement` can now be a function that is called once
for each match and whose return value is used to replace the match.
* New `str_which()` mimics `grep()` (#129).
* A new vignette (`vignette("regular-expressions")`) describes the
details of the regular expressions supported by stringr.
The main vignette (`vignette("stringr")`) has been updated to
give a high-level overview of the package.
## Minor improvements and bug fixes
* `str_order()` and `str_sort()` gain explicit `numeric` argument for sorting
mixed numbers and strings.
* `str_replace_all()` now throws an error if `replacement` is not a character
vector. If `replacement` is `NA_character_` it replaces the complete string
with replaces with `NA` (#124).
* All functions that take a locale (e.g. `str_to_lower()` and `str_sort()`)
default to "en" (English) to ensure that the default is consistent across
platforms.
# stringr 1.1.0
* Add sample datasets: `fruit`, `words` and `sentences`.
* `fixed()`, `regex()`, and `coll()` now throw an error if you use them with
anything other than a plain string (#60). I've clarified that the replacement
for `perl()` is `regex()` not `regexp()` (#61). `boundary()` has improved
defaults when splitting on non-word boundaries (#58, @lmullen).
* `str_detect()` now can detect boundaries (by checking for a `str_count()` > 0)
(#120). `str_subset()` works similarly.
* `str_extract()` and `str_extract_all()` now work with `boundary()`. This is
particularly useful if you want to extract logical constructs like words
or sentences. `str_extract_all()` respects the `simplify` argument
when used with `fixed()` matches.
* `str_subset()` now respects custom options for `fixed()` patterns
(#79, @gagolews).
* `str_replace()` and `str_replace_all()` now behave correctly when a
replacement string contains `$`s, `\\\\1`, etc. (#83, #99).
* `str_split()` gains a `simplify` argument to match `str_extract_all()`
etc.
* `str_view()` and `str_view_all()` create HTML widgets that display regular
expression matches (#96).
* `word()` returns `NA` for indexes greater than number of words (#112).
# stringr 1.0.0
* stringr is now powered by [stringi](https://github.com/gagolews/stringi)
instead of base R regular expressions. This improves unicode and support, and
makes most operations considerably faster. If you find stringr inadequate for
your string processing needs, I highly recommend looking at stringi in more
detail.
* stringr gains a vignette, currently a straight forward update of the article
that appeared in the R Journal.
* `str_c()` now returns a zero length vector if any of its inputs are
zero length vectors. This is consistent with all other functions, and
standard R recycling rules. Similarly, using `str_c("x", NA)` now
yields `NA`. If you want `"xNA"`, use `str_replace_na()` on the inputs.
* `str_replace_all()` gains a convenient syntax for applying multiple pairs of
pattern and replacement to the same vector:
```R
input <- c("abc", "def")
str_replace_all(input, c("[ad]" = "!", "[cf]" = "?"))
```
* `str_match()` now returns NA if an optional group doesn't match
(previously it returned ""). This is more consistent with `str_extract()`
and other match failures.
* New `str_subset()` keeps values that match a pattern. It's a convenient
wrapper for `x[str_detect(x)]` (#21, @jiho).
* New `str_order()` and `str_sort()` allow you to sort and order strings
in a specified locale.
* New `str_conv()` to convert strings from specified encoding to UTF-8.
* New modifier `boundary()` allows you to count, locate and split by
character, word, line and sentence boundaries.
* The documentation got a lot of love, and very similar functions (e.g.
first and all variants) are now documented together. This should hopefully
make it easier to locate the function you need.
* `ignore.case(x)` has been deprecated in favour of
`fixed|regex|coll(x, ignore.case = TRUE)`, `perl(x)` has been deprecated in
favour of `regex(x)`.
* `str_join()` is deprecated, please use `str_c()` instead.
# stringr 0.6.2
* fixed path in `str_wrap` example so works for more R installations.
* remove dependency on plyr
# stringr 0.6.1
* Zero input to `str_split_fixed` returns 0 row matrix with `n` columns
* Export `str_join`
# stringr 0.6
* new modifier `perl` that switches to Perl regular expressions
* `str_match` now uses new base function `regmatches` to extract matches -
this should hopefully be faster than my previous pure R algorithm
# stringr 0.5
* new `str_wrap` function which gives `strwrap` output in a more convenient
format
* new `word` function extract words from a string given user defined
separator (thanks to suggestion by David Cooper)
* `str_locate` now returns consistent type when matching empty string (thanks
to Stavros Macrakis)
* new `str_count` counts number of matches in a string.
* `str_pad` and `str_trim` receive performance tweaks - for large vectors this
should give at least a two order of magnitude speed up
* str_length returns NA for invalid multibyte strings
* fix small bug in internal `recyclable` function
# stringr 0.4
* all functions now vectorised with respect to string, pattern (and
where appropriate) replacement parameters
* fixed() function now tells stringr functions to use fixed matching, rather
than escaping the regular expression. Should improve performance for
large vectors.
* new ignore.case() modifier tells stringr functions to ignore case of
pattern.
* str_replace renamed to str_replace_all and new str_replace function added.
This makes str_replace consistent with all functions.
* new str_sub<- function (analogous to substring<-) for substring replacement
* str_sub now understands negative positions as a position from the end of
the string. -1 replaces Inf as indicator for string end.
* str_pad side argument can be left, right, or both (instead of center)
* str_trim gains side argument to better match str_pad
* stringr now has a namespace and imports plyr (rather than requiring it)
# stringr 0.3
* fixed() now also escapes |
* str_join() renamed to str_c()
* all functions more carefully check input and return informative error
messages if not as expected.
* add invert_match() function to convert a matrix of location of matches to
locations of non-matches
* add fixed() function to allow matching of fixed strings.
# stringr 0.2
* str_length now returns correct results when used with factors
* str_sub now correctly replaces Inf in end argument with length of string
* new function str_split_fixed returns fixed number of splits in a character
matrix
* str_split no longer uses strsplit to preserve trailing breaks
stringr/MD5 0000644 0001762 0000144 00000017255 14524777112 012276 0 ustar ligges users 6417661a7c8efb838ad5d5b6f7765ba8 *DESCRIPTION
a0018b1c7c6a9756addc1b079daa5cf0 *LICENSE
53cac8267191c7135e60ff422a789b57 *NAMESPACE
3c28871ed9da543fe831761643561104 *NEWS.md
11390682e89c2e7653a90d0c72f84241 *R/c.R
a4a814af55ec5f84c9c39746ea39edc1 *R/case.R
07c06e6be0443b7d5b9094f11daa406f *R/compat-obj-type.R
6ff61ce96b8a0aca5f241ef7aaab4a68 *R/compat-purrr.R
f299eacebcf906163a629b2ef7787ba4 *R/compat-types-check.R
236c313428f675772ae78e10ec583aab *R/conv.R
f75b36e8fb84010a555444e6f8950148 *R/count.R
d17b3c3f3f546123603f4f5f84a5f3cb *R/data.R
a864288668850afe6aa376437d70d344 *R/detect.R
02515c6f25da38950c825474b67623e1 *R/dup.R
1c6b2097f903dde0057acb61c89eeb01 *R/equal.R
0df0460a69007695b24bbd4c2bd57645 *R/escape.R
ea6dfb84a0cbb37d017ebe5b8ff64e63 *R/extract.R
61dae6d6a3696574e7d6d86c5cf8673d *R/flatten.R
1f7ebdf1299f7832220640f16f03c7bb *R/glue.R
242f08a29f1cdcdf774bc277a0fec933 *R/interp.R
d072949ee58976ca4e02dcb4e775c394 *R/length.R
7d10a9448a8556aaf846a9408c733eb4 *R/locate.R
8c37d98f0218668449fa9378ad693eea *R/match.R
815c2c1b410c4e7a5d26fd35f5e097ce *R/modifiers.R
eede1618dad4a0861c54dcdfb2c8ac75 *R/pad.R
d21d0843b2319c6f450c1e62459e2502 *R/remove.R
100c2b42b967fff29315697c2ef89225 *R/replace.R
dfabd70c0e2d57f9b2c3ce94394a0be5 *R/sort.R
0552ae2a46503839a88cfb707866ba80 *R/split.R
89c1a3fe6a9b2c2627c0c217d3240601 *R/stringr-package.R
95a7f7de995ead49e5728f4d5ac9b6af *R/sub.R
9d96b7aeda42bf69cd9b7a1ce5492e3e *R/subset.R
88afe326dd676421d7cc04309610796a *R/trim.R
467b44328c4da52de9d4820d84cf9a70 *R/trunc.R
ee836edf224d73d887bc94cf8453705d *R/unique.R
33b05fa3a588a58663f835ce45783e83 *R/utils.R
be25c17f9a9668f766a8a02b73da9268 *R/view.R
9440e9e7a0bbc33ada2e425cf0ed2cbe *R/word.R
ccb9c91317f1b34569c8495f4c8f3b9a *R/wrap.R
0b6dd73d03f405561232bb60c5052c33 *README.md
effdb89ddbda0e944da4a5d7699bbd4b *build/vignette.rds
89f0d280160eb4419b23251639a728c2 *data/fruit.rda
51f821ca3b3f8a286d0ceabccdab6ca7 *data/sentences.rda
c99f00d311e24c76bbeabfc8a58b4b50 *data/words.rda
6259b8c4d33f86a18130632a8c44e770 *inst/doc/from-base.R
55fa03361dfbc453024c7ab8df2ede71 *inst/doc/from-base.Rmd
c9b48c49b98c37e75a6f7b64571fd6d6 *inst/doc/from-base.html
13a030b4d1d374db7bc577145b69e24c *inst/doc/regular-expressions.R
bee4d7614ef68fce3dc6772a0442a1ff *inst/doc/regular-expressions.Rmd
17c9d247135faeb4b172ebc7b47b97e1 *inst/doc/regular-expressions.html
d57838d0deb2a741886f70eeed71604b *inst/doc/stringr.R
2e6abe80c39713fdd5778e6276185408 *inst/doc/stringr.Rmd
80f1f2e645f232b6fb10cc716a5407f4 *inst/doc/stringr.html
5f38e68c0f6148b954a6849fe553b173 *inst/htmlwidgets/lib/str_view.css
e7c37a495d4ae965400eeb1000dee672 *inst/htmlwidgets/str_view.js
1763429826b7f9745d2e590e4ca4c119 *inst/htmlwidgets/str_view.yaml
71f33ca928beb04691d6a17102f377f9 *man/case.Rd
cb1e46f469cfbbbde29c8b5113e1d789 *man/figures/lifecycle-archived.svg
c0d2e5a54f1fa4ff02bf9533079dd1f7 *man/figures/lifecycle-defunct.svg
a1b8c987c676c16af790f563f96cbb1f *man/figures/lifecycle-deprecated.svg
c3978703d8f40f2679795335715e98f4 *man/figures/lifecycle-experimental.svg
952b59dc07b171b97d5d982924244f61 *man/figures/lifecycle-maturing.svg
27b879bf3677ea76e3991d56ab324081 *man/figures/lifecycle-questioning.svg
53b3f893324260b737b3c46ed2a0e643 *man/figures/lifecycle-stable.svg
1c1fe7a759b86dc6dbcbe7797ab8246c *man/figures/lifecycle-superseded.svg
86fdd0a3f998a3d5a3ed6a850f5a1a0b *man/figures/logo.png
ab69caa66e7d332f9555f8c4ae39e441 *man/invert_match.Rd
ef8404412dac3596f66f50c3268fd089 *man/modifiers.Rd
a64a7ea44fcaa33c2d3ad0f7909cbc3e *man/pipe.Rd
7ecc8f5ddb1b5fd123cdbf4a532da370 *man/str_c.Rd
4c5363f6872ab4d60fdb91609af1be13 *man/str_conv.Rd
d6973b6218a2a1a32eee03e1a0ffa41c *man/str_count.Rd
1bdaa07efcfb600dadd5a93342af1e4b *man/str_detect.Rd
b07cca29357daa5c72bad16c916ede42 *man/str_dup.Rd
5f09e863013a8297b0b38ffa1d3ba5fe *man/str_equal.Rd
0e95910de21db06a6e642bbd8cc17e96 *man/str_escape.Rd
d4f5015fbae4ef8d749a8d334b274412 *man/str_extract.Rd
8d296bb5ba6ef0bc7d976c12c3af195e *man/str_flatten.Rd
4b55b07f3b462f77dc4ebb5bb22c303b *man/str_glue.Rd
0aaa5a0cce235f807c189a0233464add *man/str_interp.Rd
9a978f65167837c2a82b9eb45e877276 *man/str_length.Rd
743c58ac7940bfdb78022ab998687a3d *man/str_like.Rd
fde4acb343e7261725078e7453f1a5fd *man/str_locate.Rd
c78d29b9b7696ac56fbd4f8975efa955 *man/str_match.Rd
6ac9678ff6aa4a96ff3beb460a2d565e *man/str_order.Rd
df526bd928ec6a89b62d80df016d7aa9 *man/str_pad.Rd
ae9a5667a4064d65c3812080b3f80fec *man/str_remove.Rd
94e9edf26c8bdca90bcac40e426ba042 *man/str_replace.Rd
797da58fc306dc7b018434727a32d26a *man/str_replace_na.Rd
fffbbf8d258f6be66101c63210570936 *man/str_split.Rd
422188a7f648f1047e529fcafa3dcacc *man/str_starts.Rd
a0bda4a83f1bbcce75d6ff072eab3812 *man/str_sub.Rd
d92d29fbb86b0fb2a98e496af68e5561 *man/str_subset.Rd
7dffcd7bcfda40c125dd8da67404a32e *man/str_trim.Rd
4e4e96af2d85d1f024a8c3495c7a8400 *man/str_trunc.Rd
ad920b9d524a6cdad804abddd67836bc *man/str_unique.Rd
fce68051479e8c8a2126cab061cc956a *man/str_view.Rd
6f3edc14ec4040eaa8414f53ead6e9d9 *man/str_which.Rd
fb432c6d1ee6a45f6bae4630a72e4c31 *man/str_wrap.Rd
b020a9e0c22c8a73988673d8105e6beb *man/stringr-data.Rd
faadd8ce234ceadf5aa02978b567398f *man/stringr-package.Rd
0e38c8016c39ab1cbfdac436864918df *man/word.Rd
4ee9d05bd4688270eca8d85299cedcd1 *tests/testthat.R
2495853cc152148a9967b97a742189d2 *tests/testthat/_snaps/c.md
e1070ef18b7d962e0060cecc2751f0eb *tests/testthat/_snaps/detect.md
feb7439575c71a94b2fd96a1cfe8490f *tests/testthat/_snaps/match.md
bb5aa361c47349d8e72ef050f17ce13f *tests/testthat/_snaps/modifiers.md
701413f4ddebcd6f159e3c1bee9ea807 *tests/testthat/_snaps/replace.md
f7d84d80aac766e0dabc941f4d1cc99f *tests/testthat/_snaps/split.md
b226cf3dc38f2430e39bcdace6baa41f *tests/testthat/_snaps/subset.md
998a7db85bac398d9ad63edc24ae9fb4 *tests/testthat/_snaps/trunc.md
666ca9c4c0f885d6829fadce41a61616 *tests/testthat/_snaps/view.md
04fa3430820d49de179ce1be247461bf *tests/testthat/test-c.R
1b96097e258ae55b2501a037dfb9005f *tests/testthat/test-case.R
cbf33254fcbdb2f01825365e017d5ee4 *tests/testthat/test-conv.R
fd652a597975ae2e952ca11339671fe2 *tests/testthat/test-count.R
e8be5c6fee11af55731655faa27fcc57 *tests/testthat/test-detect.R
f9fca2103c840b9ed94900b03d31b5f5 *tests/testthat/test-dup.R
8c45219dd2995f936cb8c3f9716c8011 *tests/testthat/test-equal.R
d23fcddf47a45da27a103f808a18e78e *tests/testthat/test-escape.R
a5a2d54d820de92d947f38a73aa28fce *tests/testthat/test-extract.R
e05f21c06429b79a1448f42578e44408 *tests/testthat/test-flatten.R
5d174d75b4333754c212093685c8dfa9 *tests/testthat/test-glue.R
8d10e593e9d78b50eb581f4e07c73c5c *tests/testthat/test-interp.R
4b370f0991952923730c72182afddb8c *tests/testthat/test-length.R
7fefa323cad92802b1bdc6fcab170240 *tests/testthat/test-locate.R
fe205e7026398ab262c3d9bbcc94579e *tests/testthat/test-match.R
5a6bb7b3ac53d7ef600d8aa86f48c736 *tests/testthat/test-modifiers.R
3542cb39e4cc66103619704b1ab97700 *tests/testthat/test-pad.R
067c9f1b67bd63b8e355cb28e31c976f *tests/testthat/test-remove.R
6edbe852bdb28146002beea516236f6a *tests/testthat/test-replace.R
82139ea85343349a40a44be88aa36d11 *tests/testthat/test-sort.R
0b9db589d9d6b3ea2d058e310a281e61 *tests/testthat/test-split.R
2399869fcfc88342844800f634459d2a *tests/testthat/test-sub.R
968816a52cce5608b6159e758526739d *tests/testthat/test-subset.R
d6bcfb2fd01012d8ec733a7600291bed *tests/testthat/test-trim.R
bf32022e418f7e355da993ba8b354600 *tests/testthat/test-trunc.R
c801dfc65d41c161b000ea64a49f6944 *tests/testthat/test-unique.R
8a43c5c965ddfc1680a58812acde8267 *tests/testthat/test-view.R
a1de73cbd092c5c94bf6a51e6103740c *tests/testthat/test-word.R
217ae1d7e7fa11dcf0b5ba0ed1c08473 *tests/testthat/test-wrap.R
55fa03361dfbc453024c7ab8df2ede71 *vignettes/from-base.Rmd
bee4d7614ef68fce3dc6772a0442a1ff *vignettes/regular-expressions.Rmd
2e6abe80c39713fdd5778e6276185408 *vignettes/stringr.Rmd
stringr/inst/ 0000755 0001762 0000144 00000000000 14524706130 012721 5 ustar ligges users stringr/inst/doc/ 0000755 0001762 0000144 00000000000 14524706130 013466 5 ustar ligges users stringr/inst/doc/from-base.Rmd 0000644 0001762 0000144 00000040364 14524677110 016021 0 ustar ligges users ---
title: "From base R"
author: "Sara Stoudt"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{From base R}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r}
#| label: setup
#| include: false
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
library(stringr)
library(magrittr)
```
This vignette compares stringr functions to their base R equivalents to help users transitioning from using base R to stringr.
# Overall differences
We'll begin with a lookup table between the most important stringr functions and their base R equivalents.
```{r}
#| label: stringr-base-r-diff
#| echo: false
data_stringr_base_diff <- tibble::tribble(
~stringr, ~base_r,
"str_detect(string, pattern)", "grepl(pattern, x)",
"str_dup(string, times)", "strrep(x, times)",
"str_extract(string, pattern)", "regmatches(x, m = regexpr(pattern, text))",
"str_extract_all(string, pattern)", "regmatches(x, m = gregexpr(pattern, text))",
"str_length(string)", "nchar(x)",
"str_locate(string, pattern)", "regexpr(pattern, text)",
"str_locate_all(string, pattern)", "gregexpr(pattern, text)",
"str_match(string, pattern)", "regmatches(x, m = regexec(pattern, text))",
"str_order(string)", "order(...)",
"str_replace(string, pattern, replacement)", "sub(pattern, replacement, x)",
"str_replace_all(string, pattern, replacement)", "gsub(pattern, replacement, x)",
"str_sort(string)", "sort(x)",
"str_split(string, pattern)", "strsplit(x, split)",
"str_sub(string, start, end)", "substr(x, start, stop)",
"str_subset(string, pattern)", "grep(pattern, x, value = TRUE)",
"str_to_lower(string)", "tolower(x)",
"str_to_title(string)", "tools::toTitleCase(text)",
"str_to_upper(string)", "toupper(x)",
"str_trim(string)", "trimws(x)",
"str_which(string, pattern)", "grep(pattern, x)",
"str_wrap(string)", "strwrap(x)"
)
# create MD table, arranged alphabetically by stringr fn name
data_stringr_base_diff %>%
dplyr::mutate(dplyr::across(.fns = ~ paste0("`", .x, "`"))) %>%
dplyr::arrange(stringr) %>%
dplyr::rename(`base R` = base_r) %>%
gt::gt() %>%
gt::fmt_markdown(columns = everything()) %>%
gt::tab_options(column_labels.font.weight = "bold")
```
Overall the main differences between base R and stringr are:
1. stringr functions start with `str_` prefix; base R string functions have no
consistent naming scheme.
1. The order of inputs is usually different between base R and stringr.
In base R, the `pattern` to match usually comes first; in stringr, the
`string` to manupulate always comes first. This makes stringr easier
to use in pipes, and with `lapply()` or `purrr::map()`.
1. Functions in stringr tend to do less, where many of the string processing
functions in base R have multiple purposes.
1. The output and input of stringr functions has been carefully designed.
For example, the output of `str_locate()` can be fed directly into
`str_sub()`; the same is not true of `regpexpr()` and `substr()`.
1. Base functions use arguments (like `perl`, `fixed`, and `ignore.case`)
to control how the pattern is interpreted. To avoid dependence between
arguments, stringr instead uses helper functions (like `fixed()`,
`regex()`, and `coll()`).
Next we'll walk through each of the functions, noting the similarities and important differences. These examples are adapted from the stringr documentation and here they are contrasted with the analogous base R operations.
# Detect matches
## `str_detect()`: Detect the presence or absence of a pattern in a string
Suppose you want to know whether each word in a vector of fruit names contains an "a".
```{r}
fruit <- c("apple", "banana", "pear", "pineapple")
# base
grepl(pattern = "a", x = fruit)
# stringr
str_detect(fruit, pattern = "a")
```
In base you would use `grepl()` (see the "l" and think logical) while in stringr you use `str_detect()` (see the verb "detect" and think of a yes/no action).
## `str_which()`: Find positions matching a pattern
Now you want to identify the positions of the words in a vector of fruit names that contain an "a".
```{r}
# base
grep(pattern = "a", x = fruit)
# stringr
str_which(fruit, pattern = "a")
```
In base you would use `grep()` while in stringr you use `str_which()` (by analogy to `which()`).
## `str_count()`: Count the number of matches in a string
How many "a"s are in each fruit?
```{r}
# base
loc <- gregexpr(pattern = "a", text = fruit, fixed = TRUE)
sapply(loc, function(x) length(attr(x, "match.length")))
# stringr
str_count(fruit, pattern = "a")
```
This information can be gleaned from `gregexpr()` in base, but you need to look at the `match.length` attribute as the vector uses a length-1 integer vector (`-1`) to indicate no match.
## `str_locate()`: Locate the position of patterns in a string
Within each fruit, where does the first "p" occur? Where are all of the "p"s?
```{r}
fruit3 <- c("papaya", "lime", "apple")
# base
str(gregexpr(pattern = "p", text = fruit3))
# stringr
str_locate(fruit3, pattern = "p")
str_locate_all(fruit3, pattern = "p")
```
# Subset strings
## `str_sub()`: Extract and replace substrings from a character vector
What if we want to grab part of a string?
```{r}
hw <- "Hadley Wickham"
# base
substr(hw, start = 1, stop = 6)
substring(hw, first = 1)
# stringr
str_sub(hw, start = 1, end = 6)
str_sub(hw, start = 1)
str_sub(hw, end = 6)
```
In base you could use `substr()` or `substring()`. The former requires both a start and stop of the substring while the latter assumes the stop will be the end of the string. The stringr version, `str_sub()` has the same functionality, but also gives a default start value (the beginning of the string). Both the base and stringr functions have the same order of expected inputs.
In stringr you can use negative numbers to index from the right-hand side string: -1 is the last letter, -2 is the second to last, and so on.
```{r}
str_sub(hw, start = 1, end = -1)
str_sub(hw, start = -5, end = -2)
```
Both base R and stringr subset are vectorized over their parameters. This means you can either choose the same subset across multiple strings or specify different subsets for different strings.
```{r}
al <- "Ada Lovelace"
# base
substr(c(hw,al), start = 1, stop = 6)
substr(c(hw,al), start = c(1,1), stop = c(6,7))
# stringr
str_sub(c(hw,al), start = 1, end = -1)
str_sub(c(hw,al), start = c(1,1), end = c(-1,-2))
```
stringr will automatically recycle the first argument to the same length as `start` and `stop`:
```{r}
str_sub(hw, start = 1:5)
```
Whereas the base equivalent silently uses just the first value:
```{r}
substr(hw, start = 1:5, stop = 15)
```
## `str_sub() <- `: Subset assignment
`substr()` behaves in a surprising way when you replace a substring with a different number of characters:
```{r}
# base
x <- "ABCDEF"
substr(x, 1, 3) <- "x"
x
```
`str_sub()` does what you would expect:
```{r}
# stringr
x <- "ABCDEF"
str_sub(x, 1, 3) <- "x"
x
```
## `str_subset()`: Keep strings matching a pattern, or find positions
We may want to retrieve strings that contain a pattern of interest:
```{r}
# base
grep(pattern = "g", x = fruit, value = TRUE)
# stringr
str_subset(fruit, pattern = "g")
```
## `str_extract()`: Extract matching patterns from a string
We may want to pick out certain patterns from a string, for example, the digits in a shopping list:
```{r}
shopping_list <- c("apples x4", "bag of flour", "10", "milk x2")
# base
matches <- regexpr(pattern = "\\d+", text = shopping_list) # digits
regmatches(shopping_list, m = matches)
matches <- gregexpr(pattern = "[a-z]+", text = shopping_list) # words
regmatches(shopping_list, m = matches)
# stringr
str_extract(shopping_list, pattern = "\\d+")
str_extract_all(shopping_list, "[a-z]+")
```
Base R requires the combination of `regexpr()` with `regmatches()`; but note that the strings without matches are dropped from the output. stringr provides `str_extract()` and `str_extract_all()`, and the output is always the same length as the input.
## `str_match()`: Extract matched groups from a string
We may also want to extract groups from a string. Here I'm going to use the scenario from Section 14.4.3 in [R for Data Science](https://r4ds.had.co.nz/strings.html).
```{r}
head(sentences)
noun <- "([A]a|[Tt]he) ([^ ]+)"
# base
matches <- regexec(pattern = noun, text = head(sentences))
do.call("rbind", regmatches(x = head(sentences), m = matches))
# stringr
str_match(head(sentences), pattern = noun)
```
As for extracting the full match base R requires the combination of two functions, and inputs with no matches are dropped from the output.
# Manage lengths
## `str_length()`: The length of a string
To determine the length of a string, base R uses `nchar()` (not to be confused with `length()` which gives the length of vectors, etc.) while stringr uses `str_length()`.
```{r}
# base
nchar(letters)
# stringr
str_length(letters)
```
There are some subtle differences between base and stringr here. `nchar()` requires a character vector, so it will return an error if used on a factor. `str_length()` can handle a factor input.
```{r}
#| error: true
# base
nchar(factor("abc"))
```
```{r}
# stringr
str_length(factor("abc"))
```
Note that "characters" is a poorly defined concept, and technically both `nchar()` and `str_length()` returns the number of code points. This is usually the same as what you'd consider to be a charcter, but not always:
```{r}
x <- c("\u00fc", "u\u0308")
x
nchar(x)
str_length(x)
```
## `str_pad()`: Pad a string
To pad a string to a certain width, use stringr's `str_pad()`. In base R you could use `sprintf()`, but unlike `str_pad()`, `sprintf()` has many other functionalities.
```{r}
# base
sprintf("%30s", "hadley")
sprintf("%-30s", "hadley")
# "both" is not as straightforward
# stringr
rbind(
str_pad("hadley", 30, "left"),
str_pad("hadley", 30, "right"),
str_pad("hadley", 30, "both")
)
```
## `str_trunc()`: Truncate a character string
The stringr package provides an easy way to truncate a character string: `str_trunc()`. Base R has no function to do this directly.
```{r}
x <- "This string is moderately long"
# stringr
rbind(
str_trunc(x, 20, "right"),
str_trunc(x, 20, "left"),
str_trunc(x, 20, "center")
)
```
## `str_trim()`: Trim whitespace from a string
Similarly, stringr provides `str_trim()` to trim whitespace from a string. This is analogous to base R's `trimws()` added in R 3.3.0.
```{r}
# base
trimws(" String with trailing and leading white space\t")
trimws("\n\nString with trailing and leading white space\n\n")
# stringr
str_trim(" String with trailing and leading white space\t")
str_trim("\n\nString with trailing and leading white space\n\n")
```
The stringr function `str_squish()` allows for extra whitespace within a string to be trimmed (in contrast to `str_trim()` which removes whitespace at the beginning and/or end of string). In base R, one might take advantage of `gsub()` to accomplish the same effect.
```{r}
# stringr
str_squish(" String with trailing, middle, and leading white space\t")
str_squish("\n\nString with excess, trailing and leading white space\n\n")
```
## `str_wrap()`: Wrap strings into nicely formatted paragraphs
`strwrap()` and `str_wrap()` use different algorithms. `str_wrap()` uses the famous [Knuth-Plass algorithm](http://litherum.blogspot.com/2015/07/knuth-plass-line-breaking-algorithm.html).
```{r}
gettysburg <- "Four score and seven years ago our fathers brought forth on this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal."
# base
cat(strwrap(gettysburg, width = 60), sep = "\n")
# stringr
cat(str_wrap(gettysburg, width = 60), "\n")
```
Note that `strwrap()` returns a character vector with one element for each line; `str_wrap()` returns a single string containing line breaks.
# Mutate strings
## `str_replace()`: Replace matched patterns in a string
To replace certain patterns within a string, stringr provides the functions `str_replace()` and `str_replace_all()`. The base R equivalents are `sub()` and `gsub()`. Note the difference in default input order again.
```{r}
fruits <- c("apple", "banana", "pear", "pineapple")
# base
sub("[aeiou]", "-", fruits)
gsub("[aeiou]", "-", fruits)
# stringr
str_replace(fruits, "[aeiou]", "-")
str_replace_all(fruits, "[aeiou]", "-")
```
## case: Convert case of a string
Both stringr and base R have functions to convert to upper and lower case. Title case is also provided in stringr.
```{r}
dog <- "The quick brown dog"
# base
toupper(dog)
tolower(dog)
tools::toTitleCase(dog)
# stringr
str_to_upper(dog)
str_to_lower(dog)
str_to_title(dog)
```
In stringr we can control the locale, while in base R locale distinctions are controlled with global variables. Therefore, the output of your base R code may vary across different computers with different global settings.
```{r}
# stringr
str_to_upper("i") # English
str_to_upper("i", locale = "tr") # Turkish
```
# Join and split
## `str_flatten()`: Flatten a string
If we want to take elements of a string vector and collapse them to a single string we can use the `collapse` argument in `paste()` or use stringr's `str_flatten()`.
```{r}
# base
paste0(letters, collapse = "-")
# stringr
str_flatten(letters, collapse = "-")
```
The advantage of `str_flatten()` is that it always returns a vector the same length as its input; to predict the return length of `paste()` you must carefully read all arguments.
## `str_dup()`: duplicate strings within a character vector
To duplicate strings within a character vector use `strrep()` (in R 3.3.0 or greater) or `str_dup()`:
```{r}
#| eval: !expr getRversion() >= "3.3.0"
fruit <- c("apple", "pear", "banana")
# base
strrep(fruit, 2)
strrep(fruit, 1:3)
# stringr
str_dup(fruit, 2)
str_dup(fruit, 1:3)
```
## `str_split()`: Split up a string into pieces
To split a string into pieces with breaks based on a particular pattern match stringr uses `str_split()` and base R uses `strsplit()`. Unlike most other functions, `strsplit()` starts with the character vector to modify.
```{r}
fruits <- c(
"apples and oranges and pears and bananas",
"pineapples and mangos and guavas"
)
# base
strsplit(fruits, " and ")
# stringr
str_split(fruits, " and ")
```
The stringr package's `str_split()` allows for more control over the split, including restricting the number of possible matches.
```{r}
# stringr
str_split(fruits, " and ", n = 3)
str_split(fruits, " and ", n = 2)
```
## `str_glue()`: Interpolate strings
It's often useful to interpolate varying values into a fixed string. In base R, you can use `sprintf()` for this purpose; stringr provides a wrapper for the more general purpose [glue](https://glue.tidyverse.org) package.
```{r}
name <- "Fred"
age <- 50
anniversary <- as.Date("1991-10-12")
# base
sprintf(
"My name is %s my age next year is %s and my anniversary is %s.",
name,
age + 1,
format(anniversary, "%A, %B %d, %Y")
)
# stringr
str_glue(
"My name is {name}, ",
"my age next year is {age + 1}, ",
"and my anniversary is {format(anniversary, '%A, %B %d, %Y')}."
)
```
# Order strings
## `str_order()`: Order or sort a character vector
Both base R and stringr have separate functions to order and sort strings.
```{r}
# base
order(letters)
sort(letters)
# stringr
str_order(letters)
str_sort(letters)
```
Some options in `str_order()` and `str_sort()` don't have analogous base R options. For example, the stringr functions have a `locale` argument to control how to order or sort. In base R the locale is a global setting, so the outputs of `sort()` and `order()` may differ across different computers. For example, in the Norwegian alphabet, å comes after z:
```{r}
x <- c("å", "a", "z")
str_sort(x)
str_sort(x, locale = "no")
```
The stringr functions also have a `numeric` argument to sort digits numerically instead of treating them as strings.
```{r}
# stringr
x <- c("100a10", "100a5", "2b", "2a")
str_sort(x)
str_sort(x, numeric = TRUE)
```
stringr/inst/doc/regular-expressions.html 0000644 0001762 0000144 00000140652 14524706130 020405 0 ustar ligges users
Regular expressions
Regular expressions
Regular expressions are a concise and flexible tool for describing
patterns in strings. This vignette describes the key features of
stringr’s regular expressions, as implemented by stringi. It is not a
tutorial, so if you’re unfamiliar regular expressions, I’d recommend
starting at https://r4ds.had.co.nz/strings.html. If you want to
master the details, I’d recommend reading the classic Mastering
Regular Expressions by Jeffrey E. F. Friedl.
Regular expressions are the default pattern engine in stringr. That
means when you use a pattern matching function with a bare string, it’s
equivalent to wrapping it in a call to regex():
# The regular call:
str_extract(fruit, "nana")
# Is shorthand for
str_extract(fruit, regex("nana"))
You will need to use regex() explicitly if you want to
override the default options, as you’ll see in examples below.
Basic matches
The simplest patterns match exact strings:
x <- c("apple", "banana", "pear")
str_extract(x, "an")
#> [1] NA "an" NA
You can perform a case-insensitive match using
ignore_case = TRUE:
bananas <- c("banana", "Banana", "BANANA")
str_detect(bananas, "banana")
#> [1] TRUE FALSE FALSE
str_detect(bananas, regex("banana", ignore_case = TRUE))
#> [1] TRUE TRUE TRUE
The next step up in complexity is ., which matches any
character except a newline:
str_extract(x, ".a.")
#> [1] NA "ban" "ear"
You can allow . to match everything, including
\n, by setting dotall = TRUE:
str_detect("\nX\n", ".X.")
#> [1] FALSE
str_detect("\nX\n", regex(".X.", dotall = TRUE))
#> [1] TRUE
Escaping
If “.” matches any character, how do you match a literal
“.”? You need to use an “escape” to tell the regular
expression you want to match it exactly, not use its special behaviour.
Like strings, regexps use the backslash, \, to escape
special behaviour. So to match an ., you need the regexp
\.. Unfortunately this creates a problem. We use strings to
represent regular expressions, and \ is also used as an
escape symbol in strings. So to create the regular expression
\. we need the string "\\.".
# To create the regular expression, we need \\
dot <- "\\."
# But the expression itself only contains one:
writeLines(dot)
#> \.
# And this tells R to look for an explicit .
str_extract(c("abc", "a.c", "bef"), "a\\.c")
#> [1] NA "a.c" NA
If \ is used as an escape character in regular
expressions, how do you match a literal \? Well you need to
escape it, creating the regular expression \\. To create
that regular expression, you need to use a string, which also needs to
escape \. That means to match a literal \ you
need to write "\\\\" — you need four backslashes to match
one!
x <- "a\\b"
writeLines(x)
#> a\b
str_extract(x, "\\\\")
#> [1] "\\"
In this vignette, I use \. to denote the regular
expression, and "\\." to denote the string that represents
the regular expression.
An alternative quoting mechanism is \Q...\E: all the
characters in ... are treated as exact matches. This is
useful if you want to exactly match user input as part of a regular
expression.
x <- c("a.b.c.d", "aeb")
starts_with <- "a.b"
str_detect(x, paste0("^", starts_with))
#> [1] TRUE TRUE
str_detect(x, paste0("^\\Q", starts_with, "\\E"))
#> [1] TRUE FALSE
Special characters
Escapes also allow you to specify individual characters that are
otherwise hard to type. You can specify individual unicode characters in
five ways, either as a variable number of hex digits (four is most
common), or by name:
\xhh: 2 hex digits.
\x{hhhh}: 1-6 hex digits.
\uhhhh: 4 hex digits.
\Uhhhhhhhh: 8 hex digits.
\N{name}, e.g. \N{grinning face}
matches the basic smiling emoji.
Similarly, you can specify many common control characters:
\a: bell.
\cX: match a control-X character.
\e: escape (\u001B).
\f: form feed (\u000C).
\n: line feed (\u000A).
\r: carriage return (\u000D).
\t: horizontal tabulation
(\u0009).
\0ooo match an octal character. ‘ooo’ is from one to
three octal digits, from 000 to 0377. The leading zero is
required.
(Many of these are only of historical interest and are only included
here for the sake of completeness.)
Matching multiple characters
There are a number of patterns that match more than one character.
You’ve already seen ., which matches any character (except
a newline). A closely related operator is \X, which matches
a grapheme cluster, a set of individual elements that
form a single symbol. For example, one way of representing “á” is as the
letter “a” plus an accent: . will match the component “a”,
while \X will match the complete symbol:
x <- "a\u0301"
str_extract(x, ".")
#> [1] "a"
str_extract(x, "\\X")
#> [1] "á"
There are five other escaped pairs that match narrower classes of
characters:
\d: matches any digit. The complement,
\D, matches any character that is not a decimal digit.
str_extract_all("1 + 2 = 3", "\\d+")[[1]]
#> [1] "1" "2" "3"
Technically, \d includes any character in the Unicode
Category of Nd (“Number, Decimal Digit”), which also includes numeric
symbols from other languages:
# Some Laotian numbers
str_detect("១២៣", "\\d")
#> [1] TRUE
\s: matches any whitespace. This includes tabs,
newlines, form feeds, and any character in the Unicode Z Category (which
includes a variety of space characters and other separators.). The
complement, \S, matches any non-whitespace character.
(text <- "Some \t badly\n\t\tspaced \f text")
#> [1] "Some \t badly\n\t\tspaced \f text"
str_replace_all(text, "\\s+", " ")
#> [1] "Some badly spaced text"
\p{property name} matches any character with
specific unicode property, like \p{Uppercase} or
\p{Diacritic}. The complement,
\P{property name}, matches all characters without the
property. A complete list of unicode properties can be found at http://www.unicode.org/reports/tr44/#Property_Index.
(text <- c('"Double quotes"', "«Guillemet»", "“Fancy quotes”"))
#> [1] "\"Double quotes\"" "«Guillemet»" "“Fancy quotes”"
str_replace_all(text, "\\p{quotation mark}", "'")
#> [1] "'Double quotes'" "'Guillemet'" "'Fancy quotes'"
\w matches any “word” character, which includes
alphabetic characters, marks and decimal numbers. The complement,
\W, matches any non-word character.
str_extract_all("Don't eat that!", "\\w+")[[1]]
#> [1] "Don" "t" "eat" "that"
str_split("Don't eat that!", "\\W")[[1]]
#> [1] "Don" "t" "eat" "that" ""
Technically, \w also matches connector punctuation,
\u200c (zero width connector), and \u200d
(zero width joiner), but these are rarely seen in the wild.
\b matches word boundaries, the transition between
word and non-word characters. \B matches the opposite:
boundaries that have either both word or non-word characters on either
side.
str_replace_all("The quick brown fox", "\\b", "_")
#> [1] "_The_ _quick_ _brown_ _fox_"
str_replace_all("The quick brown fox", "\\B", "_")
#> [1] "T_h_e q_u_i_c_k b_r_o_w_n f_o_x"
You can also create your own character classes using
[]:
[abc]: matches a, b, or c.[a-z]: matches every character between a and z (in
Unicode code point order).[^abc]: matches anything except a, b, or c.[\^\-]: matches ^ or -.
There are a number of pre-built classes that you can use inside
[]:
[:punct:]: punctuation.[:alpha:]: letters.[:lower:]: lowercase letters.[:upper:]: upperclass letters.[:digit:]: digits.[:xdigit:]: hex digits.[:alnum:]: letters and numbers.[:cntrl:]: control characters.[:graph:]: letters, numbers, and punctuation.[:print:]: letters, numbers, punctuation, and
whitespace.[:space:]: space characters (basically equivalent to
\s).[:blank:]: space and tab.
These all go inside the [] for character classes,
i.e. [[:digit:]AX] matches all digits, A, and X.
You can also using Unicode properties, like
[\p{Letter}], and various set operations, like
[\p{Letter}--\p{script=latin}]. See
?"stringi-search-charclass" for details.
Alternation
| is the alternation operator, which
will pick between one or more possible matches. For example,
abc|def will match abc or
def:
str_detect(c("abc", "def", "ghi"), "abc|def")
#> [1] TRUE TRUE FALSE
Note that the precedence for | is low:
abc|def is equivalent to (abc)|(def) not
ab(c|d)ef.
Grouping
You can use parentheses to override the default precedence rules:
str_extract(c("grey", "gray"), "gre|ay")
#> [1] "gre" "ay"
str_extract(c("grey", "gray"), "gr(e|a)y")
#> [1] "grey" "gray"
Parenthesis also define “groups” that you can refer to with
backreferences, like \1, \2
etc, and can be extracted with str_match(). For example,
the following regular expression finds all fruits that have a repeated
pair of letters:
pattern <- "(..)\\1"
fruit %>%
str_subset(pattern)
#> [1] "banana"
fruit %>%
str_subset(pattern) %>%
str_match(pattern)
#> [,1] [,2]
#> [1,] "anan" "an"
You can use (?:...), the non-grouping parentheses, to
control precedence but not capture the match in a group. This is
slightly more efficient than capturing parentheses.
str_match(c("grey", "gray"), "gr(e|a)y")
#> [,1] [,2]
#> [1,] "grey" "e"
#> [2,] "gray" "a"
str_match(c("grey", "gray"), "gr(?:e|a)y")
#> [,1]
#> [1,] "grey"
#> [2,] "gray"
This is most useful for more complex cases where you need to capture
matches and control precedence independently.
Anchors
By default, regular expressions will match any part of a string. It’s
often useful to anchor the regular expression so that
it matches from the start or end of the string:
^ matches the start of string.$ matches the end of the string.
x <- c("apple", "banana", "pear")
str_extract(x, "^a")
#> [1] "a" NA NA
str_extract(x, "a$")
#> [1] NA "a" NA
To match a literal “$” or “^”, you need to escape them,
\$, and \^.
For multiline strings, you can use
regex(multiline = TRUE). This changes the behaviour of
^ and $, and introduces three new
operators:
^ now matches the start of each line.
$ now matches the end of each line.
\A matches the start of the input.
\z matches the end of the input.
\Z matches the end of the input, but before the
final line terminator, if it exists.
x <- "Line 1\nLine 2\nLine 3\n"
str_extract_all(x, "^Line..")[[1]]
#> [1] "Line 1"
str_extract_all(x, regex("^Line..", multiline = TRUE))[[1]]
#> [1] "Line 1" "Line 2" "Line 3"
str_extract_all(x, regex("\\ALine..", multiline = TRUE))[[1]]
#> [1] "Line 1"
Repetition
You can control how many times a pattern matches with the repetition
operators:
?: 0 or 1.+: 1 or more.*: 0 or more.
x <- "1888 is the longest year in Roman numerals: MDCCCLXXXVIII"
str_extract(x, "CC?")
#> [1] "CC"
str_extract(x, "CC+")
#> [1] "CCC"
str_extract(x, 'C[LX]+')
#> [1] "CLXXX"
Note that the precedence of these operators is high, so you can
write: colou?r to match either American or British
spellings. That means most uses will need parentheses, like
bana(na)+.
You can also specify the number of matches precisely:
{n}: exactly n{n,}: n or more{n,m}: between n and m
str_extract(x, "C{2}")
#> [1] "CC"
str_extract(x, "C{2,}")
#> [1] "CCC"
str_extract(x, "C{2,3}")
#> [1] "CCC"
By default these matches are “greedy”: they will match the longest
string possible. You can make them “lazy”, matching the shortest string
possible by putting a ? after them:
??: 0 or 1, prefer 0.+?: 1 or more, match as few times as possible.*?: 0 or more, match as few times as possible.{n,}?: n or more, match as few times as possible.{n,m}?: between n and m, , match as few times as
possible, but at least n.
str_extract(x, c("C{2,3}", "C{2,3}?"))
#> [1] "CCC" "CC"
str_extract(x, c("C[LX]+", "C[LX]+?"))
#> [1] "CLXXX" "CL"
You can also make the matches possessive by putting a +
after them, which means that if later parts of the match fail, the
repetition will not be re-tried with a smaller number of characters.
This is an advanced feature used to improve performance in worst-case
scenarios (called “catastrophic backtracking”).
?+: 0 or 1, possessive.++: 1 or more, possessive.*+: 0 or more, possessive.{n}+: exactly n, possessive.{n,}+: n or more, possessive.{n,m}+: between n and m, possessive.
A related concept is the atomic-match parenthesis,
(?>...). If a later match fails and the engine needs to
back-track, an atomic match is kept as is: it succeeds or fails as a
whole. Compare the following two regular expressions:
str_detect("ABC", "(?>A|.B)C")
#> [1] FALSE
str_detect("ABC", "(?:A|.B)C")
#> [1] TRUE
The atomic match fails because it matches A, and then the next
character is a C so it fails. The regular match succeeds because it
matches A, but then C doesn’t match, so it back-tracks and tries B
instead.
Look arounds
These assertions look ahead or behind the current match without
“consuming” any characters (i.e. changing the input position).
(?=...): positive look-ahead assertion. Matches if
... matches at the current input.
(?!...): negative look-ahead assertion. Matches if
... does not match at the current
input.
(?<=...): positive look-behind assertion. Matches
if ... matches text preceding the current position, with
the last character of the match being the character just before the
current position. Length must be bounded
(i.e. no * or +).
(?<!...): negative look-behind assertion. Matches
if ... does not match text preceding the
current position. Length must be bounded
(i.e. no * or +).
These are useful when you want to check that a pattern exists, but
you don’t want to include it in the result:
x <- c("1 piece", "2 pieces", "3")
str_extract(x, "\\d+(?= pieces?)")
#> [1] "1" "2" NA
y <- c("100", "$400")
str_extract(y, "(?<=\\$)\\d+")
#> [1] NA "400"
stringr/inst/doc/from-base.html 0000644 0001762 0000144 00000266104 14524706127 016246 0 ustar ligges users
From base R
From base R
Sara Stoudt
This vignette compares stringr functions to their base R equivalents
to help users transitioning from using base R to stringr.
Overall differences
We’ll begin with a lookup table between the most important stringr
functions and their base R equivalents.
#> Warning: There was 1 warning in `dplyr::mutate()`.
#> ℹ In argument: `dplyr::across(.fns = ~paste0("`", .x, "`"))`.
#> Caused by warning:
#> ! Using `across()` without supplying `.cols` was deprecated in dplyr 1.1.0.
#> ℹ Please supply `.cols` instead.
| stringr |
base R |
str_detect(string, pattern)
|
|
|
|
str_extract(string, pattern)
|
regmatches(x, m = regexpr(pattern, text))
|
str_extract_all(string, pattern)
|
regmatches(x, m = gregexpr(pattern, text))
|
|
|
str_locate(string, pattern)
|
|
str_locate_all(string, pattern)
|
|
str_match(string, pattern)
|
regmatches(x, m = regexec(pattern, text))
|
|
|
str_replace(string, pattern, replacement)
|
sub(pattern, replacement, x)
|
str_replace_all(string, pattern, replacement)
|
gsub(pattern, replacement, x)
|
|
|
str_split(string, pattern)
|
|
str_sub(string, start, end)
|
|
str_subset(string, pattern)
|
grep(pattern, x, value = TRUE)
|
|
|
|
|
|
|
|
|
str_which(string, pattern)
|
|
|
|
Overall the main differences between base R and stringr are:
stringr functions start with str_ prefix; base R
string functions have no consistent naming scheme.
The order of inputs is usually different between base R and
stringr. In base R, the pattern to match usually comes
first; in stringr, the string to manupulate always comes
first. This makes stringr easier to use in pipes, and with
lapply() or purrr::map().
Functions in stringr tend to do less, where many of the string
processing functions in base R have multiple purposes.
The output and input of stringr functions has been carefully
designed. For example, the output of str_locate() can be
fed directly into str_sub(); the same is not true of
regpexpr() and substr().
Base functions use arguments (like perl,
fixed, and ignore.case) to control how the
pattern is interpreted. To avoid dependence between arguments, stringr
instead uses helper functions (like fixed(),
regex(), and coll()).
Next we’ll walk through each of the functions, noting the
similarities and important differences. These examples are adapted from
the stringr documentation and here they are contrasted with the
analogous base R operations.
Detect matches
str_detect(): Detect the presence or absence of a
pattern in a string
Suppose you want to know whether each word in a vector of fruit names
contains an “a”.
fruit <- c("apple", "banana", "pear", "pineapple")
# base
grepl(pattern = "a", x = fruit)
#> [1] TRUE TRUE TRUE TRUE
# stringr
str_detect(fruit, pattern = "a")
#> [1] TRUE TRUE TRUE TRUE
In base you would use grepl() (see the “l” and think
logical) while in stringr you use str_detect() (see the
verb “detect” and think of a yes/no action).
str_which(): Find positions matching a pattern
Now you want to identify the positions of the words in a vector of
fruit names that contain an “a”.
# base
grep(pattern = "a", x = fruit)
#> [1] 1 2 3 4
# stringr
str_which(fruit, pattern = "a")
#> [1] 1 2 3 4
In base you would use grep() while in stringr you use
str_which() (by analogy to which()).
str_count(): Count the number of matches in a
string
How many “a”s are in each fruit?
# base
loc <- gregexpr(pattern = "a", text = fruit, fixed = TRUE)
sapply(loc, function(x) length(attr(x, "match.length")))
#> [1] 1 3 1 1
# stringr
str_count(fruit, pattern = "a")
#> [1] 1 3 1 1
This information can be gleaned from gregexpr() in base,
but you need to look at the match.length attribute as the
vector uses a length-1 integer vector (-1) to indicate no
match.
str_locate(): Locate the position of patterns in a
string
Within each fruit, where does the first “p” occur? Where are all of
the “p”s?
fruit3 <- c("papaya", "lime", "apple")
# base
str(gregexpr(pattern = "p", text = fruit3))
#> List of 3
#> $ : int [1:2] 1 3
#> ..- attr(*, "match.length")= int [1:2] 1 1
#> ..- attr(*, "index.type")= chr "chars"
#> ..- attr(*, "useBytes")= logi TRUE
#> $ : int -1
#> ..- attr(*, "match.length")= int -1
#> ..- attr(*, "index.type")= chr "chars"
#> ..- attr(*, "useBytes")= logi TRUE
#> $ : int [1:2] 2 3
#> ..- attr(*, "match.length")= int [1:2] 1 1
#> ..- attr(*, "index.type")= chr "chars"
#> ..- attr(*, "useBytes")= logi TRUE
# stringr
str_locate(fruit3, pattern = "p")
#> start end
#> [1,] 1 1
#> [2,] NA NA
#> [3,] 2 2
str_locate_all(fruit3, pattern = "p")
#> [[1]]
#> start end
#> [1,] 1 1
#> [2,] 3 3
#>
#> [[2]]
#> start end
#>
#> [[3]]
#> start end
#> [1,] 2 2
#> [2,] 3 3
Subset strings
str_sub(): Extract and replace substrings from a
character vector
What if we want to grab part of a string?
hw <- "Hadley Wickham"
# base
substr(hw, start = 1, stop = 6)
#> [1] "Hadley"
substring(hw, first = 1)
#> [1] "Hadley Wickham"
# stringr
str_sub(hw, start = 1, end = 6)
#> [1] "Hadley"
str_sub(hw, start = 1)
#> [1] "Hadley Wickham"
str_sub(hw, end = 6)
#> [1] "Hadley"
In base you could use substr() or
substring(). The former requires both a start and stop of
the substring while the latter assumes the stop will be the end of the
string. The stringr version, str_sub() has the same
functionality, but also gives a default start value (the beginning of
the string). Both the base and stringr functions have the same order of
expected inputs.
In stringr you can use negative numbers to index from the right-hand
side string: -1 is the last letter, -2 is the second to last, and so
on.
str_sub(hw, start = 1, end = -1)
#> [1] "Hadley Wickham"
str_sub(hw, start = -5, end = -2)
#> [1] "ckha"
Both base R and stringr subset are vectorized over their parameters.
This means you can either choose the same subset across multiple strings
or specify different subsets for different strings.
al <- "Ada Lovelace"
# base
substr(c(hw,al), start = 1, stop = 6)
#> [1] "Hadley" "Ada Lo"
substr(c(hw,al), start = c(1,1), stop = c(6,7))
#> [1] "Hadley" "Ada Lov"
# stringr
str_sub(c(hw,al), start = 1, end = -1)
#> [1] "Hadley Wickham" "Ada Lovelace"
str_sub(c(hw,al), start = c(1,1), end = c(-1,-2))
#> [1] "Hadley Wickham" "Ada Lovelac"
stringr will automatically recycle the first argument to the same
length as start and stop:
str_sub(hw, start = 1:5)
#> [1] "Hadley Wickham" "adley Wickham" "dley Wickham" "ley Wickham"
#> [5] "ey Wickham"
Whereas the base equivalent silently uses just the first value:
substr(hw, start = 1:5, stop = 15)
#> [1] "Hadley Wickham"
str_sub() <-: Subset assignment
substr() behaves in a surprising way when you replace a
substring with a different number of characters:
# base
x <- "ABCDEF"
substr(x, 1, 3) <- "x"
x
#> [1] "xBCDEF"
str_sub() does what you would expect:
# stringr
x <- "ABCDEF"
str_sub(x, 1, 3) <- "x"
x
#> [1] "xDEF"
str_subset(): Keep strings matching a pattern, or find
positions
We may want to retrieve strings that contain a pattern of
interest:
# base
grep(pattern = "g", x = fruit, value = TRUE)
#> character(0)
# stringr
str_subset(fruit, pattern = "g")
#> character(0)
Manage lengths
str_length(): The length of a string
To determine the length of a string, base R uses nchar()
(not to be confused with length() which gives the length of
vectors, etc.) while stringr uses str_length().
# base
nchar(letters)
#> [1] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
# stringr
str_length(letters)
#> [1] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
There are some subtle differences between base and stringr here.
nchar() requires a character vector, so it will return an
error if used on a factor. str_length() can handle a factor
input.
# base
nchar(factor("abc"))
#> Error in nchar(factor("abc")): 'nchar()' requires a character vector
# stringr
str_length(factor("abc"))
#> [1] 3
Note that “characters” is a poorly defined concept, and technically
both nchar() and str_length() returns the
number of code points. This is usually the same as what you’d consider
to be a charcter, but not always:
x <- c("\u00fc", "u\u0308")
x
#> [1] "ü" "ü"
nchar(x)
#> [1] 1 2
str_length(x)
#> [1] 1 2
str_pad(): Pad a string
To pad a string to a certain width, use stringr’s
str_pad(). In base R you could use sprintf(),
but unlike str_pad(), sprintf() has many other
functionalities.
# base
sprintf("%30s", "hadley")
#> [1] " hadley"
sprintf("%-30s", "hadley")
#> [1] "hadley "
# "both" is not as straightforward
# stringr
rbind(
str_pad("hadley", 30, "left"),
str_pad("hadley", 30, "right"),
str_pad("hadley", 30, "both")
)
#> [,1]
#> [1,] " hadley"
#> [2,] "hadley "
#> [3,] " hadley "
str_trunc(): Truncate a character string
The stringr package provides an easy way to truncate a character
string: str_trunc(). Base R has no function to do this
directly.
x <- "This string is moderately long"
# stringr
rbind(
str_trunc(x, 20, "right"),
str_trunc(x, 20, "left"),
str_trunc(x, 20, "center")
)
#> [,1]
#> [1,] "This string is mo..."
#> [2,] "...s moderately long"
#> [3,] "This stri...ely long"
str_trim(): Trim whitespace from a string
Similarly, stringr provides str_trim() to trim
whitespace from a string. This is analogous to base R’s
trimws() added in R 3.3.0.
# base
trimws(" String with trailing and leading white space\t")
#> [1] "String with trailing and leading white space"
trimws("\n\nString with trailing and leading white space\n\n")
#> [1] "String with trailing and leading white space"
# stringr
str_trim(" String with trailing and leading white space\t")
#> [1] "String with trailing and leading white space"
str_trim("\n\nString with trailing and leading white space\n\n")
#> [1] "String with trailing and leading white space"
The stringr function str_squish() allows for extra
whitespace within a string to be trimmed (in contrast to
str_trim() which removes whitespace at the beginning and/or
end of string). In base R, one might take advantage of
gsub() to accomplish the same effect.
# stringr
str_squish(" String with trailing, middle, and leading white space\t")
#> [1] "String with trailing, middle, and leading white space"
str_squish("\n\nString with excess, trailing and leading white space\n\n")
#> [1] "String with excess, trailing and leading white space"
Mutate strings
str_replace(): Replace matched patterns in a
string
To replace certain patterns within a string, stringr provides the
functions str_replace() and str_replace_all().
The base R equivalents are sub() and gsub().
Note the difference in default input order again.
fruits <- c("apple", "banana", "pear", "pineapple")
# base
sub("[aeiou]", "-", fruits)
#> [1] "-pple" "b-nana" "p-ar" "p-neapple"
gsub("[aeiou]", "-", fruits)
#> [1] "-ppl-" "b-n-n-" "p--r" "p-n--ppl-"
# stringr
str_replace(fruits, "[aeiou]", "-")
#> [1] "-pple" "b-nana" "p-ar" "p-neapple"
str_replace_all(fruits, "[aeiou]", "-")
#> [1] "-ppl-" "b-n-n-" "p--r" "p-n--ppl-"
case: Convert case of a string
Both stringr and base R have functions to convert to upper and lower
case. Title case is also provided in stringr.
dog <- "The quick brown dog"
# base
toupper(dog)
#> [1] "THE QUICK BROWN DOG"
tolower(dog)
#> [1] "the quick brown dog"
tools::toTitleCase(dog)
#> [1] "The Quick Brown Dog"
# stringr
str_to_upper(dog)
#> [1] "THE QUICK BROWN DOG"
str_to_lower(dog)
#> [1] "the quick brown dog"
str_to_title(dog)
#> [1] "The Quick Brown Dog"
In stringr we can control the locale, while in base R locale
distinctions are controlled with global variables. Therefore, the output
of your base R code may vary across different computers with different
global settings.
# stringr
str_to_upper("i") # English
#> [1] "I"
str_to_upper("i", locale = "tr") # Turkish
#> [1] "İ"
Join and split
str_flatten(): Flatten a string
If we want to take elements of a string vector and collapse them to a
single string we can use the collapse argument in
paste() or use stringr’s str_flatten().
# base
paste0(letters, collapse = "-")
#> [1] "a-b-c-d-e-f-g-h-i-j-k-l-m-n-o-p-q-r-s-t-u-v-w-x-y-z"
# stringr
str_flatten(letters, collapse = "-")
#> [1] "a-b-c-d-e-f-g-h-i-j-k-l-m-n-o-p-q-r-s-t-u-v-w-x-y-z"
The advantage of str_flatten() is that it always returns
a vector the same length as its input; to predict the return length of
paste() you must carefully read all arguments.
str_dup(): duplicate strings within a character
vector
To duplicate strings within a character vector use
strrep() (in R 3.3.0 or greater) or
str_dup():
fruit <- c("apple", "pear", "banana")
# base
strrep(fruit, 2)
#> [1] "appleapple" "pearpear" "bananabanana"
strrep(fruit, 1:3)
#> [1] "apple" "pearpear" "bananabananabanana"
# stringr
str_dup(fruit, 2)
#> [1] "appleapple" "pearpear" "bananabanana"
str_dup(fruit, 1:3)
#> [1] "apple" "pearpear" "bananabananabanana"
str_split(): Split up a string into pieces
To split a string into pieces with breaks based on a particular
pattern match stringr uses str_split() and base R uses
strsplit(). Unlike most other functions,
strsplit() starts with the character vector to modify.
fruits <- c(
"apples and oranges and pears and bananas",
"pineapples and mangos and guavas"
)
# base
strsplit(fruits, " and ")
#> [[1]]
#> [1] "apples" "oranges" "pears" "bananas"
#>
#> [[2]]
#> [1] "pineapples" "mangos" "guavas"
# stringr
str_split(fruits, " and ")
#> [[1]]
#> [1] "apples" "oranges" "pears" "bananas"
#>
#> [[2]]
#> [1] "pineapples" "mangos" "guavas"
The stringr package’s str_split() allows for more
control over the split, including restricting the number of possible
matches.
# stringr
str_split(fruits, " and ", n = 3)
#> [[1]]
#> [1] "apples" "oranges" "pears and bananas"
#>
#> [[2]]
#> [1] "pineapples" "mangos" "guavas"
str_split(fruits, " and ", n = 2)
#> [[1]]
#> [1] "apples" "oranges and pears and bananas"
#>
#> [[2]]
#> [1] "pineapples" "mangos and guavas"
str_glue(): Interpolate strings
It’s often useful to interpolate varying values into a fixed string.
In base R, you can use sprintf() for this purpose; stringr
provides a wrapper for the more general purpose glue package.
name <- "Fred"
age <- 50
anniversary <- as.Date("1991-10-12")
# base
sprintf(
"My name is %s my age next year is %s and my anniversary is %s.",
name,
age + 1,
format(anniversary, "%A, %B %d, %Y")
)
#> [1] "My name is Fred my age next year is 51 and my anniversary is Saturday, October 12, 1991."
# stringr
str_glue(
"My name is {name}, ",
"my age next year is {age + 1}, ",
"and my anniversary is {format(anniversary, '%A, %B %d, %Y')}."
)
#> My name is Fred, my age next year is 51, and my anniversary is Saturday, October 12, 1991.
Order strings
str_order(): Order or sort a character vector
Both base R and stringr have separate functions to order and sort
strings.
# base
order(letters)
#> [1] 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] 26
sort(letters)
#> [1] "a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" "n" "o" "p" "q" "r" "s"
#> [20] "t" "u" "v" "w" "x" "y" "z"
# stringr
str_order(letters)
#> [1] 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] 26
str_sort(letters)
#> [1] "a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" "n" "o" "p" "q" "r" "s"
#> [20] "t" "u" "v" "w" "x" "y" "z"
Some options in str_order() and str_sort()
don’t have analogous base R options. For example, the stringr functions
have a locale argument to control how to order or sort. In
base R the locale is a global setting, so the outputs of
sort() and order() may differ across different
computers. For example, in the Norwegian alphabet, å comes after z:
x <- c("å", "a", "z")
str_sort(x)
#> [1] "a" "å" "z"
str_sort(x, locale = "no")
#> [1] "a" "z" "å"
The stringr functions also have a numeric argument to
sort digits numerically instead of treating them as strings.
# stringr
x <- c("100a10", "100a5", "2b", "2a")
str_sort(x)
#> [1] "100a10" "100a5" "2a" "2b"
str_sort(x, numeric = TRUE)
#> [1] "2a" "2b" "100a5" "100a10"
stringr/inst/doc/regular-expressions.Rmd 0000644 0001762 0000144 00000034476 14520174727 020200 0 ustar ligges users ---
title: "Regular expressions"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Regular expressions}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
library(stringr)
```
Regular expressions are a concise and flexible tool for describing patterns in strings. This vignette describes the key features of stringr's regular expressions, as implemented by [stringi](https://github.com/gagolews/stringi). It is not a tutorial, so if you're unfamiliar regular expressions, I'd recommend starting at . If you want to master the details, I'd recommend reading the classic [_Mastering Regular Expressions_](https://www.amazon.com/Mastering-Regular-Expressions-Jeffrey-Friedl/dp/0596528124) by Jeffrey E. F. Friedl.
Regular expressions are the default pattern engine in stringr. That means when you use a pattern matching function with a bare string, it's equivalent to wrapping it in a call to `regex()`:
```{r, eval = FALSE}
# The regular call:
str_extract(fruit, "nana")
# Is shorthand for
str_extract(fruit, regex("nana"))
```
You will need to use `regex()` explicitly if you want to override the default options, as you'll see in examples below.
## Basic matches
The simplest patterns match exact strings:
```{r}
x <- c("apple", "banana", "pear")
str_extract(x, "an")
```
You can perform a case-insensitive match using `ignore_case = TRUE`:
```{r}
bananas <- c("banana", "Banana", "BANANA")
str_detect(bananas, "banana")
str_detect(bananas, regex("banana", ignore_case = TRUE))
```
The next step up in complexity is `.`, which matches any character except a newline:
```{r}
str_extract(x, ".a.")
```
You can allow `.` to match everything, including `\n`, by setting `dotall = TRUE`:
```{r}
str_detect("\nX\n", ".X.")
str_detect("\nX\n", regex(".X.", dotall = TRUE))
```
## Escaping
If "`.`" matches any character, how do you match a literal "`.`"? You need to use an "escape" to tell the regular expression you want to match it exactly, not use its special behaviour. Like strings, regexps use the backslash, `\`, to escape special behaviour. So to match an `.`, you need the regexp `\.`. Unfortunately this creates a problem. We use strings to represent regular expressions, and `\` is also used as an escape symbol in strings. So to create the regular expression `\.` we need the string `"\\."`.
```{r}
# To create the regular expression, we need \\
dot <- "\\."
# But the expression itself only contains one:
writeLines(dot)
# And this tells R to look for an explicit .
str_extract(c("abc", "a.c", "bef"), "a\\.c")
```
If `\` is used as an escape character in regular expressions, how do you match a literal `\`? Well you need to escape it, creating the regular expression `\\`. To create that regular expression, you need to use a string, which also needs to escape `\`. That means to match a literal `\` you need to write `"\\\\"` --- you need four backslashes to match one!
```{r}
x <- "a\\b"
writeLines(x)
str_extract(x, "\\\\")
```
In this vignette, I use `\.` to denote the regular expression, and `"\\."` to denote the string that represents the regular expression.
An alternative quoting mechanism is `\Q...\E`: all the characters in `...` are treated as exact matches. This is useful if you want to exactly match user input as part of a regular expression.
```{r}
x <- c("a.b.c.d", "aeb")
starts_with <- "a.b"
str_detect(x, paste0("^", starts_with))
str_detect(x, paste0("^\\Q", starts_with, "\\E"))
```
## Special characters
Escapes also allow you to specify individual characters that are otherwise hard to type. You can specify individual unicode characters in five ways, either as a variable number of hex digits (four is most common), or by name:
* `\xhh`: 2 hex digits.
* `\x{hhhh}`: 1-6 hex digits.
* `\uhhhh`: 4 hex digits.
* `\Uhhhhhhhh`: 8 hex digits.
* `\N{name}`, e.g. `\N{grinning face}` matches the basic smiling emoji.
Similarly, you can specify many common control characters:
* `\a`: bell.
* `\cX`: match a control-X character.
* `\e`: escape (`\u001B`).
* `\f`: form feed (`\u000C`).
* `\n`: line feed (`\u000A`).
* `\r`: carriage return (`\u000D`).
* `\t`: horizontal tabulation (`\u0009`).
* `\0ooo` match an octal character. 'ooo' is from one to three octal digits,
from 000 to 0377. The leading zero is required.
(Many of these are only of historical interest and are only included here for the sake of completeness.)
## Matching multiple characters
There are a number of patterns that match more than one character. You've already seen `.`, which matches any character (except a newline). A closely related operator is `\X`, which matches a __grapheme cluster__, a set of individual elements that form a single symbol. For example, one way of representing "á" is as the letter "a" plus an accent: `.` will match the component "a", while `\X` will match the complete symbol:
```{r}
x <- "a\u0301"
str_extract(x, ".")
str_extract(x, "\\X")
```
There are five other escaped pairs that match narrower classes of characters:
* `\d`: matches any digit. The complement, `\D`, matches any character that
is not a decimal digit.
```{r}
str_extract_all("1 + 2 = 3", "\\d+")[[1]]
```
Technically, `\d` includes any character in the Unicode Category of Nd
("Number, Decimal Digit"), which also includes numeric symbols from other
languages:
```{r}
# Some Laotian numbers
str_detect("១២៣", "\\d")
```
* `\s`: matches any whitespace. This includes tabs, newlines, form feeds,
and any character in the Unicode Z Category (which includes a variety of
space characters and other separators.). The complement, `\S`, matches any
non-whitespace character.
```{r}
(text <- "Some \t badly\n\t\tspaced \f text")
str_replace_all(text, "\\s+", " ")
```
* `\p{property name}` matches any character with specific unicode property,
like `\p{Uppercase}` or `\p{Diacritic}`. The complement,
`\P{property name}`, matches all characters without the property.
A complete list of unicode properties can be found at
.
```{r}
(text <- c('"Double quotes"', "«Guillemet»", "“Fancy quotes”"))
str_replace_all(text, "\\p{quotation mark}", "'")
```
* `\w` matches any "word" character, which includes alphabetic characters,
marks and decimal numbers. The complement, `\W`, matches any non-word
character.
```{r}
str_extract_all("Don't eat that!", "\\w+")[[1]]
str_split("Don't eat that!", "\\W")[[1]]
```
Technically, `\w` also matches connector punctuation, `\u200c` (zero width
connector), and `\u200d` (zero width joiner), but these are rarely seen in
the wild.
* `\b` matches word boundaries, the transition between word and non-word
characters. `\B` matches the opposite: boundaries that have either both
word or non-word characters on either side.
```{r}
str_replace_all("The quick brown fox", "\\b", "_")
str_replace_all("The quick brown fox", "\\B", "_")
```
You can also create your own __character classes__ using `[]`:
* `[abc]`: matches a, b, or c.
* `[a-z]`: matches every character between a and z
(in Unicode code point order).
* `[^abc]`: matches anything except a, b, or c.
* `[\^\-]`: matches `^` or `-`.
There are a number of pre-built classes that you can use inside `[]`:
* `[:punct:]`: punctuation.
* `[:alpha:]`: letters.
* `[:lower:]`: lowercase letters.
* `[:upper:]`: upperclass letters.
* `[:digit:]`: digits.
* `[:xdigit:]`: hex digits.
* `[:alnum:]`: letters and numbers.
* `[:cntrl:]`: control characters.
* `[:graph:]`: letters, numbers, and punctuation.
* `[:print:]`: letters, numbers, punctuation, and whitespace.
* `[:space:]`: space characters (basically equivalent to `\s`).
* `[:blank:]`: space and tab.
These all go inside the `[]` for character classes, i.e. `[[:digit:]AX]` matches all digits, A, and X.
You can also using Unicode properties, like `[\p{Letter}]`, and various set operations, like `[\p{Letter}--\p{script=latin}]`. See `?"stringi-search-charclass"` for details.
## Alternation
`|` is the __alternation__ operator, which will pick between one or more possible matches. For example, `abc|def` will match `abc` or `def`:
```{r}
str_detect(c("abc", "def", "ghi"), "abc|def")
```
Note that the precedence for `|` is low: `abc|def` is equivalent to `(abc)|(def)` not `ab(c|d)ef`.
## Grouping
You can use parentheses to override the default precedence rules:
```{r}
str_extract(c("grey", "gray"), "gre|ay")
str_extract(c("grey", "gray"), "gr(e|a)y")
```
Parenthesis also define "groups" that you can refer to with __backreferences__, like `\1`, `\2` etc, and can be extracted with `str_match()`. For example, the following regular expression finds all fruits that have a repeated pair of letters:
```{r}
pattern <- "(..)\\1"
fruit %>%
str_subset(pattern)
fruit %>%
str_subset(pattern) %>%
str_match(pattern)
```
You can use `(?:...)`, the non-grouping parentheses, to control precedence but not capture the match in a group. This is slightly more efficient than capturing parentheses.
```{r}
str_match(c("grey", "gray"), "gr(e|a)y")
str_match(c("grey", "gray"), "gr(?:e|a)y")
```
This is most useful for more complex cases where you need to capture matches and control precedence independently.
## Anchors
By default, regular expressions will match any part of a string. It's often useful to __anchor__ the regular expression so that it matches from the start or end of the string:
* `^` matches the start of string.
* `$` matches the end of the string.
```{r}
x <- c("apple", "banana", "pear")
str_extract(x, "^a")
str_extract(x, "a$")
```
To match a literal "$" or "^", you need to escape them, `\$`, and `\^`.
For multiline strings, you can use `regex(multiline = TRUE)`. This changes the behaviour of `^` and `$`, and introduces three new operators:
* `^` now matches the start of each line.
* `$` now matches the end of each line.
* `\A` matches the start of the input.
* `\z` matches the end of the input.
* `\Z` matches the end of the input, but before the final line terminator,
if it exists.
```{r}
x <- "Line 1\nLine 2\nLine 3\n"
str_extract_all(x, "^Line..")[[1]]
str_extract_all(x, regex("^Line..", multiline = TRUE))[[1]]
str_extract_all(x, regex("\\ALine..", multiline = TRUE))[[1]]
```
## Repetition
You can control how many times a pattern matches with the repetition operators:
* `?`: 0 or 1.
* `+`: 1 or more.
* `*`: 0 or more.
```{r}
x <- "1888 is the longest year in Roman numerals: MDCCCLXXXVIII"
str_extract(x, "CC?")
str_extract(x, "CC+")
str_extract(x, 'C[LX]+')
```
Note that the precedence of these operators is high, so you can write: `colou?r` to match either American or British spellings. That means most uses will need parentheses, like `bana(na)+`.
You can also specify the number of matches precisely:
* `{n}`: exactly n
* `{n,}`: n or more
* `{n,m}`: between n and m
```{r}
str_extract(x, "C{2}")
str_extract(x, "C{2,}")
str_extract(x, "C{2,3}")
```
By default these matches are "greedy": they will match the longest string possible. You can make them "lazy", matching the shortest string possible by putting a `?` after them:
* `??`: 0 or 1, prefer 0.
* `+?`: 1 or more, match as few times as possible.
* `*?`: 0 or more, match as few times as possible.
* `{n,}?`: n or more, match as few times as possible.
* `{n,m}?`: between n and m, , match as few times as possible, but at least n.
```{r}
str_extract(x, c("C{2,3}", "C{2,3}?"))
str_extract(x, c("C[LX]+", "C[LX]+?"))
```
You can also make the matches possessive by putting a `+` after them, which means that if later parts of the match fail, the repetition will not be re-tried with a smaller number of characters. This is an advanced feature used to improve performance in worst-case scenarios (called "catastrophic backtracking").
* `?+`: 0 or 1, possessive.
* `++`: 1 or more, possessive.
* `*+`: 0 or more, possessive.
* `{n}+`: exactly n, possessive.
* `{n,}+`: n or more, possessive.
* `{n,m}+`: between n and m, possessive.
A related concept is the __atomic-match__ parenthesis, `(?>...)`. If a later match fails and the engine needs to back-track, an atomic match is kept as is: it succeeds or fails as a whole. Compare the following two regular expressions:
```{r}
str_detect("ABC", "(?>A|.B)C")
str_detect("ABC", "(?:A|.B)C")
```
The atomic match fails because it matches A, and then the next character is a C so it fails. The regular match succeeds because it matches A, but then C doesn't match, so it back-tracks and tries B instead.
## Look arounds
These assertions look ahead or behind the current match without "consuming" any characters (i.e. changing the input position).
* `(?=...)`: positive look-ahead assertion. Matches if `...` matches at the
current input.
* `(?!...)`: negative look-ahead assertion. Matches if `...` __does not__
match at the current input.
* `(?<=...)`: positive look-behind assertion. Matches if `...` matches text
preceding the current position, with the last character of the match
being the character just before the current position. Length must be bounded
(i.e. no `*` or `+`).
* `(?
Introduction to stringr
Introduction to stringr
There are four main families of functions in stringr:
Character manipulation: these functions allow you to manipulate
individual characters within the strings in character vectors.
Whitespace tools to add, remove, and manipulate
whitespace.
Locale sensitive operations whose operations will vary from
locale to locale.
Pattern matching functions. These recognise four engines of
pattern description. The most common is regular expressions, but there
are three other tools.
Getting and setting individual characters
You can get the length of the string with
str_length():
str_length("abc")
#> [1] 3
This is now equivalent to the base R function nchar().
Previously it was needed to work around issues with nchar()
such as the fact that it returned 2 for nchar(NA). This has
been fixed as of R 3.3.0, so it is no longer so important.
You can access individual character using str_sub(). It
takes three arguments: a character vector, a start position
and an end position. Either position can either be a
positive integer, which counts from the left, or a negative integer
which counts from the right. The positions are inclusive, and if longer
than the string, will be silently truncated.
x <- c("abcdef", "ghifjk")
# The 3rd letter
str_sub(x, 3, 3)
#> [1] "c" "i"
# The 2nd to 2nd-to-last character
str_sub(x, 2, -2)
#> [1] "bcde" "hifj"
You can also use str_sub() to modify strings:
str_sub(x, 3, 3) <- "X"
x
#> [1] "abXdef" "ghXfjk"
To duplicate individual strings, you can use
str_dup():
str_dup(x, c(2, 3))
#> [1] "abXdefabXdef" "ghXfjkghXfjkghXfjk"
Whitespace
Three functions add, remove, or modify whitespace:
str_pad() pads a string to a fixed length by adding
extra whitespace on the left, right, or both sides.
x <- c("abc", "defghi")
str_pad(x, 10) # default pads on left
#> [1] " abc" " defghi"
str_pad(x, 10, "both")
#> [1] " abc " " defghi "
(You can pad with other characters by using the pad
argument.)
str_pad() will never make a string shorter:
str_pad(x, 4)
#> [1] " abc" "defghi"
So if you want to ensure that all strings are the same length (often
useful for print methods), combine str_pad() and
str_trunc():
x <- c("Short", "This is a long string")
x %>%
str_trunc(10) %>%
str_pad(10, "right")
#> [1] "Short " "This is..."
The opposite of str_pad() is
str_trim(), which removes leading and trailing
whitespace:
x <- c(" a ", "b ", " c")
str_trim(x)
#> [1] "a" "b" "c"
str_trim(x, "left")
#> [1] "a " "b " "c"
You can use str_wrap() to modify existing whitespace
in order to wrap a paragraph of text, such that the length of each line
is as similar as possible.
jabberwocky <- str_c(
"`Twas brillig, and the slithy toves ",
"did gyre and gimble in the wabe: ",
"All mimsy were the borogoves, ",
"and the mome raths outgrabe. "
)
cat(str_wrap(jabberwocky, width = 40))
#> `Twas brillig, and the slithy toves did
#> gyre and gimble in the wabe: All mimsy
#> were the borogoves, and the mome raths
#> outgrabe.
Locale sensitive
A handful of stringr functions are locale-sensitive: they will
perform differently in different regions of the world. These functions
are case transformation functions:
x <- "I like horses."
str_to_upper(x)
#> [1] "I LIKE HORSES."
str_to_title(x)
#> [1] "I Like Horses."
str_to_lower(x)
#> [1] "i like horses."
# Turkish has two sorts of i: with and without the dot
str_to_lower(x, "tr")
#> [1] "ı like horses."
String ordering and sorting:
x <- c("y", "i", "k")
str_order(x)
#> [1] 2 3 1
str_sort(x)
#> [1] "i" "k" "y"
# In Lithuanian, y comes between i and k
str_sort(x, locale = "lt")
#> [1] "i" "y" "k"
The locale always defaults to English to ensure that the default
behaviour is identical across systems. Locales always include a two
letter ISO-639-1 language code (like “en” for English or “zh” for
Chinese), and optionally a ISO-3166 country code (like “en_UK” vs
“en_US”). You can see a complete list of available locales by running
stringi::stri_locale_list().
Pattern matching
The vast majority of stringr functions work with patterns. These are
parameterised by the task they perform and the types of patterns they
match.
Tasks
Each pattern matching function has the same first two arguments, a
character vector of strings to process and a single
pattern to match. stringr provides pattern matching
functions to detect, locate,
extract, match,
replace, and split strings. I’ll
illustrate how they work with some strings and a regular expression
designed to match (US) phone numbers:
strings <- c(
"apple",
"219 733 8965",
"329-293-8753",
"Work: 579-499-7527; Home: 543.355.3679"
)
phone <- "([2-9][0-9]{2})[- .]([0-9]{3})[- .]([0-9]{4})"
str_detect() detects the presence or absence of a
pattern and returns a logical vector (similar to grepl()).
str_subset() returns the elements of a character vector
that match a regular expression (similar to grep() with
value = TRUE)`.
# Which strings contain phone numbers?
str_detect(strings, phone)
#> [1] FALSE TRUE TRUE TRUE
str_subset(strings, phone)
#> [1] "219 733 8965"
#> [2] "329-293-8753"
#> [3] "Work: 579-499-7527; Home: 543.355.3679"
str_count() counts the number of matches:
# How many phone numbers in each string?
str_count(strings, phone)
#> [1] 0 1 1 2
str_locate() locates the first
position of a pattern and returns a numeric matrix with columns start
and end. str_locate_all() locates all matches, returning a
list of numeric matrices. Similar to regexpr() and
gregexpr().
# Where in the string is the phone number located?
(loc <- str_locate(strings, phone))
#> start end
#> [1,] NA NA
#> [2,] 1 12
#> [3,] 1 12
#> [4,] 7 18
str_locate_all(strings, phone)
#> [[1]]
#> start end
#>
#> [[2]]
#> start end
#> [1,] 1 12
#>
#> [[3]]
#> start end
#> [1,] 1 12
#>
#> [[4]]
#> start end
#> [1,] 7 18
#> [2,] 27 38
str_extract() extracts text corresponding to the
first match, returning a character vector.
str_extract_all() extracts all matches and returns a list
of character vectors.
# What are the phone numbers?
str_extract(strings, phone)
#> [1] NA "219 733 8965" "329-293-8753" "579-499-7527"
str_extract_all(strings, phone)
#> [[1]]
#> character(0)
#>
#> [[2]]
#> [1] "219 733 8965"
#>
#> [[3]]
#> [1] "329-293-8753"
#>
#> [[4]]
#> [1] "579-499-7527" "543.355.3679"
str_extract_all(strings, phone, simplify = TRUE)
#> [,1] [,2]
#> [1,] "" ""
#> [2,] "219 733 8965" ""
#> [3,] "329-293-8753" ""
#> [4,] "579-499-7527" "543.355.3679"
str_match() extracts capture groups formed by
() from the first match. It returns a
character matrix with one column for the complete match and one column
for each group. str_match_all() extracts capture groups
from all matches and returns a list of character matrices. Similar to
regmatches().
# Pull out the three components of the match
str_match(strings, phone)
#> [,1] [,2] [,3] [,4]
#> [1,] NA NA NA NA
#> [2,] "219 733 8965" "219" "733" "8965"
#> [3,] "329-293-8753" "329" "293" "8753"
#> [4,] "579-499-7527" "579" "499" "7527"
str_match_all(strings, phone)
#> [[1]]
#> [,1] [,2] [,3] [,4]
#>
#> [[2]]
#> [,1] [,2] [,3] [,4]
#> [1,] "219 733 8965" "219" "733" "8965"
#>
#> [[3]]
#> [,1] [,2] [,3] [,4]
#> [1,] "329-293-8753" "329" "293" "8753"
#>
#> [[4]]
#> [,1] [,2] [,3] [,4]
#> [1,] "579-499-7527" "579" "499" "7527"
#> [2,] "543.355.3679" "543" "355" "3679"
str_replace() replaces the first
matched pattern and returns a character vector.
str_replace_all() replaces all matches. Similar to
sub() and gsub().
str_replace(strings, phone, "XXX-XXX-XXXX")
#> [1] "apple"
#> [2] "XXX-XXX-XXXX"
#> [3] "XXX-XXX-XXXX"
#> [4] "Work: XXX-XXX-XXXX; Home: 543.355.3679"
str_replace_all(strings, phone, "XXX-XXX-XXXX")
#> [1] "apple"
#> [2] "XXX-XXX-XXXX"
#> [3] "XXX-XXX-XXXX"
#> [4] "Work: XXX-XXX-XXXX; Home: XXX-XXX-XXXX"
str_split_fixed() splits a string into a
fixed number of pieces based on a pattern and returns a
character matrix. str_split() splits a string into a
variable number of pieces and returns a list of
character vectors.
str_split("a-b-c", "-")
#> [[1]]
#> [1] "a" "b" "c"
str_split_fixed("a-b-c", "-", n = 2)
#> [,1] [,2]
#> [1,] "a" "b-c"
Engines
There are four main engines that stringr can use to describe
patterns:
Regular expressions, the default, as shown above, and described
in vignette("regular-expressions").
Fixed bytewise matching, with fixed().
Locale-sensitive character matching, with
coll()
Text boundary analysis with boundary().
Fixed matches
fixed(x) only matches the exact sequence of bytes
specified by x. This is a very limited “pattern”, but the
restriction can make matching much faster. Beware using
fixed() with non-English data. It is problematic because
there are often multiple ways of representing the same character. For
example, there are two ways to define “á”: either as a single character
or as an “a” plus an accent:
a1 <- "\u00e1"
a2 <- "a\u0301"
c(a1, a2)
#> [1] "á" "á"
a1 == a2
#> [1] FALSE
They render identically, but because they’re defined differently,
fixed() doesn’t find a match. Instead, you can use
coll(), explained below, to respect human character
comparison rules:
str_detect(a1, fixed(a2))
#> [1] FALSE
str_detect(a1, coll(a2))
#> [1] TRUE
Collation search
coll(x) looks for a match to x using
human-language collation rules, and is particularly
important if you want to do case insensitive matching. Collation rules
differ around the world, so you’ll also need to supply a
locale parameter.
i <- c("I", "İ", "i", "ı")
i
#> [1] "I" "İ" "i" "ı"
str_subset(i, coll("i", ignore_case = TRUE))
#> [1] "I" "i"
str_subset(i, coll("i", ignore_case = TRUE, locale = "tr"))
#> [1] "İ" "i"
The downside of coll() is speed. Because the rules for
recognising which characters are the same are complicated,
coll() is relatively slow compared to regex()
and fixed(). Note that when both fixed() and
regex() have ignore_case arguments, they
perform a much simpler comparison than coll().
Boundary
boundary() matches boundaries between characters, lines,
sentences or words. It’s most useful with str_split(), but
can be used with all pattern matching functions:
x <- "This is a sentence."
str_split(x, boundary("word"))
#> [[1]]
#> [1] "This" "is" "a" "sentence"
str_count(x, boundary("word"))
#> [1] 4
str_extract_all(x, boundary("word"))
#> [[1]]
#> [1] "This" "is" "a" "sentence"
By convention, "" is treated as
boundary("character"):
str_split(x, "")
#> [[1]]
#> [1] "T" "h" "i" "s" " " "i" "s" " " "a" " " "s" "e" "n" "t" "e" "n" "c" "e" "."
str_count(x, "")
#> [1] 19
stringr/inst/doc/stringr.R 0000644 0001762 0000144 00000010271 14524706130 015302 0 ustar ligges users ## ----include = FALSE----------------------------------------------------------
library(stringr)
knitr::opts_chunk$set(
comment = "#>",
collapse = TRUE
)
## -----------------------------------------------------------------------------
str_length("abc")
## -----------------------------------------------------------------------------
x <- c("abcdef", "ghifjk")
# The 3rd letter
str_sub(x, 3, 3)
# The 2nd to 2nd-to-last character
str_sub(x, 2, -2)
## -----------------------------------------------------------------------------
str_sub(x, 3, 3) <- "X"
x
## -----------------------------------------------------------------------------
str_dup(x, c(2, 3))
## -----------------------------------------------------------------------------
x <- c("abc", "defghi")
str_pad(x, 10) # default pads on left
str_pad(x, 10, "both")
## -----------------------------------------------------------------------------
str_pad(x, 4)
## -----------------------------------------------------------------------------
x <- c("Short", "This is a long string")
x %>%
str_trunc(10) %>%
str_pad(10, "right")
## -----------------------------------------------------------------------------
x <- c(" a ", "b ", " c")
str_trim(x)
str_trim(x, "left")
## -----------------------------------------------------------------------------
jabberwocky <- str_c(
"`Twas brillig, and the slithy toves ",
"did gyre and gimble in the wabe: ",
"All mimsy were the borogoves, ",
"and the mome raths outgrabe. "
)
cat(str_wrap(jabberwocky, width = 40))
## -----------------------------------------------------------------------------
x <- "I like horses."
str_to_upper(x)
str_to_title(x)
str_to_lower(x)
# Turkish has two sorts of i: with and without the dot
str_to_lower(x, "tr")
## -----------------------------------------------------------------------------
x <- c("y", "i", "k")
str_order(x)
str_sort(x)
# In Lithuanian, y comes between i and k
str_sort(x, locale = "lt")
## -----------------------------------------------------------------------------
strings <- c(
"apple",
"219 733 8965",
"329-293-8753",
"Work: 579-499-7527; Home: 543.355.3679"
)
phone <- "([2-9][0-9]{2})[- .]([0-9]{3})[- .]([0-9]{4})"
## -----------------------------------------------------------------------------
# Which strings contain phone numbers?
str_detect(strings, phone)
str_subset(strings, phone)
## -----------------------------------------------------------------------------
# How many phone numbers in each string?
str_count(strings, phone)
## -----------------------------------------------------------------------------
# Where in the string is the phone number located?
(loc <- str_locate(strings, phone))
str_locate_all(strings, phone)
## -----------------------------------------------------------------------------
# What are the phone numbers?
str_extract(strings, phone)
str_extract_all(strings, phone)
str_extract_all(strings, phone, simplify = TRUE)
## -----------------------------------------------------------------------------
# Pull out the three components of the match
str_match(strings, phone)
str_match_all(strings, phone)
## -----------------------------------------------------------------------------
str_replace(strings, phone, "XXX-XXX-XXXX")
str_replace_all(strings, phone, "XXX-XXX-XXXX")
## -----------------------------------------------------------------------------
str_split("a-b-c", "-")
str_split_fixed("a-b-c", "-", n = 2)
## -----------------------------------------------------------------------------
a1 <- "\u00e1"
a2 <- "a\u0301"
c(a1, a2)
a1 == a2
## -----------------------------------------------------------------------------
str_detect(a1, fixed(a2))
str_detect(a1, coll(a2))
## -----------------------------------------------------------------------------
i <- c("I", "İ", "i", "ı")
i
str_subset(i, coll("i", ignore_case = TRUE))
str_subset(i, coll("i", ignore_case = TRUE, locale = "tr"))
## -----------------------------------------------------------------------------
x <- "This is a sentence."
str_split(x, boundary("word"))
str_count(x, boundary("word"))
str_extract_all(x, boundary("word"))
## -----------------------------------------------------------------------------
str_split(x, "")
str_count(x, "")
stringr/inst/doc/regular-expressions.R 0000644 0001762 0000144 00000012202 14524706130 017627 0 ustar ligges users ## ----setup, include = FALSE---------------------------------------------------
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
library(stringr)
## ----eval = FALSE-------------------------------------------------------------
# # The regular call:
# str_extract(fruit, "nana")
# # Is shorthand for
# str_extract(fruit, regex("nana"))
## -----------------------------------------------------------------------------
x <- c("apple", "banana", "pear")
str_extract(x, "an")
## -----------------------------------------------------------------------------
bananas <- c("banana", "Banana", "BANANA")
str_detect(bananas, "banana")
str_detect(bananas, regex("banana", ignore_case = TRUE))
## -----------------------------------------------------------------------------
str_extract(x, ".a.")
## -----------------------------------------------------------------------------
str_detect("\nX\n", ".X.")
str_detect("\nX\n", regex(".X.", dotall = TRUE))
## -----------------------------------------------------------------------------
# To create the regular expression, we need \\
dot <- "\\."
# But the expression itself only contains one:
writeLines(dot)
# And this tells R to look for an explicit .
str_extract(c("abc", "a.c", "bef"), "a\\.c")
## -----------------------------------------------------------------------------
x <- "a\\b"
writeLines(x)
str_extract(x, "\\\\")
## -----------------------------------------------------------------------------
x <- c("a.b.c.d", "aeb")
starts_with <- "a.b"
str_detect(x, paste0("^", starts_with))
str_detect(x, paste0("^\\Q", starts_with, "\\E"))
## -----------------------------------------------------------------------------
x <- "a\u0301"
str_extract(x, ".")
str_extract(x, "\\X")
## -----------------------------------------------------------------------------
str_extract_all("1 + 2 = 3", "\\d+")[[1]]
## -----------------------------------------------------------------------------
# Some Laotian numbers
str_detect("១២៣", "\\d")
## -----------------------------------------------------------------------------
(text <- "Some \t badly\n\t\tspaced \f text")
str_replace_all(text, "\\s+", " ")
## -----------------------------------------------------------------------------
(text <- c('"Double quotes"', "«Guillemet»", "“Fancy quotes”"))
str_replace_all(text, "\\p{quotation mark}", "'")
## -----------------------------------------------------------------------------
str_extract_all("Don't eat that!", "\\w+")[[1]]
str_split("Don't eat that!", "\\W")[[1]]
## -----------------------------------------------------------------------------
str_replace_all("The quick brown fox", "\\b", "_")
str_replace_all("The quick brown fox", "\\B", "_")
## -----------------------------------------------------------------------------
str_detect(c("abc", "def", "ghi"), "abc|def")
## -----------------------------------------------------------------------------
str_extract(c("grey", "gray"), "gre|ay")
str_extract(c("grey", "gray"), "gr(e|a)y")
## -----------------------------------------------------------------------------
pattern <- "(..)\\1"
fruit %>%
str_subset(pattern)
fruit %>%
str_subset(pattern) %>%
str_match(pattern)
## -----------------------------------------------------------------------------
str_match(c("grey", "gray"), "gr(e|a)y")
str_match(c("grey", "gray"), "gr(?:e|a)y")
## -----------------------------------------------------------------------------
x <- c("apple", "banana", "pear")
str_extract(x, "^a")
str_extract(x, "a$")
## -----------------------------------------------------------------------------
x <- "Line 1\nLine 2\nLine 3\n"
str_extract_all(x, "^Line..")[[1]]
str_extract_all(x, regex("^Line..", multiline = TRUE))[[1]]
str_extract_all(x, regex("\\ALine..", multiline = TRUE))[[1]]
## -----------------------------------------------------------------------------
x <- "1888 is the longest year in Roman numerals: MDCCCLXXXVIII"
str_extract(x, "CC?")
str_extract(x, "CC+")
str_extract(x, 'C[LX]+')
## -----------------------------------------------------------------------------
str_extract(x, "C{2}")
str_extract(x, "C{2,}")
str_extract(x, "C{2,3}")
## -----------------------------------------------------------------------------
str_extract(x, c("C{2,3}", "C{2,3}?"))
str_extract(x, c("C[LX]+", "C[LX]+?"))
## -----------------------------------------------------------------------------
str_detect("ABC", "(?>A|.B)C")
str_detect("ABC", "(?:A|.B)C")
## -----------------------------------------------------------------------------
x <- c("1 piece", "2 pieces", "3")
str_extract(x, "\\d+(?= pieces?)")
y <- c("100", "$400")
str_extract(y, "(?<=\\$)\\d+")
## -----------------------------------------------------------------------------
str_detect("xyz", "x(?#this is a comment)")
## -----------------------------------------------------------------------------
phone <- regex("
\\(? # optional opening parens
(\\d{3}) # area code
\\)? # optional closing parens
(?:-|\\ )? # optional dash or space
(\\d{3}) # another three numbers
(?:-|\\ )? # optional dash or space
(\\d{3}) # three more numbers
", comments = TRUE)
str_match(c("514-791-8141", "(514) 791 8141"), phone)
stringr/inst/doc/stringr.Rmd 0000644 0001762 0000144 00000022475 14037267204 015637 0 ustar ligges users ---
title: "Introduction to stringr"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Introduction to stringr}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
library(stringr)
knitr::opts_chunk$set(
comment = "#>",
collapse = TRUE
)
```
There are four main families of functions in stringr:
1. Character manipulation: these functions allow you to manipulate
individual characters within the strings in character vectors.
1. Whitespace tools to add, remove, and manipulate whitespace.
1. Locale sensitive operations whose operations will vary from locale
to locale.
1. Pattern matching functions. These recognise four engines of
pattern description. The most common is regular expressions, but there
are three other tools.
## Getting and setting individual characters
You can get the length of the string with `str_length()`:
```{r}
str_length("abc")
```
This is now equivalent to the base R function `nchar()`. Previously it was needed to work around issues with `nchar()` such as the fact that it returned 2 for `nchar(NA)`. This has been fixed as of R 3.3.0, so it is no longer so important.
You can access individual character using `str_sub()`. It takes three arguments: a character vector, a `start` position and an `end` position. Either position can either be a positive integer, which counts from the left, or a negative integer which counts from the right. The positions are inclusive, and if longer than the string, will be silently truncated.
```{r}
x <- c("abcdef", "ghifjk")
# The 3rd letter
str_sub(x, 3, 3)
# The 2nd to 2nd-to-last character
str_sub(x, 2, -2)
```
You can also use `str_sub()` to modify strings:
```{r}
str_sub(x, 3, 3) <- "X"
x
```
To duplicate individual strings, you can use `str_dup()`:
```{r}
str_dup(x, c(2, 3))
```
## Whitespace
Three functions add, remove, or modify whitespace:
1. `str_pad()` pads a string to a fixed length by adding extra whitespace on
the left, right, or both sides.
```{r}
x <- c("abc", "defghi")
str_pad(x, 10) # default pads on left
str_pad(x, 10, "both")
```
(You can pad with other characters by using the `pad` argument.)
`str_pad()` will never make a string shorter:
```{r}
str_pad(x, 4)
```
So if you want to ensure that all strings are the same length (often useful
for print methods), combine `str_pad()` and `str_trunc()`:
```{r}
x <- c("Short", "This is a long string")
x %>%
str_trunc(10) %>%
str_pad(10, "right")
```
1. The opposite of `str_pad()` is `str_trim()`, which removes leading and
trailing whitespace:
```{r}
x <- c(" a ", "b ", " c")
str_trim(x)
str_trim(x, "left")
```
1. You can use `str_wrap()` to modify existing whitespace in order to wrap
a paragraph of text, such that the length of each line is as similar as
possible.
```{r}
jabberwocky <- str_c(
"`Twas brillig, and the slithy toves ",
"did gyre and gimble in the wabe: ",
"All mimsy were the borogoves, ",
"and the mome raths outgrabe. "
)
cat(str_wrap(jabberwocky, width = 40))
```
## Locale sensitive
A handful of stringr functions are locale-sensitive: they will perform differently in different regions of the world. These functions are case transformation functions:
```{r}
x <- "I like horses."
str_to_upper(x)
str_to_title(x)
str_to_lower(x)
# Turkish has two sorts of i: with and without the dot
str_to_lower(x, "tr")
```
String ordering and sorting:
```{r}
x <- c("y", "i", "k")
str_order(x)
str_sort(x)
# In Lithuanian, y comes between i and k
str_sort(x, locale = "lt")
```
The locale always defaults to English to ensure that the default behaviour is identical across systems. Locales always include a two letter ISO-639-1 language code (like "en" for English or "zh" for Chinese), and optionally a ISO-3166 country code (like "en_UK" vs "en_US"). You can see a complete list of available locales by running `stringi::stri_locale_list()`.
## Pattern matching
The vast majority of stringr functions work with patterns. These are parameterised by the task they perform and the types of patterns they match.
### Tasks
Each pattern matching function has the same first two arguments, a character vector of `string`s to process and a single `pattern` to match. stringr provides pattern matching functions to **detect**, **locate**, **extract**, **match**, **replace**, and **split** strings. I'll illustrate how they work with some strings and a regular expression designed to match (US) phone numbers:
```{r}
strings <- c(
"apple",
"219 733 8965",
"329-293-8753",
"Work: 579-499-7527; Home: 543.355.3679"
)
phone <- "([2-9][0-9]{2})[- .]([0-9]{3})[- .]([0-9]{4})"
```
- `str_detect()` detects the presence or absence of a pattern and returns a
logical vector (similar to `grepl()`). `str_subset()` returns the elements
of a character vector that match a regular expression (similar to `grep()`
with `value = TRUE`)`.
```{r}
# Which strings contain phone numbers?
str_detect(strings, phone)
str_subset(strings, phone)
```
- `str_count()` counts the number of matches:
```{r}
# How many phone numbers in each string?
str_count(strings, phone)
```
- `str_locate()` locates the **first** position of a pattern and returns a numeric
matrix with columns start and end. `str_locate_all()` locates all matches,
returning a list of numeric matrices. Similar to `regexpr()` and `gregexpr()`.
```{r}
# Where in the string is the phone number located?
(loc <- str_locate(strings, phone))
str_locate_all(strings, phone)
```
- `str_extract()` extracts text corresponding to the **first** match, returning a
character vector. `str_extract_all()` extracts all matches and returns a
list of character vectors.
```{r}
# What are the phone numbers?
str_extract(strings, phone)
str_extract_all(strings, phone)
str_extract_all(strings, phone, simplify = TRUE)
```
- `str_match()` extracts capture groups formed by `()` from the **first** match.
It returns a character matrix with one column for the complete match and
one column for each group. `str_match_all()` extracts capture groups from
all matches and returns a list of character matrices. Similar to
`regmatches()`.
```{r}
# Pull out the three components of the match
str_match(strings, phone)
str_match_all(strings, phone)
```
- `str_replace()` replaces the **first** matched pattern and returns a character
vector. `str_replace_all()` replaces all matches. Similar to `sub()` and
`gsub()`.
```{r}
str_replace(strings, phone, "XXX-XXX-XXXX")
str_replace_all(strings, phone, "XXX-XXX-XXXX")
```
- `str_split_fixed()` splits a string into a **fixed** number of pieces based
on a pattern and returns a character matrix. `str_split()` splits a string
into a **variable** number of pieces and returns a list of character vectors.
```{r}
str_split("a-b-c", "-")
str_split_fixed("a-b-c", "-", n = 2)
```
### Engines
There are four main engines that stringr can use to describe patterns:
* Regular expressions, the default, as shown above, and described in
`vignette("regular-expressions")`.
* Fixed bytewise matching, with `fixed()`.
* Locale-sensitive character matching, with `coll()`
* Text boundary analysis with `boundary()`.
#### Fixed matches
`fixed(x)` only matches the exact sequence of bytes specified by `x`. This is a very limited "pattern", but the restriction can make matching much faster. Beware using `fixed()` with non-English data. It is problematic because there are often multiple ways of representing the same character. For example, there are two ways to define "á": either as a single character or as an "a" plus an accent:
```{r}
a1 <- "\u00e1"
a2 <- "a\u0301"
c(a1, a2)
a1 == a2
```
They render identically, but because they're defined differently,
`fixed()` doesn't find a match. Instead, you can use `coll()`, explained
below, to respect human character comparison rules:
```{r}
str_detect(a1, fixed(a2))
str_detect(a1, coll(a2))
```
#### Collation search
`coll(x)` looks for a match to `x` using human-language **coll**ation rules, and is particularly important if you want to do case insensitive matching. Collation rules differ around the world, so you'll also need to supply a `locale` parameter.
```{r}
i <- c("I", "İ", "i", "ı")
i
str_subset(i, coll("i", ignore_case = TRUE))
str_subset(i, coll("i", ignore_case = TRUE, locale = "tr"))
```
The downside of `coll()` is speed. Because the rules for recognising which characters are the same are complicated, `coll()` is relatively slow compared to `regex()` and `fixed()`. Note that when both `fixed()` and `regex()` have `ignore_case` arguments, they perform a much simpler comparison than `coll()`.
#### Boundary
`boundary()` matches boundaries between characters, lines, sentences or words. It's most useful with `str_split()`, but can be used with all pattern matching functions:
```{r}
x <- "This is a sentence."
str_split(x, boundary("word"))
str_count(x, boundary("word"))
str_extract_all(x, boundary("word"))
```
By convention, `""` is treated as `boundary("character")`:
```{r}
str_split(x, "")
str_count(x, "")
```
stringr/inst/doc/from-base.R 0000644 0001762 0000144 00000022771 14524706127 015503 0 ustar ligges users ## -----------------------------------------------------------------------------
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
library(stringr)
library(magrittr)
## -----------------------------------------------------------------------------
data_stringr_base_diff <- tibble::tribble(
~stringr, ~base_r,
"str_detect(string, pattern)", "grepl(pattern, x)",
"str_dup(string, times)", "strrep(x, times)",
"str_extract(string, pattern)", "regmatches(x, m = regexpr(pattern, text))",
"str_extract_all(string, pattern)", "regmatches(x, m = gregexpr(pattern, text))",
"str_length(string)", "nchar(x)",
"str_locate(string, pattern)", "regexpr(pattern, text)",
"str_locate_all(string, pattern)", "gregexpr(pattern, text)",
"str_match(string, pattern)", "regmatches(x, m = regexec(pattern, text))",
"str_order(string)", "order(...)",
"str_replace(string, pattern, replacement)", "sub(pattern, replacement, x)",
"str_replace_all(string, pattern, replacement)", "gsub(pattern, replacement, x)",
"str_sort(string)", "sort(x)",
"str_split(string, pattern)", "strsplit(x, split)",
"str_sub(string, start, end)", "substr(x, start, stop)",
"str_subset(string, pattern)", "grep(pattern, x, value = TRUE)",
"str_to_lower(string)", "tolower(x)",
"str_to_title(string)", "tools::toTitleCase(text)",
"str_to_upper(string)", "toupper(x)",
"str_trim(string)", "trimws(x)",
"str_which(string, pattern)", "grep(pattern, x)",
"str_wrap(string)", "strwrap(x)"
)
# create MD table, arranged alphabetically by stringr fn name
data_stringr_base_diff %>%
dplyr::mutate(dplyr::across(.fns = ~ paste0("`", .x, "`"))) %>%
dplyr::arrange(stringr) %>%
dplyr::rename(`base R` = base_r) %>%
gt::gt() %>%
gt::fmt_markdown(columns = everything()) %>%
gt::tab_options(column_labels.font.weight = "bold")
## -----------------------------------------------------------------------------
fruit <- c("apple", "banana", "pear", "pineapple")
# base
grepl(pattern = "a", x = fruit)
# stringr
str_detect(fruit, pattern = "a")
## -----------------------------------------------------------------------------
# base
grep(pattern = "a", x = fruit)
# stringr
str_which(fruit, pattern = "a")
## -----------------------------------------------------------------------------
# base
loc <- gregexpr(pattern = "a", text = fruit, fixed = TRUE)
sapply(loc, function(x) length(attr(x, "match.length")))
# stringr
str_count(fruit, pattern = "a")
## -----------------------------------------------------------------------------
fruit3 <- c("papaya", "lime", "apple")
# base
str(gregexpr(pattern = "p", text = fruit3))
# stringr
str_locate(fruit3, pattern = "p")
str_locate_all(fruit3, pattern = "p")
## -----------------------------------------------------------------------------
hw <- "Hadley Wickham"
# base
substr(hw, start = 1, stop = 6)
substring(hw, first = 1)
# stringr
str_sub(hw, start = 1, end = 6)
str_sub(hw, start = 1)
str_sub(hw, end = 6)
## -----------------------------------------------------------------------------
str_sub(hw, start = 1, end = -1)
str_sub(hw, start = -5, end = -2)
## -----------------------------------------------------------------------------
al <- "Ada Lovelace"
# base
substr(c(hw,al), start = 1, stop = 6)
substr(c(hw,al), start = c(1,1), stop = c(6,7))
# stringr
str_sub(c(hw,al), start = 1, end = -1)
str_sub(c(hw,al), start = c(1,1), end = c(-1,-2))
## -----------------------------------------------------------------------------
str_sub(hw, start = 1:5)
## -----------------------------------------------------------------------------
substr(hw, start = 1:5, stop = 15)
## -----------------------------------------------------------------------------
# base
x <- "ABCDEF"
substr(x, 1, 3) <- "x"
x
## -----------------------------------------------------------------------------
# stringr
x <- "ABCDEF"
str_sub(x, 1, 3) <- "x"
x
## -----------------------------------------------------------------------------
# base
grep(pattern = "g", x = fruit, value = TRUE)
# stringr
str_subset(fruit, pattern = "g")
## -----------------------------------------------------------------------------
shopping_list <- c("apples x4", "bag of flour", "10", "milk x2")
# base
matches <- regexpr(pattern = "\\d+", text = shopping_list) # digits
regmatches(shopping_list, m = matches)
matches <- gregexpr(pattern = "[a-z]+", text = shopping_list) # words
regmatches(shopping_list, m = matches)
# stringr
str_extract(shopping_list, pattern = "\\d+")
str_extract_all(shopping_list, "[a-z]+")
## -----------------------------------------------------------------------------
head(sentences)
noun <- "([A]a|[Tt]he) ([^ ]+)"
# base
matches <- regexec(pattern = noun, text = head(sentences))
do.call("rbind", regmatches(x = head(sentences), m = matches))
# stringr
str_match(head(sentences), pattern = noun)
## -----------------------------------------------------------------------------
# base
nchar(letters)
# stringr
str_length(letters)
## -----------------------------------------------------------------------------
# base
nchar(factor("abc"))
## -----------------------------------------------------------------------------
# stringr
str_length(factor("abc"))
## -----------------------------------------------------------------------------
x <- c("\u00fc", "u\u0308")
x
nchar(x)
str_length(x)
## -----------------------------------------------------------------------------
# base
sprintf("%30s", "hadley")
sprintf("%-30s", "hadley")
# "both" is not as straightforward
# stringr
rbind(
str_pad("hadley", 30, "left"),
str_pad("hadley", 30, "right"),
str_pad("hadley", 30, "both")
)
## -----------------------------------------------------------------------------
x <- "This string is moderately long"
# stringr
rbind(
str_trunc(x, 20, "right"),
str_trunc(x, 20, "left"),
str_trunc(x, 20, "center")
)
## -----------------------------------------------------------------------------
# base
trimws(" String with trailing and leading white space\t")
trimws("\n\nString with trailing and leading white space\n\n")
# stringr
str_trim(" String with trailing and leading white space\t")
str_trim("\n\nString with trailing and leading white space\n\n")
## -----------------------------------------------------------------------------
# stringr
str_squish(" String with trailing, middle, and leading white space\t")
str_squish("\n\nString with excess, trailing and leading white space\n\n")
## -----------------------------------------------------------------------------
gettysburg <- "Four score and seven years ago our fathers brought forth on this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal."
# base
cat(strwrap(gettysburg, width = 60), sep = "\n")
# stringr
cat(str_wrap(gettysburg, width = 60), "\n")
## -----------------------------------------------------------------------------
fruits <- c("apple", "banana", "pear", "pineapple")
# base
sub("[aeiou]", "-", fruits)
gsub("[aeiou]", "-", fruits)
# stringr
str_replace(fruits, "[aeiou]", "-")
str_replace_all(fruits, "[aeiou]", "-")
## -----------------------------------------------------------------------------
dog <- "The quick brown dog"
# base
toupper(dog)
tolower(dog)
tools::toTitleCase(dog)
# stringr
str_to_upper(dog)
str_to_lower(dog)
str_to_title(dog)
## -----------------------------------------------------------------------------
# stringr
str_to_upper("i") # English
str_to_upper("i", locale = "tr") # Turkish
## -----------------------------------------------------------------------------
# base
paste0(letters, collapse = "-")
# stringr
str_flatten(letters, collapse = "-")
## -----------------------------------------------------------------------------
fruit <- c("apple", "pear", "banana")
# base
strrep(fruit, 2)
strrep(fruit, 1:3)
# stringr
str_dup(fruit, 2)
str_dup(fruit, 1:3)
## -----------------------------------------------------------------------------
fruits <- c(
"apples and oranges and pears and bananas",
"pineapples and mangos and guavas"
)
# base
strsplit(fruits, " and ")
# stringr
str_split(fruits, " and ")
## -----------------------------------------------------------------------------
# stringr
str_split(fruits, " and ", n = 3)
str_split(fruits, " and ", n = 2)
## -----------------------------------------------------------------------------
name <- "Fred"
age <- 50
anniversary <- as.Date("1991-10-12")
# base
sprintf(
"My name is %s my age next year is %s and my anniversary is %s.",
name,
age + 1,
format(anniversary, "%A, %B %d, %Y")
)
# stringr
str_glue(
"My name is {name}, ",
"my age next year is {age + 1}, ",
"and my anniversary is {format(anniversary, '%A, %B %d, %Y')}."
)
## -----------------------------------------------------------------------------
# base
order(letters)
sort(letters)
# stringr
str_order(letters)
str_sort(letters)
## -----------------------------------------------------------------------------
x <- c("å", "a", "z")
str_sort(x)
str_sort(x, locale = "no")
## -----------------------------------------------------------------------------
# stringr
x <- c("100a10", "100a5", "2b", "2a")
str_sort(x)
str_sort(x, numeric = TRUE)
stringr/inst/htmlwidgets/ 0000755 0001762 0000144 00000000000 14524706124 015257 5 ustar ligges users stringr/inst/htmlwidgets/str_view.yaml 0000644 0001762 0000144 00000000147 12613714471 020010 0 ustar ligges users dependencies:
- name: str_view
version: 0.1.0
src: htmlwidgets/lib/
stylesheet: str_view.css
stringr/inst/htmlwidgets/str_view.js 0000644 0001762 0000144 00000000367 12613714660 017466 0 ustar ligges users HTMLWidgets.widget({
name: 'str_view',
type: 'output',
initialize: function(el, width, height) {
},
renderValue: function(el, x, instance) {
el.innerHTML = x.html;
},
resize: function(el, width, height, instance) {
}
});
stringr/inst/htmlwidgets/lib/ 0000755 0001762 0000144 00000000000 14316043620 016017 5 ustar ligges users stringr/inst/htmlwidgets/lib/str_view.css 0000644 0001762 0000144 00000000440 14316043620 020371 0 ustar ligges users .str_view ul {
font-size: 16px;
}
.str_view ul, .str_view li {
list-style: none;
padding: 0;
margin: 0.5em 0;
}
.str_view .match {
border: 1px solid #ccc;
background-color: #eee;
border-color: #ccc;
border-radius: 3px;
}
.str_view .special {
background-color: red;
}
## Usage
All functions in stringr start with `str_` and take a vector of strings
as the first argument:
``` r
x <- c("why", "video", "cross", "extra", "deal", "authority")
str_length(x)
#> [1] 3 5 5 5 4 9
str_c(x, collapse = ", ")
#> [1] "why, video, cross, extra, deal, authority"
str_sub(x, 1, 2)
#> [1] "wh" "vi" "cr" "ex" "de" "au"
```
Most string functions work with regular expressions, a concise language
for describing patterns of text. For example, the regular expression
`"[aeiou]"` matches any single character that is a vowel:
``` r
str_subset(x, "[aeiou]")
#> [1] "video" "cross" "extra" "deal" "authority"
str_count(x, "[aeiou]")
#> [1] 0 3 1 2 2 4
```
There are seven main verbs that work with patterns:
- `str_detect(x, pattern)` tells you if there’s any match to the
pattern:
``` r
str_detect(x, "[aeiou]")
#> [1] FALSE TRUE TRUE TRUE TRUE TRUE
```
- `str_count(x, pattern)` counts the number of patterns:
``` r
str_count(x, "[aeiou]")
#> [1] 0 3 1 2 2 4
```
- `str_subset(x, pattern)` extracts the matching components:
``` r
str_subset(x, "[aeiou]")
#> [1] "video" "cross" "extra" "deal" "authority"
```
- `str_locate(x, pattern)` gives the position of the match:
``` r
str_locate(x, "[aeiou]")
#> start end
#> [1,] NA NA
#> [2,] 2 2
#> [3,] 3 3
#> [4,] 1 1
#> [5,] 2 2
#> [6,] 1 1
```
- `str_extract(x, pattern)` extracts the text of the match:
``` r
str_extract(x, "[aeiou]")
#> [1] NA "i" "o" "e" "e" "a"
```
- `str_match(x, pattern)` extracts parts of the match defined by
parentheses:
``` r
# extract the characters on either side of the vowel
str_match(x, "(.)[aeiou](.)")
#> [,1] [,2] [,3]
#> [1,] NA NA NA
#> [2,] "vid" "v" "d"
#> [3,] "ros" "r" "s"
#> [4,] NA NA NA
#> [5,] "dea" "d" "a"
#> [6,] "aut" "a" "t"
```
- `str_replace(x, pattern, replacement)` replaces the matches with new
text:
``` r
str_replace(x, "[aeiou]", "?")
#> [1] "why" "v?deo" "cr?ss" "?xtra" "d?al" "?uthority"
```
- `str_split(x, pattern)` splits up a string into multiple pieces:
``` r
str_split(c("a,b", "c,d,e"), ",")
#> [[1]]
#> [1] "a" "b"
#>
#> [[2]]
#> [1] "c" "d" "e"
```
As well as regular expressions (the default), there are three other
pattern matching engines:
- `fixed()`: match exact bytes
- `coll()`: match human letters
- `boundary()`: match boundaries
## RStudio Addin
The [RegExplain RStudio
addin](https://www.garrickadenbuie.com/project/regexplain/) provides a
friendly interface for working with regular expressions and functions
from stringr. This addin allows you to interactively build your regexp,
check the output of common string matching functions, consult the
interactive help pages, or use the included resources to learn regular
expressions.
This addin can easily be installed with devtools:
``` r
# install.packages("devtools")
devtools::install_github("gadenbuie/regexplain")
```
## Compared to base R
R provides a solid set of string operations, but because they have grown
organically over time, they can be inconsistent and a little hard to
learn. Additionally, they lag behind the string operations in other
programming languages, so that some things that are easy to do in
languages like Ruby or Python are rather hard to do in R.
- Uses consistent function and argument names. The first argument is
always the vector of strings to modify, which makes stringr work
particularly well in conjunction with the pipe:
``` r
letters %>%
.[1:10] %>%
str_pad(3, "right") %>%
str_c(letters[2:11])
#> [1] "a b" "b c" "c d" "d e" "e f" "f g" "g h" "h i" "i j" "j k"
```
- Simplifies string operations by eliminating options that you don’t
need 95% of the time.
- Produces outputs than can easily be used as inputs. This includes
ensuring that missing inputs result in missing outputs, and zero
length inputs result in zero length outputs.
Learn more in `vignette("from-base")`
stringr/data/ 0000755 0001762 0000144 00000000000 14520174727 012664 5 ustar ligges users stringr/data/words.rda 0000644 0001762 0000144 00000006512 12743441637 014520 0 ustar ligges users BZh91AY&SY#qa fo@ @? ` w
O| u]
3=L5%:vaxM CM Si 4OA *=I A
?Jl$M $SB24 iOS L#B4 J!F
vI!}ÖO]$ R9 i%=3S>J YQ$$O4GS˝{ˉ6n$I߮ݲV J1Klw"
[YQ; `=C, DfUedW!`OX}FQaM,2& 4 Ŏpy;: ]=y?n 2(MvB;zմ\X'à&jBSBAMOfckFPpO7iJ!J 3p&^4,n}1RLO:V/u]hWsQFip*{E% @!yR ]AnW-/EF(I*9pYI |<7#,--,qbPTDh>fa)q71!ΡS #LZ
a("x).jf䴼 (A|!zQVg5.yUVZ !H8yZk/4Í ЫkjA0`řWcbOu]=;4pFmhZzB.,yNp ݸJwlx _'F3á;g9 CL":(+7:,tvɾ/ aĴ#$ 6T6S .ZE~{I+%㉳Qc\jqcGd$v
|&1gDfYrnUDe4U(8,MXF/i fc|Uŋ6IޜUIy^Os>˝?R>0nn\n.T.;
"ŷ5IFռ1J p_ {͢10y֊5/7
{0^nACqs4J @ >Ϥv,%uX@I Y!S$Gy|x$>vHc.PQDC%S(9BC2ȥʑqeC3t
!D". \nsxl o=4]8G}ܹfr SVM!< FRd&dM!;Xr ݗW>1svJ6]ޢ NwPd%@fI n\1e }ge|UX*CLpAȃgFnD
\`] W0'9 }nb>tq$
8K O31p|,;=7Ú=R&[":iMÑ%y M|.-|V \5Gչ(/ q#' cǜ|8s<ԡЈͬL P2GOZ'0vA}_~gCKndWS{G6]JCC ; nr|"dnzW*P*>jR
Rq4
e(= C"uV9 '=1܁oN"tabmlߦ`2`Hl~+ 9Pk;k7z/C܃
w* &'D0(bxT0f]}:ay<"_/7T^p#aQVH&Ѐhz;ب?)lgl&
#
T#ՒA "-. )QpC+&!mh)pX֍,ЎcÒnpڣs`k >y_!rDv3O I73ѹz4zv^fu ɠ_,;E/CMQ2Hɤ y 7eA3\6"HQ3c ;}lW$<9,4S)!:덯5ϜWx}vL
'
Comments
There are two ways to include comments in a regular expression. The first is with
(?#...):The second is to use
regex(comments = TRUE). This form ignores spaces and newlines, and anything everything after#. To match a literal space, you’ll need to escape it:"\\ ". This is a useful way of describing complex regular expressions: