Implement rows_append() (#6249)

* New rows_append() with data.frame method

* Document

* Revert documentation update in `ident()`

* Tweak example comment

* Flesh out the `rows_append()` tests more

* Add return value details for `rows_patch()` and `rows_append()`

* NEWS bullet

Co-authored-by: DavisVaughan <davis@rstudio.com>

Author: krlmlr

NAMESPACE

@@ -124,6 +124,7 @@ S3method(rename_,data.frame)
 S3method(rename_,grouped_df)
 S3method(rename_with,data.frame)
 S3method(right_join,data.frame)
+S3method(rows_append,data.frame)
 S3method(rows_delete,data.frame)
 S3method(rows_insert,data.frame)
 S3method(rows_patch,data.frame)
@@ -376,6 +377,7 @@ export(rename_vars_)
 export(rename_with)
 export(right_join)
 export(row_number)
+export(rows_append)
 export(rows_delete)
 export(rows_insert)
 export(rows_patch)

NEWS.md

@@ -1,5 +1,10 @@
 # dplyr (development version)
 
+* New `rows_append()` which works like `rows_insert()` but ignores keys and
+  allows you to insert arbitrary rows with a guarantee that the type of `x`
+  won't change (#6249, thanks to @krlmlr for the implementation and @mgirlich
+  for the idea).
+
 * The `rows_*()` functions no longer require that the key values in `x` uniquely
   identify each row. Additionally, `rows_insert()` and `rows_delete()` no
   longer require that the key values in `y` uniquely identify each row. Relaxing

R/rows.R

@@ -11,6 +11,7 @@
 #'
 #' * `rows_insert()` adds new rows (like `INSERT`). By default, key values in
 #'   `y` must not exist in `x`.
+#' * `rows_append()` works like `rows_insert()` but ignores keys.
 #' * `rows_update()` modifies existing rows (like `UPDATE`). Key values in `y`
 #'   must be unique, and, by default, key values in `y` must exist in `x`.
 #' * `rows_patch()` works like `rows_update()` but only overwrites `NA` values.
@@ -55,9 +56,10 @@
 #' An object of the same type as `x`. The order of the rows and columns of `x`
 #' is preserved as much as possible. The output has the following properties:
 #'
-#' * `rows_update()` preserves rows as is; `rows_insert()` and `rows_upsert()`
-#'   return all existing rows and potentially new rows; `rows_delete()` returns
-#'   a subset of the rows.
+#' * `rows_update()` and `rows_patch()` preserve the number of rows;
+#'   `rows_insert()`, `rows_append()`, and `rows_upsert()` return all existing
+#'   rows and potentially new rows; `rows_delete()` returns a subset of the
+#'   rows.
 #' * Columns are not added, removed, or relocated, though the data may be
 #'   updated.
 #' * Groups are taken from `x`.
@@ -74,9 +76,11 @@
 #'
 #' # By default, if a key in `y` matches a key in `x`, then it can't be inserted
 #' # and will throw an error. Alternatively, you can ignore rows in `y`
-#' # containing keys that conflict with keys in `x` with `conflict = "ignore"`.
+#' # containing keys that conflict with keys in `x` with `conflict = "ignore"`,
+#' # or you can use `rows_append()` to ignore keys entirely.
 #' try(rows_insert(data, tibble(a = 3, b = "z")))
 #' rows_insert(data, tibble(a = 3, b = "z"), conflict = "ignore")
+#' rows_append(data, tibble(a = 3, b = "z"))
 #'
 #' # Update
 #' rows_update(data, tibble(a = 2:3, b = "z"))
@@ -144,6 +148,34 @@ rows_insert.data.frame <- function(x,
   rows_bind(x, y)
 }
 
+#' @rdname rows
+#' @export
+rows_append <- function(x,
+                        y,
+                        ...,
+                        copy = FALSE,
+                        in_place = FALSE) {
+  lifecycle::signal_stage("experimental", "rows_append()")
+  UseMethod("rows_append")
+}
+
+#' @export
+rows_append.data.frame <- function(x,
+                                   y,
+                                   ...,
+                                   copy = FALSE,
+                                   in_place = FALSE) {
+  check_dots_empty()
+  rows_df_in_place(in_place)
+
+  y <- auto_copy(x, y, copy = copy)
+
+  rows_check_containment(x, y)
+  y <- rows_cast_y(y, x)
+
+  rows_bind(x, y)
+}
+
 #' @rdname rows
 #' @export
 rows_update <- function(x,

man/rows.Rd

@@ -55,6 +55,26 @@
       Error in `rows_insert()`:
       ! `conflict` must be a character vector, not a number.
 
+# rows_append() casts to the type of `x`
+
+    Code
+      (expect_error(rows_append(x, y)))
+    Output
+      <error/vctrs_error_cast_lossy>
+      Error in `rows_append()`:
+      ! Can't convert from `y$key` <double> to `x$key` <integer> due to loss of precision.
+      * Locations: 1
+
+# rows_append() requires that `y` columns be a subset of `x`
+
+    Code
+      (expect_error(rows_append(x, y)))
+    Output
+      <error/rlang_error>
+      Error in `rows_append()`:
+      ! All columns in `y` must exist in `x`.
+      i The following columns only exist in `y`: `c`.
+
 # rows_update() requires `y` keys to exist in `x` by default
 
     Code

tests/testthat/_snaps/rows.md

@@ -89,6 +89,53 @@ test_that("`conflict` is validated", {
   })
 })
 
+# ------------------------------------------------------------------------------
+# rows_append()
+
+test_that("rows_append() allows you to insert unconditionally", {
+  x <- tibble(a = 1, b = 2)
+  y <- tibble(a = 1, b = 3)
+
+  expect_identical(rows_append(x, y), bind_rows(x, y))
+
+  y <- tibble(a = c(1, 2, 1), b = c(3, 4, 5))
+
+  expect_identical(rows_append(x, y), bind_rows(x, y))
+})
+
+test_that("rows_append() casts to the type of `x`", {
+  x <- vctrs::data_frame(key = 1L, value = 2)
+
+  y <- vctrs::data_frame(key = 1.5, value = 1.5)
+
+  expect_snapshot({
+    (expect_error(rows_append(x, y)))
+  })
+
+  y <- vctrs::data_frame(key = 2, value = 3L)
+
+  out <- rows_append(x, y)
+  expect_identical(out$key, c(1L, 2L))
+  expect_identical(out$value, c(2, 3))
+})
+
+test_that("rows_append() requires that `y` columns be a subset of `x`", {
+  x <- tibble(a = 1, b = 2)
+  y <- tibble(a = 1, b = 2, c = 3)
+
+  expect_snapshot({
+    (expect_error(rows_append(x, y)))
+  })
+})
+
+test_that("rows_append() doesn't require that `x` columns be a subset of `y`", {
+  x <- tibble(a = 1, b = 2, c = 3)
+  y <- tibble(a = 1, b = 2)
+
+  out <- rows_append(x, y)
+  expect_identical(out$c, c(3, NA))
+})
+
 # ------------------------------------------------------------------------------
 
 test_that("rows_update() works", {