This vignette compares stringr functions to their base R equivalents to help users transitioning from using base R to stringr.
We’ll begin with a lookup table between the most important stringr functions and their base R equivalents.
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) |
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.
str_detect()
: Detect the presence or absence of a
pattern in a stringSuppose 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 patternNow 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
stringHow 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
stringWithin 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
str_sub()
: Extract and replace substrings from a
character vectorWhat 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:
str_sub() <-
: Subset assignmentsubstr()
behaves in a surprising way when you replace a
substring with a different number of characters:
str_sub()
does what you would expect:
str_subset()
: Keep strings matching a pattern, or find
positionsWe may want to retrieve strings that contain a pattern of interest:
str_extract()
: Extract matching patterns from a
stringWe may want to pick out certain patterns from a string, for example, the digits in a shopping list:
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)
#> [1] "4" "10" "2"
matches <- gregexpr(pattern = "[a-z]+", text = shopping_list) # words
regmatches(shopping_list, m = matches)
#> [[1]]
#> [1] "apples" "x"
#>
#> [[2]]
#> [1] "bag" "of" "flour"
#>
#> [[3]]
#> character(0)
#>
#> [[4]]
#> [1] "milk" "x"
# stringr
str_extract(shopping_list, pattern = "\\d+")
#> [1] "4" NA "10" "2"
str_extract_all(shopping_list, "[a-z]+")
#> [[1]]
#> [1] "apples" "x"
#>
#> [[2]]
#> [1] "bag" "of" "flour"
#>
#> [[3]]
#> character(0)
#>
#> [[4]]
#> [1] "milk" "x"
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 stringWe 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.
head(sentences)
#> [1] "The birch canoe slid on the smooth planks."
#> [2] "Glue the sheet to the dark blue background."
#> [3] "It's easy to tell the depth of a well."
#> [4] "These days a chicken leg is a rare dish."
#> [5] "Rice is often served in round bowls."
#> [6] "The juice of lemons makes fine punch."
noun <- "([A]a|[Tt]he) ([^ ]+)"
# base
matches <- regexec(pattern = noun, text = head(sentences))
do.call("rbind", regmatches(x = head(sentences), m = matches))
#> [,1] [,2] [,3]
#> [1,] "The birch" "The" "birch"
#> [2,] "the sheet" "the" "sheet"
#> [3,] "the depth" "the" "depth"
#> [4,] "The juice" "The" "juice"
# stringr
str_match(head(sentences), pattern = noun)
#> [,1] [,2] [,3]
#> [1,] "The birch" "The" "birch"
#> [2,] "the sheet" "the" "sheet"
#> [3,] "the depth" "the" "depth"
#> [4,] NA NA NA
#> [5,] NA NA NA
#> [6,] "The juice" "The" "juice"
As for extracting the full match base R requires the combination of two functions, and inputs with no matches are dropped from the output.
str_length()
: The length of a stringTo 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.
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:
str_pad()
: Pad a stringTo 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 stringThe stringr package provides an easy way to truncate a character
string: str_trunc()
. Base R has no function to do this
directly.
str_trim()
: Trim whitespace from a stringSimilarly, 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.
str_wrap()
: Wrap strings into nicely formatted
paragraphsstrwrap()
and str_wrap()
use different
algorithms. str_wrap()
uses the famous Knuth-Plass
algorithm.
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")
#> 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.
# stringr
cat(str_wrap(gettysburg, width = 60), "\n")
#> 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.
Note that strwrap()
returns a character vector with one
element for each line; str_wrap()
returns a single string
containing line breaks.
str_replace()
: Replace matched patterns in a
stringTo 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-"
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.
str_flatten()
: Flatten a stringIf 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
vectorTo 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 piecesTo 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.
str_glue()
: Interpolate stringsIt’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.
str_order()
: Order or sort a character vectorBoth 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:
The stringr functions also have a numeric
argument to
sort digits numerically instead of treating them as strings.