Added str_starts and str_ends wrapper functions. (#270)

Fixes #258

Author: jonthegeek

NAMESPACE

@@ -12,6 +12,7 @@ export(str_conv)
 export(str_count)
 export(str_detect)
 export(str_dup)
+export(str_ends)
 export(str_extract)
 export(str_extract_all)
 export(str_flatten)
@@ -34,6 +35,7 @@ export(str_sort)
 export(str_split)
 export(str_split_fixed)
 export(str_squish)
+export(str_starts)
 export(str_sub)
 export(str_subset)
 export(str_to_lower)

NEWS.md

@@ -10,6 +10,9 @@
 * New `str_to_sentence()` function to capitalize with sentence case 
   (@jonthegeek, #202)
 
+* New `str_starts()` and `str_ends()` functions to detect patterns at the 
+  beginning or end of strings (@jonthegeek, #258)
+
 # stringr 1.3.1
 
 * `str_replace_all()` with a named vector now respects modifier functions (#207)

R/detect.r

@@ -49,3 +49,58 @@ str_detect <- function(string, pattern, negate = FALSE) {
     regex = stri_detect_regex(string, pattern, negate = negate, opts_regex = opts(pattern))
   )
 }
+
+#' Detect the presence or absence of a pattern at the beginning or end of a
+#' string.
+#'
+#' Vectorised over `string` and `pattern`.
+#'
+#' @inheritParams str_detect
+#' @param pattern Pattern with which the string starts or ends.
+#'
+#'   The default interpretation is a regular expression, as described in
+#'   [stringi::stringi-search-regex]. Control options with [regex()].
+#'
+#'   Match a fixed string (i.e. by comparing only bytes), using [fixed()]. This
+#'   is fast, but approximate. Generally, for matching human text, you'll want
+#'   [coll()] which respects character matching rules for the specified locale.
+#'
+#' @return A logical vector.
+#' @seealso [str_detect()] which this function wraps when pattern is regex.
+#' @export
+#' @examples
+#' fruit <- c("apple", "banana", "pear", "pinapple")
+#' str_starts(fruit, "p")
+#' str_starts(fruit, "p", negate = TRUE)
+#' str_ends(fruit, "e")
+#' str_ends(fruit, "e", negate = TRUE)
+str_starts <- function(string, pattern, negate = FALSE) {
+  switch(
+    type(pattern),
+    empty = ,
+    bound = stop("boundary() patterns are not supported."),
+    fixed = stri_startswith_fixed(string, pattern, negate = negate, opts_fixed = opts(pattern)),
+    coll  = stri_startswith_coll(string,  pattern, negate = negate, opts_collator = opts(pattern)),
+    regex = {
+      pattern2 <- paste0("^", pattern)
+      attributes(pattern2) <- attributes(pattern)
+      str_detect(string, pattern2, negate)
+    }
+  )
+}
+
+#' @rdname str_starts
+#' @export
+str_ends <- function(string, pattern, negate = FALSE) {
+  switch(type(pattern),
+         empty = ,
+         bound = stop("boundary() patterns are not supported."),
+         fixed = stri_endswith_fixed(string, pattern, negate = negate, opts_fixed = opts(pattern)),
+         coll  = stri_endswith_coll(string,  pattern, negate = negate, opts_collator = opts(pattern)),
+         regex = {
+           pattern2 <- paste0(pattern, "$")
+           attributes(pattern2) <- attributes(pattern)
+           str_detect(string, pattern2, negate)
+         }
+  )
+}

man/str_starts.Rd

@@ -24,3 +24,28 @@ test_that("modifiers work", {
 
   expect_true(str_detect("abc", "(?x)a b c"))
 })
+
+test_that("str_starts works", {
+  expect_true(str_starts("ab", "a"))
+  expect_false(str_starts("ab", "b"))
+
+  # negation
+  expect_false(str_starts("ab", "a", TRUE))
+  expect_true(str_starts("ab", "b", TRUE))
+
+  # Special typing of patterns.
+  expect_true(str_starts("ab", fixed("A", ignore_case = TRUE)))
+  expect_true(str_starts("ab", regex("A", ignore_case = TRUE)))
+})
+
+test_that("str_ends works", {
+  expect_true(str_ends("ab", "b"))
+  expect_false(str_ends("ab", "a"))
+
+  # negation
+  expect_false(str_ends("ab", "b", TRUE))
+  expect_true(str_ends("ab", "a", TRUE))
+
+  # Special typing of patterns.
+  expect_true(str_ends("ab", fixed("B", ignore_case = TRUE)))
+})