# 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 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(pattern, 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, n)`
`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 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 `ignore.case`) 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 are adapted from the stringr documentation and here they are contrasted with the analogous base R operations.

    library(stringr)

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

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

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

    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.

# 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] "ü" "ü"

    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"

## `str_wrap()`: Wrap strings into nicely formatted paragraphs

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

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