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 base string functions and their stringr equivalents.

base stringr
gregexpr(pattern, x) str_locate_all(x, pattern)
grep(pattern, x, value = TRUE) str_subset(x, pattern)
grep(pattern, x) str_which(x, pattern)
grepl(pattern, x) str_detect(x, pattern)
gsub(pattern, replacement, x) str_replace_all(x, pattern, replacement)
nchar(x) str_length(x)
order(x) str_order(x)
regexec(patter, x) + regmatches() str_match(x, pattern)
regexpr(pattern, x) + regmatches() str_extract(x, pattern)
regexpr(pattern, x) str_locate(x, pattern)
sort(x) str_sort(x)
strrep(x, n) str_dup(x, x)
strsplit(x, pattern) str_split(x, pattern)
strwrap(x) str_wrap(x)
sub(pattern, replacement, x) str_replace(x, pattern, replacement)
substr(x, start, end) str_sub(x, start, end)
tolower(x) str_to_lower(x)
tools::toTitleCase(x) str_to_title(x)
toupper(x) str_to_upper(x)
trimws(x) str_trim(x)

Overall the main differences between base R and stringr are:

  1. stringr functions start with str_ prefix; base R string functions have no no consistent naming scheme.

  2. 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().

  3. Functions in stringr tend to do less, where many of the string processing functions in base R have multiple purposes.

  4. 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().

  5. Base functions use arguments (like perl, fixed, and to control how the pattern is interpreted. To avoid dependence between arguments, stringr instead uses helper functions (like fixed(), regexp(), and coll()).

Next we’ll walk through each of the functions, noting the similarities and important differences. These examples come from the stringr documentation and here, they are contrasted with the analogous base R operation(s).


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", "pinapple")

# 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”.

# 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.

Subset strings

str_sub(): Extract and replace substrings from a character vector

What if we want to grab part of a string?

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:

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:

str_sub() does what you would expect:

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)

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:

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.

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().

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 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.

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.

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.

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.

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().

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():

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.

The stringr package’s str_split() allows for more control over the split, including restricting the number of possible matches.

Order strings

str_order(): Order or sort a character vector

Both base R and stringr have separate functions to order and sort strings.

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")
#> [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.