Extract and replace substrings from a character vector.

str_sub will recycle all arguments to be the same length as the longest argument. If any arguments are of length 0, the output will be a zero length character vector.

str_sub(string, start = 1L, end = -1L)

str_sub(string, start = 1L, end = -1L, omit_na = FALSE) <- value

Arguments

string	input character vector.
start, end	Two integer vectors. start gives the position of the first character (defaults to first), end gives the position of the last (defaults to last character). Alternatively, pass a two-column matrix to start. Negative values count backwards from the last character.
omit_na	Single logical value. If TRUE, missing values in any of the arguments provided will result in an unchanged input.
value	replacement string

Value

A character vector of substring from start to end (inclusive). Will be length of longest input argument.

Details

Substrings are inclusive - they include the characters at both start and end positions. str_sub(string, 1, -1) will return the complete substring, from the first character to the last.

See also

The underlying implementation in stringi::stri_sub()

Examples

hw <- "Hadley Wickham"

str_sub(hw, 1, 6)
#> [1] "Hadley"
str_sub(hw, end = 6)
#> [1] "Hadley"
str_sub(hw, 8, 14)
#> [1] "Wickham"
str_sub(hw, 8)
#> [1] "Wickham"
str_sub(hw, c(1, 8), c(6, 14))
#> [1] "Hadley"  "Wickham"

# Negative indices
str_sub(hw, -1)
#> [1] "m"
str_sub(hw, -7)
#> [1] "Wickham"
str_sub(hw, end = -7)
#> [1] "Hadley W"

# Alternatively, you can pass in a two colum matrix, as in the
# output from str_locate_all
pos <- str_locate_all(hw, "[aeio]")[[1]]
str_sub(hw, pos)
#> [1] "a" "e" "i" "a"
str_sub(hw, pos[, 1], pos[, 2])
#> [1] "a" "e" "i" "a"

# Vectorisation
str_sub(hw, seq_len(str_length(hw)))
#>  [1] "Hadley Wickham" "adley Wickham"  "dley Wickham"   "ley Wickham"   
#>  [5] "ey Wickham"     "y Wickham"      " Wickham"       "Wickham"       
#>  [9] "ickham"         "ckham"          "kham"           "ham"           
#> [13] "am"             "m"             
str_sub(hw, end = seq_len(str_length(hw)))
#>  [1] "H"              "Ha"             "Had"            "Hadl"          
#>  [5] "Hadle"          "Hadley"         "Hadley "        "Hadley W"      
#>  [9] "Hadley Wi"      "Hadley Wic"     "Hadley Wick"    "Hadley Wickh"  
#> [13] "Hadley Wickha"  "Hadley Wickham"

# Replacement form
x <- "BBCDEF"
str_sub(x, 1, 1) <- "A"; x
#> [1] "ABCDEF"
str_sub(x, -1, -1) <- "K"; x
#> [1] "ABCDEK"
str_sub(x, -2, -2) <- "GHIJ"; x
#> [1] "ABCDGHIJK"
str_sub(x, 2, -2) <- ""; x
#> [1] "AK"

# If you want to keep the original if some argument is NA,
# use omit_na = TRUE
x1 <- x2 <- x3 <- x4 <- "AAA"
str_sub(x1, 1, NA) <- "B"
str_sub(x2, 1, 2) <- NA
str_sub(x3, 1, NA, omit_na = TRUE) <- "B"
str_sub(x4, 1, 2, omit_na = TRUE) <- NA
x1; x2; x3; x4
#> [1] NA
#> [1] NA
#> [1] "AAA"
#> [1] "AAA"