Deprecate miscellaneous functions (#931)

Fixes #925

NEWS.md

@@ -49,6 +49,10 @@
 * `*_dfc()` and `*_dfr()` have been deprecated in favour of using the 
   appropriate map function along with `list_rbind()` or `list_cbind()` (#912).
 
+* `prepend()`, `rdunif()`, `rbernoulli()`, `when()`, and `list_along()` have 
+  all been deprecated (#925). It's now clear that they don't align with the
+  core purpose of purrr.
+
 ## Features and fixes
 
 * New `list_update()` which is similar to `list_modify()` but doesn't work

R/along.R

@@ -1,17 +1,15 @@
 #' Create a list of given length
 #'
 #' @description
+#' `r lifecycle::badge("deprecated")`
 #'
-#' `r lifecycle::badge("questioning")`
+#' This function has been deprecated since it's not related to the core purpose
+#' of purrr.
 #'
 #' It can be useful to create an empty list that you plan to fill later. This is
 #' similar to the idea of [seq_along()], which creates a vector of the same
 #' length as its input.
 #'
-#' @details
-#'
-#' This function might change to [vctrs::vec_init()].
-#'
 #' @param x A vector.
 #' @return A list of the same length as `x`.
 #' @keywords internal
@@ -23,5 +21,7 @@
 #' @rdname along
 #' @export
 list_along <- function(x) {
+  lifecycle::deprecate_warn("0.4.0", "list_along()", I("rep_along(x, list())"))
+
   vector("list", length(x))
 }

R/map-if-at.R

@@ -33,7 +33,7 @@
 map_if <- function(.x, .p, .f, ..., .else = NULL) {
   sel <- probe(.x, .p)
 
-  out <- list_along(.x)
+  out <- vector("list", length(.x))
   out[sel]  <- map(.x[sel], .f, ...)
 
   if (is_null(.else)) {
@@ -65,7 +65,7 @@ map_at <- function(.x, .at, .f, ...) {
   where <- at_selection(names(.x), .at)
   sel <- inv_which(.x, where)
 
-  out <- list_along(.x)
+  out <- vector("list", length(.x))
   out[sel]  <- map(.x[sel], .f, ...)
   out[!sel] <- .x[!sel]
 

R/prepend.R

@@ -1,5 +1,11 @@
 #' Prepend a vector
 #'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' This function has been deprecated since it's not related to the core purpose
+#' of purrr.
+#'
 #' This is a companion to [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
@@ -10,6 +16,7 @@
 #' @param before a subscript, before which the values are to be appended. If
 #'   `NULL`, values will be appended at the beginning even for `x` of length 0.
 #' @return A merged vector.
+#' @keywords internal
 #' @export
 #' @examples
 #' x <- as.list(1:3)
@@ -19,6 +26,8 @@
 #' x %>% prepend(list("a", "b"), before = 3)
 #' prepend(list(), x)
 prepend <- function(x, values, before = NULL) {
+  lifecycle::deprecate_warn("0.4.0", "prepend()", I("append(after = 0)"))
+
   n <- length(x)
   stopifnot(is.null(before) || (before > 0 && before <= n))
 

R/utils.R

@@ -39,26 +39,43 @@ at_selection <- function(nm, .at){
 
 #' Generate random sample from a Bernoulli distribution
 #'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' This function has been deprecated since it's not related to the core purpose
+#' of purrr.
+#'
 #' @param n Number of samples
 #' @param p Probability of getting `TRUE`
 #' @return A logical vector
+#' @keywords internal
 #' @export
 #' @examples
 #' rbernoulli(10)
 #' rbernoulli(100, 0.1)
 rbernoulli <- function(n, p = 0.5) {
+  lifecycle::deprecate_warn("0.4.0", "rbernoulli()")
   stats::runif(n) > (1 - p)
 }
 
 #' Generate random sample from a discrete uniform distribution
 #'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' This function has been deprecated since it's not related to the core purpose
+#' of purrr.
+#'
 #' @param n Number of samples to draw.
 #' @param a,b Range of the distribution (inclusive).
+#' @keywords internal
 #' @export
 #' @examples
 #' table(rdunif(1e3, 10))
 #' table(rdunif(1e3, 10, -5))
 rdunif <- function(n, b, a = 1) {
+  lifecycle::deprecate_warn("0.4.0", "rdunif()")
+
   stopifnot(is.numeric(a), length(a) == 1)
   stopifnot(is.numeric(b), length(b) == 1)
 

R/when.R

@@ -2,8 +2,10 @@
 #' associated with the first valid match.
 #'
 #' @description
+#' `r lifecycle::badge("deprecated")`
 #'
-#' `r lifecycle::badge("questioning")`
+#' This function has been deprecated since it's not related to the core purpose
+#' of purrr. You can now use [dplyr::case_when()] instead.
 #'
 #' `when` is a flavour of pattern matching (or an if-else abstraction) in
 #' which a value is matched against a sequence of condition-action sets. When a
@@ -61,6 +63,8 @@
 #'        ~ stop("Expected fewer than 10 rows."))
 #' @export
 when <- function(., ...) {
+  lifecycle::deprecate_warn("0.4.0", "when()", "dplyr::case_when()")
+
   dots   <- list(...)
   names  <- names(dots)
   named  <- if (is.null(names)) rep(FALSE, length(dots)) else names != ""

_pkgdown.yml

@@ -97,7 +97,4 @@ reference:
   contents:
   - array_tree
   - as_vector
-  - rbernoulli
   - rate-helpers
-  - rdunif
-  - prepend

tests/testthat/_snaps/along.md

@@ -0,0 +1,9 @@
+# list-along is deprecated
+
+    Code
+      . <- list_along(1:4)
+    Condition
+      Warning:
+      `list_along()` was deprecated in purrr 0.4.0.
+      Please use rep_along(x, list()) instead.
+

tests/testthat/_snaps/prepend.md

@@ -0,0 +1,9 @@
+# prepend is deprecated
+
+    Code
+      . <- prepend(1, 2)
+    Condition
+      Warning:
+      `prepend()` was deprecated in purrr 0.4.0.
+      Please use append(after = 0) instead.
+

tests/testthat/_snaps/utils.md

@@ -1,3 +1,16 @@
+# rdunif and rbernoulli are deprecated
+
+    Code
+      . <- rdunif(10, 1)
+    Condition
+      Warning:
+      `rdunif()` was deprecated in purrr 0.4.0.
+    Code
+      . <- rbernoulli(10)
+    Condition
+      Warning:
+      `rbernoulli()` was deprecated in purrr 0.4.0.
+
 # using tidyselect in .at is deprecated
 
     Code

tests/testthat/_snaps/when.md

@@ -0,0 +1,9 @@
+# when is deprecated
+
+    Code
+      . <- when(1:5 < 3 ~ 1, ~0)
+    Condition
+      Warning:
+      `when()` was deprecated in purrr 0.4.0.
+      Please use `dplyr::case_when()` instead.
+

tests/testthat/test-along.R

@@ -1,9 +1,19 @@
+test_that("list-along is deprecated", {
+  expect_snapshot({
+    . <- list_along(1:4)
+  })
+})
+
 test_that("list_along works", {
+  local_options(lifecycle_verbosity = "quiet")
+
   x <- 1:5
   expect_identical(list_along(x), vector("list", 5))
 })
 
 test_that("rep_along works", {
+  local_options(lifecycle_verbosity = "quiet")
+
   expect_equal(
     rep_along(c("c", "b", "a"), 1:3),
     rep_along(c("d", "f", "e"), 1:3)

tests/testthat/test-prepend.R

@@ -1,4 +1,12 @@
+test_that("prepend is deprecated", {
+  expect_snapshot({
+    . <- prepend(1, 2)
+  })
+})
+
 test_that("prepend is clearer version of merging with c()", {
+  local_options(lifecycle_verbosity = "quiet")
+
   x <- 1:3
   expect_identical(
     x %>% prepend(4),
@@ -13,6 +21,8 @@ test_that("prepend is clearer version of merging with c()", {
 })
 
 test_that("prepend appends at the beginning for empty list by default", {
+  local_options(lifecycle_verbosity = "quiet")
+
   x <- list()
   expect_identical(
     x %>% prepend(1),
@@ -21,6 +31,8 @@ test_that("prepend appends at the beginning for empty list by default", {
 })
 
 test_that("prepend throws error if before param is neither NULL nor between 1 and length(x)", {
+  local_options(lifecycle_verbosity = "quiet")
+
   expect_error(
     prepend(list(), 1, before = 1),
     "is.null(before) || (before > 0 && before <= n) is not TRUE"

tests/testthat/test-utils.R

@@ -1,4 +1,13 @@
+test_that("rdunif and rbernoulli are deprecated", {
+  expect_snapshot({
+    . <- rdunif(10, 1)
+    . <- rbernoulli(10)
+  })
+})
+
 test_that("rbernoulli is a special case of rbinom", {
+  local_options(lifecycle_verbosity = "quiet")
+
   set.seed(1)
   x <- rbernoulli(10)
 
@@ -9,10 +18,14 @@ test_that("rbernoulli is a special case of rbinom", {
 })
 
 test_that("rdunif works", {
+  local_options(lifecycle_verbosity = "quiet")
+
   expect_length(rdunif(100, 10), 100)
 })
 
 test_that("rdunif fails if a and b are not unit length numbers", {
+  local_options(lifecycle_verbosity = "quiet")
+
   expect_error(rdunif(1000, 1, "a"))
   expect_error(rdunif(1000, 1, c(0.5, 0.2)))
   expect_error(rdunif(1000, FALSE, 2))