Implement replace_when()

Author: DavisVaughan

NAMESPACE

@@ -384,6 +384,7 @@ export(rename_if)
 export(rename_vars)
 export(rename_vars_)
 export(rename_with)
+export(replace_when)
 export(right_join)
 export(row_number)
 export(rows_append)

NEWS.md

@@ -1,5 +1,18 @@
 # dplyr (development version)
 
+* `case_when()` is now part of a family of 4 related functions, 3 of which are new:
+
+  * Use `case_when()` to create a new vector based on logical conditions.
+  * Use `replace_when()` to update an existing vector based on logical conditions.
+  * Use `recode_values()` to create a new vector by mapping old values to new values.
+  * Use `replace_values()` to update an existing vector by mapping old values to new values.
+
+  `replace_when()` is particularly useful for conditionally mutating rows within one or more columns, and can be thought of as an enhanced version of `base::replace()`.
+
+  `recode_values()` and `replace_values()` have the familiar `case_when()`-style formula interface for easy interactive use, but also have `from` and `to` arguments as a way for you to incorporate a pre-built lookup table, making them more holistic replacements for both `case_match()` and `recode()`.
+
+  This work is a result of [Tidyup 7: Recoding and replacing values in the tidyverse](https://github.com/tidyverse/tidyups/blob/main/007-tidyverse-recoding-and-replacing.md), with a lot of great [feedback](https://github.com/tidyverse/tidyups/pull/29) from the community (#7728).
+
 * In `case_when()`, supplying all size 1 LHS inputs along with a size >1 RHS input is now soft-deprecated. This is an improper usage of `case_when()` that should instead be a series of if statements, like:
 
   ```

R/case-match.R

@@ -123,15 +123,14 @@
 #'     .keep = "used"
 #'   )
 case_match <- function(.x, ..., .default = NULL, .ptype = NULL) {
-  args <- list2(...)
+  # Historically it did not allow this, even though in practice it could allow
+  # empty dots to be a no-op, like `replace_when()` and `replace_values()`.
+  allow_empty_dots <- FALSE
 
-  args <- case_formula_evaluate(
-    args = args,
-    default_env = caller_env(),
-    dots_env = current_env(),
-    error_call = current_env()
+  args <- eval_formulas(
+    ...,
+    allow_empty_dots = allow_empty_dots
   )
-
   haystacks <- args$lhs
   values <- args$rhs