Clarify that both character() and NULL are allowed for names_to (#1234)

* Clarify `names_to` handling in `build_longer_spec()`

* Refresh `names_to` documentation to describe the 3 cases

Explicitly allow `character()` or `NULL`, as both seem reasonable and we already do this in the CRAN version

Author: DavisVaughan

R/pivot-long.R

@@ -16,16 +16,25 @@
 #' @param data A data frame to pivot.
 #' @param cols <[`tidy-select`][tidyr_tidy_select]> Columns to pivot into
 #'   longer format.
-#' @param names_to A string specifying the name of the column to create
-#'   from the data stored in the column names of `data`.
+#' @param names_to A character vector specifying the new column or columns to
+#'   create from the information stored in the column names of `data` specified
+#'   by `cols`.
 #'
-#'   Can be a character vector, creating multiple columns, if `names_sep`
-#'   or `names_pattern` is provided. In this case, there are two special
-#'   values you can take advantage of:
+#'   * If length 0, or if `NULL` is supplied, no columns will be created.
 #'
-#'   * `NA` will discard that component of the name.
-#'   * `.value` indicates that component of the name defines the name of the
-#'     column containing the cell values, overriding `values_to`.
+#'   * If length 1, a single column will be created which will contain the
+#'     column names specified by `cols`.
+#'
+#'   * If length >1, multiple columns will be created. In this case, one of
+#'     `names_sep` or `names_pattern` must be supplied to specify how the
+#'     column names should be split. There are also two additional character
+#'     values you can take advantage of:
+#'
+#'     * `NA` will discard the corresponding component of the column name.
+#'
+#'     * `".value"` indicates that the corresponding component of the column
+#'       name defines the name of the output column containing the cell values,
+#'       overriding `values_to` entirely.
 #' @param names_prefix A regular expression used to remove matching text
 #'   from the start of each variable name.
 #' @param names_sep,names_pattern If `names_to` contains multiple values,
@@ -262,7 +271,8 @@ pivot_longer_spec <- function(data,
 
 #' @rdname pivot_longer_spec
 #' @export
-build_longer_spec <- function(data, cols,
+build_longer_spec <- function(data,
+                              cols,
                               names_to = "name",
                               values_to = "value",
                               names_prefix = NULL,
@@ -282,30 +292,41 @@ build_longer_spec <- function(data, cols,
     names <- gsub(vec_paste0("^", names_prefix), "", names(cols))
   }
 
-  if (length(names_to) > 1) {
-    if (!xor(is.null(names_sep), is.null(names_pattern))) {
+  if (is.null(names_to)) {
+    names_to <- character(0L)
+  }
+  if (!is.character(names_to)) {
+    abort("`names_to` must be a character vector or `NULL`.")
+  }
+
+  n_names_to <- length(names_to)
+  has_names_sep <- !is.null(names_sep)
+  has_names_pattern <- !is.null(names_pattern)
+
+  if (n_names_to == 0L) {
+    names <- tibble::new_tibble(x = list(), nrow = length(names))
+  } else if (n_names_to == 1L) {
+    if (has_names_sep) {
+      abort("`names_sep` can't be used with a length 1 `names_to`.")
+    }
+    if (has_names_pattern) {
+      names <- str_extract(names, names_to, regex = names_pattern)[[1]]
+    }
+
+    names <- tibble(!!names_to := names)
+  } else {
+    if (!xor(has_names_sep, has_names_pattern)) {
       abort(glue::glue(
         "If you supply multiple names in `names_to` you must also supply one",
         " of `names_sep` or `names_pattern`."
       ))
     }
 
-    if (!is.null(names_sep)) {
+    if (has_names_sep) {
       names <- str_separate(names, names_to, sep = names_sep)
     } else {
       names <- str_extract(names, names_to, regex = names_pattern)
     }
-  } else if (length(names_to) == 0) {
-    names <- tibble::new_tibble(x = list(), nrow = length(names))
-  } else {
-    if (!is.null(names_sep)) {
-      abort("`names_sep` can not be used with length-1 `names_to`")
-    }
-    if (!is.null(names_pattern)) {
-      names <- str_extract(names, names_to, regex = names_pattern)[[1]]
-    }
-
-    names <- tibble(!!names_to := names)
   }
 
   if (".value" %in% names_to) {

man/pivot_longer.Rd

@@ -0,0 +1,19 @@
+# `names_to` is validated
+
+    Code
+      (expect_error(build_longer_spec(df, x, names_to = 1)))
+    Output
+      <error/rlang_error>
+      `names_to` must be a character vector or `NULL`.
+    Code
+      (expect_error(build_longer_spec(df, x, names_to = c("x", "y"))))
+    Output
+      <error/rlang_error>
+      If you supply multiple names in `names_to` you must also supply one of `names_sep` or `names_pattern`.
+    Code
+      (expect_error(build_longer_spec(df, x, names_to = c("x", "y"), names_sep = "_",
+      names_pattern = "x")))
+    Output
+      <error/rlang_error>
+      If you supply multiple names in `names_to` you must also supply one of `names_sep` or `names_pattern`.
+

man/pivot_longer_spec.Rd

@@ -170,12 +170,18 @@ test_that("validates inputs", {
   )
 })
 
-test_that("no names doesn't generate names", {
+test_that("no names doesn't generate names (#1120)", {
   df <- tibble(x = 1)
-  expect_equal(
+
+  expect_identical(
     colnames(build_longer_spec(df, x, names_to = character())),
     c(".name", ".value")
   )
+
+  expect_identical(
+    colnames(build_longer_spec(df, x, names_to = NULL)),
+    c(".name", ".value")
+  )
 })
 
 test_that("multiple names requires names_sep/names_pattern", {
@@ -245,3 +251,13 @@ test_that("can cast to custom type", {
 test_that("Error if the `col` can't be selected.", {
   expect_error(pivot_longer(iris, matches("foo")), "select at least one")
 })
+
+test_that("`names_to` is validated", {
+  df <- tibble(x = 1)
+
+  expect_snapshot({
+    (expect_error(build_longer_spec(df, x, names_to = 1)))
+    (expect_error(build_longer_spec(df, x, names_to = c("x", "y"))))
+    (expect_error(build_longer_spec(df, x, names_to = c("x", "y"), names_sep = "_", names_pattern = "x")))
+  })
+})