Implement str_flatten_comma() (#464)

Special case of `str_flatten()` that can automatically handle the Oxford comma with 2 elements.

Author: hadley

NAMESPACE

@@ -27,6 +27,7 @@ export(str_escape)
 export(str_extract)
 export(str_extract_all)
 export(str_flatten)
+export(str_flatten_comma)
 export(str_glue)
 export(str_glue_data)
 export(str_interp)

NEWS.md

@@ -43,6 +43,10 @@
 
 * `str_extract()` can now optionally extract a capturing group instead of
   the complete match (#420).
+  
+* `str_flatten_comma()` is a special case of `str_flatten()` designed for
+  comman separated flattening and can handle the special case of Oxford
+  commas with two elements (#444).
 
 * New `str_split_1()` is tailored for the special case of splitting up a single 
   string (#409).

R/flatten.R

@@ -1,8 +1,13 @@
 #' Flatten a string
+#
+#' @description
+#' `str_flatten()` reduces a character vector to a single string. This is a
+#' summary function because regardless of the length of the input `x`, it
+#' always returns a single string.
 #'
-#' Reduce a character vector to a single string. This is a summary function
-#' because regardless of the length of the input `x`, it always returns a
-#' single string.
+#' `str_flatten_comma()` is a variation designed specifically for flattening
+#' with commas. It automatically recognises if `last` uses the Oxford comma
+#' and handles the special case of 2 elements.
 #'
 #' @inheritParams str_detect
 #' @param collapse String to insert between each piece. Defaults to `""`.
@@ -15,11 +20,20 @@
 #' str_flatten(letters)
 #' str_flatten(letters, "-")
 #'
-#' str_flatten(letters[1:4], ", ", ", and ")
+#' str_flatten(letters[1:3], ", ")
+#'
+#' # Use last to customise the last component
+#' str_flatten(letters[1:3], ", ", " and ")
+#'
+#' # this almost works if you want an Oxford (aka serial) comma
 #' str_flatten(letters[1:3], ", ", ", and ")
+#'
+#' # but it will always add a comma, even when not necessary
 #' str_flatten(letters[1:2], ", ", ", and ")
-#' str_flatten(letters[1], ", ", ", and ")
-#' str_flatten(letters[0], ", ", ", and ")
+#'
+#' # str_flatten_comma knows how to handle the Oxford comma
+#' str_flatten_comma(letters[1:3], ", and ")
+#' str_flatten_comma(letters[1:2], ", and ")
 str_flatten <- function(string, collapse = "", last = NULL, na.rm = FALSE) {
   check_string(collapse)
   check_string(last, allow_null = TRUE)
@@ -39,3 +53,16 @@ str_flatten <- function(string, collapse = "", last = NULL, na.rm = FALSE) {
 
   stri_flatten(string, collapse = collapse)
 }
+
+#' @export
+#' @rdname str_flatten
+str_flatten_comma <- function(string, last = NULL, na.rm = FALSE) {
+  check_string(last, allow_null = TRUE)
+  check_bool(na.rm)
+
+  # Remove comma if exactly two elements, and last uses Oxford comma
+  if (length(string) == 2 && !is.null(last) && str_detect(last, "^,")) {
+    last <- str_replace(last, "^,", "")
+  }
+  str_flatten(string, ", ", last = last, na.rm = na.rm)
+}

man/str_flatten.Rd

@@ -16,3 +16,11 @@ test_that("can remove missing values", {
   expect_equal(str_flatten(c("a", NA)), NA_character_)
   expect_equal(str_flatten(c("a", NA), na.rm = TRUE), "a")
 })
+
+test_that("str_flatten_oxford removes comma iif necessary", {
+  expect_equal(str_flatten_comma(letters[1:2], ", or "), "a or b")
+
+  expect_equal(str_flatten_comma(letters[1:3], ", or "), "a, b, or c")
+  expect_equal(str_flatten_comma(letters[1:3], " or "), "a, b or c")
+  expect_equal(str_flatten_comma(letters[1:3]), "a, b, c")
+})