Refresh na_if() and coalesce() docs (#7742)

* Refresh `na_if()` docs

* Refresh `coalesce()` docs

* Also mention `replace_when()`

After reading #5711 and #6511

* Show how `na_if(x, <multiple>)` fails

Author: DavisVaughan

R/coalesce.R

@@ -19,24 +19,48 @@
 #' @return A vector with the same type and size as the common type and common
 #'   size of the vectors in `...`.
 #'
-#' @seealso [na_if()] to replace specified values with an `NA`.
-#'   [tidyr::replace_na()] to replace `NA` with a value.
+#' @seealso
+#'
+#'   - [na_if()] to replace a specified value with `NA`.
+#'
+#'   - [replace_values()] for making arbitrary replacements by value.
+#'
+#'   - [replace_when()] for making arbitrary replacements using logical
+#'     conditions.
 #'
 #' @export
 #' @examples
-#' # Use a single value to replace all missing values
+#' # Replace missing values with a single value
 #' x <- sample(c(1:5, NA, NA, NA))
 #' coalesce(x, 0L)
 #'
-#' # The equivalent to a missing value in a list is `NULL`
-#' coalesce(list(1, 2, NULL), list(NA))
+#' # Or replace missing values with the corresponding non-missing value in
+#' # another vector
+#' x <- c(1, 2, NA, NA, 5, NA)
+#' y <- c(NA, NA, 3, 4, 5, NA)
+#' coalesce(x, y)
+#'
+#' # For cases like these where your replacement is a single value or a single
+#' # vector, `replace_values()` works just as well
+#' replace_values(x, NA ~ 0)
+#' coalesce(x, 0)
 #'
-#' # Or generate a complete vector from partially missing pieces
-#' y <- c(1, 2, NA, NA, 5)
-#' z <- c(NA, NA, 3, 4, 5)
-#' coalesce(y, z)
+#' replace_values(x, NA ~ y)
+#' coalesce(x, y)
+#'
+#' # `coalesce()` really shines when you have >2 vectors to coalesce with
+#' z <- c(NA, 2, 3, 4, 5, 6)
+#' coalesce(x, y, z)
+#'
+#' # If you're looking to replace values with `NA`, rather than replacing `NA`
+#' # with a value, then use `replace_values()`
+#' x <- c(0, -1, 5, -99, 8)
+#' replace_values(x, c(-1, -99) ~ NA)
+#'
+#' # The equivalent to a missing value in a list is `NULL`
+#' coalesce(list(1, 2, NULL, NA), list(0))
 #'
-#' # Supply lists by splicing them into dots:
+#' # Supply lists of vectors by splicing them into dots
 #' vecs <- list(
 #'   c(1, 2, NA, NA, 5),
 #'   c(NA, NA, 3, 4, 5)

R/na-if.R

@@ -15,28 +15,51 @@
 #'   but most of the time this will be a single value.
 #' @return A modified version of `x` that replaces any values that
 #'   are equal to `y` with `NA`.
-#' @seealso [coalesce()] to replace missing values with a specified
-#'   value.
 #'
-#'   [tidyr::replace_na()] to replace `NA` with a value.
+#' @seealso
+#'
+#'   - [coalesce()] to replace `NA`s with the first non-missing value.
+#'
+#'   - [replace_values()] for making arbitrary replacements by value.
+#'
+#'   - [replace_when()] for making arbitrary replacements using logical
+#'     conditions.
+#'
 #' @export
 #' @examples
-#' na_if(1:5, 5:1)
+#' # `na_if()` is useful for replacing a single problematic value with `NA`
+#' na_if(c(-99, 1, 4, 3, -99, 5), -99)
+#' na_if(c("abc", "def", "", "ghi"), "")
+#'
+#' # You can use it to standardize `NaN`s to `NA`
+#' na_if(c(1, NaN, NA, 2, NaN), NaN)
+#'
+#' # Because `na_if()` is an R translation of SQL's `NULLIF` command,
+#' # it compares `x` and `y` element by element. Where `x` and `y` are
+#' # equal, the value in `x` is replaced with an `NA`.
+#' na_if(
+#'   x = c(1, 2, 5, 5, 6),
+#'   y = c(0, 2, 3, 5, 4)
+#' )
+#'
+#' # If you have multiple problematic values that you'd like to replace with
+#' # `NA`, then `replace_values()` is a better choice than `na_if()`
+#' x <- c(-99, 1, 4, 0, -99, 5, -1, 0, 5)
+#' replace_values(x, c(0, -1, -99) ~ NA)
 #'
-#' x <- c(1, -1, 0, 10)
-#' 100 / x
-#' 100 / na_if(x, 0)
+#' # You'd have to nest `na_if()`s to achieve this
+#' try(na_if(x, c(0, -1, -99)))
+#' na_if(na_if(na_if(x, 0), -1), -99)
 #'
-#' y <- c("abc", "def", "", "ghi")
-#' na_if(y, "")
+#' # If you'd like to replace values that match a logical condition with `NA`,
+#' # use `replace_when()`
+#' replace_when(x, x < 0 ~ NA)
 #'
-#' # `na_if()` allows you to replace `NaN` with `NA`,
-#' # even though `NaN == NaN` returns `NA`
-#' z <- c(1, NaN, NA, 2, NaN)
-#' na_if(z, NaN)
+#' # If you'd like to replace `NA` with some other value, use `replace_values()`
+#' x <- c(NA, 5, 2, NA, 0, 3)
+#' replace_values(x, NA ~ 0)
 #'
-#' # `na_if()` is particularly useful inside `mutate()`,
-#' # and is meant for use with vectors rather than entire data frames
+#' # `na_if()` is particularly useful inside `mutate()`
 #' starwars |>
 #'   select(name, eye_color) |>
 #'   mutate(eye_color = na_if(eye_color, "unknown"))