Implement filter_out() (#7775)

* Implement `filter_out()`

* Document `filter_out()`

* Revise examples

* Overhaul tests to include `filter_out()`

* Add to list of `.by` supported verbs

* Mention in extending dplyr docs

* Mention in `across()` example

* Test alongside `pick()`

* Test alongside `rowwise()`

* Use `filter_out()` in a few vignettes

* Mark `filter_out()` as experimental

* NEWS bullet

* Add complement test

* Fix NEWS example

BECAUSE THIS IS HARD Y'ALL

* Apply documentation updates from code review

* Remove `filter_out()` defunct tests

Author: DavisVaughan

NAMESPACE

@@ -61,6 +61,7 @@ S3method(filter_,data.frame)
 S3method(filter_,tbl_df)
 S3method(filter_bullets,"dplyr:::filter_incompatible_size")
 S3method(filter_bullets,"dplyr:::filter_incompatible_type")
+S3method(filter_out,data.frame)
 S3method(full_join,data.frame)
 S3method(group_by,data.frame)
 S3method(group_by_,data.frame)
@@ -281,6 +282,7 @@ export(filter_)
 export(filter_all)
 export(filter_at)
 export(filter_if)
+export(filter_out)
 export(first)
 export(full_join)
 export(funs)

NEWS.md

@@ -1,5 +1,23 @@
 # dplyr (development version)
 
+* New `filter_out()` companion to `filter()`.
+
+  * Use `filter()` when specifying rows to _keep_.
+
+  * Use `filter_out()` when specifying rows to _drop_.
+
+  `filter_out()` simplifies cases where you would have previously used a `filter()` to drop rows. It is particularly useful when missing values are involved. For example, to drop rows where the `count` is zero:
+
+  ```r
+  df |> filter(count != 0 | is.na(count))
+
+  df |> filter_out(count == 0)
+  ```
+
+  With `filter()`, you must provide a "negative" condition of `!= 0` and must explicitly guard against accidentally dropping rows with `NA`. With `filter_out()`, you directly specify rows to drop and you don't have to guard against dropping rows with `NA`, which tends to result in much clearer code.
+
+  This work is a result of [Tidyup 8: Expanding the `filter()` family](https://github.com/tidyverse/tidyups/pull/30), with a lot of great feedback from the community (#6560, #6891).
+
 * The `.groups` message emitted by `summarise()` is hopefully more clear now (#6986).
 
 * `if_any()` and `if_all()` are now more consistent in all use cases (#7059, #7077, #7746, @jrwinget). In particular:

R/across.R

@@ -204,7 +204,12 @@
 #' iris |>
 #'   filter(if_any(ends_with("Width"), ~ . > 4))
 #' iris |>
+#'   filter_out(if_any(ends_with("Width"), ~ . > 4))
+#'
+#' iris |>
 #'   filter(if_all(ends_with("Width"), ~ . > 2))
+#' iris |>
+#'   filter_out(if_all(ends_with("Width"), ~ . > 2))
 #'
 #' @export
 #' @seealso [c_across()] for a function that returns a vector

R/data-mask.R

@@ -116,11 +116,12 @@ DataMask <- R6Class(
       eval()
     },
 
-    eval_all_filter = function(quos, env_filter) {
+    eval_all_filter = function(quos, invert, env_filter) {
       eval <- function() {
         .Call(
           `dplyr_mask_eval_all_filter`,
           quos,
+          invert,
           private,
           private$size,
           env_filter