Deprecate prepend() and modify()

Closes #766
Part of tidyverse/purrr#320

NEWS.md

@@ -59,6 +59,14 @@
   `"function"` (@richierocks, #735).
 
 
+## Lifecycle
+
+* `modify()` and `prepend()` (two experimental functions marked as in
+  the questioning stage since rlang 0.3.0) are now deprecated. Vector
+  functions are now out of scope for rlang. They might be revived in
+  the vctrs or funs packages.
+
+
 # rlang 0.3.2
 
 * Fixed protection issue reported by rchk.

R/lifecycle-retired.R

@@ -1474,6 +1474,68 @@ signal_soft_deprecated_along <- function(type, na, env = caller_env(2)) {
   ))
 }
 
+#' Prepend a vector
+#'
+#' @description
+#'
+#' \Sexpr[results=rd, stage=render]{rlang:::lifecycle("deprecated")}
+#'
+#' Vector functions are now out of scope for rlang. They might be
+#' revived in the vctrs or funs packages.
+#'
+#'
+#' @keywords internal
+#'
+#' @param x the vector to be modified.
+#' @param values to be included in the modified vector.
+#' @param before a subscript, before which the values are to be appended.
+#' @export
+prepend <- function(x, values, before = 1) {
+  warn_deprecated_vector("prepend")
+
+  n <- length(x)
+  stopifnot(before > 0 && before <= n)
+
+  if (before == 1) {
+    c(values, x)
+  } else {
+    c(x[1:(before - 1)], values, x[before:n])
+  }
+}
+
+#' @rdname prepend
+#' @param .x A vector to modify.
+#' @param ... List of elements to merge into `.x`. Named elements
+#'   already existing in `.x` are used as replacements. Elements that
+#'   have new or no names are inserted at the end. These dots support
+#'   [tidy dots][tidy-dots] features.
+#' @export
+modify <- function(.x, ...) {
+  warn_deprecated_vector("modify")
+
+  out <- as.list(.x)
+  args <- list2(...)
+
+  args_nms <- names(args)
+  exists <- have_name(args) & args_nms %in% names(out)
+
+  for (nm in args_nms[exists]) {
+    out[[nm]] <- args[[nm]]
+  }
+
+  c(out, args[!exists])
+}
+
+warn_deprecated_vector <- function(fn) {
+  warn_deprecated(paste_line(
+    sprintf("`%s()` is deprecated as of rlang 0.4.0.", fn),
+    "",
+    "Vector tools are now out of scope for rlang to make it a more",
+    "focused package."
+  ))
+}
+
+
 
 #  Attributes  -------------------------------------------------------
 

R/lifecycle.R

@@ -179,6 +179,11 @@
 #'
 #' \Sexpr[results=rd, stage=render]{rlang:::lifecycle("deprecated")}
 #'
+#' **Deprecated as of rlang 0.4.0**
+#'
+#' * [modify()] and [prepend()].
+#'
+#'
 #' **Deprecated as of rlang 0.3.0**
 #'
 #' * [as_data_mask()]: `parent` argument

R/vec-utils.R

@@ -1,90 +1,3 @@
-#' Prepend a vector
-#'
-#' @description
-#'
-#' \Sexpr[results=rd, stage=render]{rlang:::lifecycle("questioning")}
-#' \Sexpr[results=rd, stage=render]{rlang:::lifecycle("experimental")}
-#'
-#' This is a companion to [base::append()] to help merging two lists
-#' or atomic vectors. `prepend()` is a clearer semantic signal than
-#' `c()` that a vector is to be merged at the beginning of another,
-#' especially in a pipe chain.
-#'
-#'
-#' @keywords internal
-#' @section Life cycle:
-#'
-#' `prepend()` is in the qestioning stage. We are still figuring out
-#' what vector tools belong in rlang.
-#'
-#' @param x the vector to be modified.
-#' @param values to be included in the modified vector.
-#' @param before a subscript, before which the values are to be appended.
-#'
-#' @return A merged vector.
-#' @export
-#' @examples
-#' x <- as.list(1:3)
-#'
-#' append(x, "a")
-#' prepend(x, "a")
-#' prepend(x, list("a", "b"), before = 3)
-prepend <- function(x, values, before = 1) {
-  n <- length(x)
-  stopifnot(before > 0 && before <= n)
-
-  if (before == 1) {
-    c(values, x)
-  } else {
-    c(x[1:(before - 1)], values, x[before:n])
-  }
-}
-
-#' Modify a vector
-#'
-#' @description
-#'
-#' \Sexpr[results=rd, stage=render]{rlang:::lifecycle("questioning")}
-#' \Sexpr[results=rd, stage=render]{rlang:::lifecycle("experimental")}
-#'
-#' This function merges a list of arguments into a vector. It always
-#' returns a list.
-#'
-#'
-#' @keywords internal
-#' @section Life cycle:
-#'
-#' `modify()` is in the qestioning stage. We are still figuring out
-#' what vector tools belong in rlang.
-#'
-#' @param .x A vector to modify.
-#' @param ... List of elements to merge into `.x`. Named elements
-#'   already existing in `.x` are used as replacements. Elements that
-#'   have new or no names are inserted at the end. These dots support
-#'   [tidy dots][tidy-dots] features.
-#'
-#' @return A modified vector upcasted to a list.
-#' @export
-#' @examples
-#' modify(c(1, b = 2, 3), 4, b = "foo")
-#'
-#' x <- list(a = 1, b = 2)
-#' y <- list(b = 3, c = 4)
-#' modify(x, splice(y))
-modify <- function(.x, ...) {
-  out <- as.list(.x)
-  args <- list2(...)
-
-  args_nms <- names(args)
-  exists <- have_name(args) & args_nms %in% names(out)
-
-  for (nm in args_nms[exists]) {
-    out[[nm]] <- args[[nm]]
-  }
-
-  c(out, args[!exists])
-}
-
 #' Increasing sequence of integers in an interval
 #'
 #' These helpers take two endpoints and return the sequence of all

tests/testthat/test-retired.R

@@ -514,3 +514,9 @@ test_that("vector _along() ctors pick up names", {
   expect_identical(new_raw_along(x, toupper), set_names(raw(2), c("A", "B")))
   expect_identical(new_list_along(x, toupper), list(A = NULL, B = NULL))
 })
+
+test_that("vector is modified", {
+  x <- c(1, b = 2, c = 3, 4)
+  out <- modify(x, 5, b = 20, splice(list(6, c = "30")))
+  expect_equal(out, list(1, b = 20, c = "30", 4, 5, 6))
+})

tests/testthat/test-vec-utils.R

@@ -1,11 +1,5 @@
 context("vec-utils")
 
-test_that("vector is modified", {
-  x <- c(1, b = 2, c = 3, 4)
-  out <- modify(x, 5, b = 20, splice(list(6, c = "30")))
-  expect_equal(out, list(1, b = 20, c = "30", 4, 5, 6))
-})
-
 test_that("seq2() creates increasing sequences", {
   expect_identical(seq2(2, 3), 2:3)
   expect_identical(seq2(3, 2), int())