R/flatten.R

In stringr: Simple, Consistent Wrappers for Common String Operations

#' 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.
#'
#' `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 `""`.
#' @param last Optional string to use in place of the final separator.
#' @param na.rm Remove missing values? If `FALSE` (the default), the result
#'   will be `NA` if any element of `string` is `NA`.
#' @return A string, i.e. a character vector of length 1.
#' @export
#' @examples
#' str_flatten(letters)
#' str_flatten(letters, "-")
#'
#' 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_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)
  check_bool(na.rm)

  if (na.rm) {
    string <- string[!is.na(string)]
  }

  n <- length(string)
  if (!is.null(last) && n >= 2) {
    string <- c(
      string[seq2(1, n - 2)],
      stringi::stri_c(string[[n - 1]], last, string[[n]])
    )
  }

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