Simple, Consistent Wrappers for Common String Operations

A consistent, simple and easy to use set of wrappers around the fantastic 'stringi' package. All function and argument names (and positions) are consistent, all functions deal with "NA"'s and zero length vectors in the same way, and the output from one function is easy to feed into the input of another.

Overview

Strings are not glamorous, high-profile components of R, but they do play a big role in many data cleaning and preparation tasks. The stringr package provide a cohesive set of functions designed to make working with strings as easy as posssible. If you're not familiar with strings, the best place to start is the chapter on strings in R for Data Science.

stringr is built on top of stringi, which uses the ICU C library to provide fast, correct implementations of common string manipulations. stringr focusses on the most important and commonly used string manipulation functions whereas stringi provides a comprehensive set covering almost anything you can imagine. If you find that stringr is missing a function that you need, try looking in stringi. Both packages share similar conventions, so once you've mastered stringr, you should find stringi similarly easy to use.

Installation

install.packages("stringr")
 
# Install the cutting edge development version from GitHub:
# install.packages("devtools")
devtools::install_github("tidyverse/stringr")

Usage

All functions in stringr start with str_ and take a vector of strings as the first argument.

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:

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.

str_detect(x, "[aeiou]")
#> [1] FALSE  TRUE  TRUE  TRUE  TRUE  TRUE

str_count(x, pattern) counts the number of patterns.
```
str_count(x, "[aeiou]")
#> [1] 0 3 1 2 2 4
```

str_subset(x, pattern) extracts the matching components.

str_subset(x, "[aeiou]")
#> [1] "video"     "cross"     "extra"     "deal"      "authority"

str_locate(x, pattern) gives the position of the match.

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.

str_extract(x, "[aeiou]")
#> [1] NA  "i" "o" "e" "e" "a"

str_match(x, pattern) extracts parts of the match defined by parentheses.

# 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, replacemnt) replaces the matches with new text.

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.

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

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:

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.

News

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 who's 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 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:
```
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