ARROW-7796: [R] write_* functions should invisibly return their inputs

I had some trouble building from source on Windows but I thought the changes were simple enough that I just went ahead. Tests and documentation also updated.

Closes #6387 from boshek/write_return and squashes the following commits:

d4d1ead <Sam Albers> Update r/NEWS.md
5f0e316 <Sam Albers> Merge branch 'master' into write_return
5d32579 <Sam Albers> update NEWS
53c3ab9 <Sam Albers> Update r/tests/testthat/test-read-write.R
673de49 <Sam Albers> Update r/tests/testthat/test-feather.R
11db34c <Sam Albers> Update r/tests/testthat/test-parquet.R
12222d6 <Sam Albers> update documentation
3768d0f <Sam Albers> return invisibly
a595854 <Sam Albers> write_arrow returns input
cac8db8 <Sam Albers> write_feather returns input
f6b79de <Sam Albers> write_parquet returns input

Lead-authored-by: Sam Albers <sam.albers@gov.bc.ca>
Co-authored-by: Sam Albers <sam.albers@gmail.com>
Signed-off-by: Neal Richardson <neal.p.richardson@gmail.com>

r/NEWS.md

@@ -19,6 +19,9 @@
 
 # arrow 0.16.0.9000
 
+
+* `write_feather`, `write_arrow` and `write_parquet` now return their input
+similar to `write_*` functions from `readr` (#6387, @boshek)
 * Dataset filtering is now correctly supported for all Arrow date/time/timestamp column types.
 
 # arrow 0.16.0

r/R/feather.R

@@ -20,6 +20,8 @@
 #' @param x `data.frame` or RecordBatch
 #' @param sink A file path or an OutputStream
 #'
+#' @return the input `x` invisibly.
+#'
 #' @export
 #' @examples
 #' \donttest{
@@ -29,6 +31,8 @@
 #' }
 #' @include arrow-package.R
 write_feather <- function(x, sink) {
+  x_out <- x
+
   if (is.data.frame(x)) {
     x <- record_batch(x)
   }
@@ -42,6 +46,8 @@ write_feather <- function(x, sink) {
 
   writer <- FeatherTableWriter$create(sink)
   ipc___TableWriter__RecordBatch__WriteFeather(writer, x)
+
+  invisible(x_out)
 }
 
 #' @title FeatherTableWriter class

r/R/parquet.R

@@ -99,7 +99,7 @@ read_parquet <- function(file,
 #' disable compression, set `compression = "uncompressed"`.
 #' Note that "uncompressed" columns may still have dictionary encoding.
 #'
-#' @return `NULL`, invisibly
+#' @return the input `x` invisibly.
 #'
 #' @examples
 #' \donttest{
@@ -145,6 +145,7 @@ write_parquet <- function(x,
     allow_truncated_timestamps = allow_truncated_timestamps
   )
 ) {
+  x_out <- x
   x <- to_arrow(x)
 
   if (is.character(sink)) {
@@ -164,6 +165,8 @@ write_parquet <- function(x,
   writer <- ParquetFileWriter$create(schema, sink, properties = properties, arrow_properties = arrow_properties)
   writer$WriteTable(x, chunk_size = chunk_size %||% x$num_rows)
   writer$Close()
+
+  invisible(x_out)
 }
 
 

r/R/write-arrow.R

@@ -49,6 +49,7 @@ to_arrow.data.frame <- function(x) Table$create(!!!x)
 #' `write_arrow` is a convenience function, the classes [arrow::RecordBatchFileWriter][RecordBatchFileWriter]
 #' and [arrow::RecordBatchStreamWriter][RecordBatchStreamWriter] can be used for more flexibility.
 #'
+#' @return the input `x` invisibly.
 #' @export
 write_arrow <- function(x, sink, ...) {
   UseMethod("write_arrow", sink)
@@ -61,6 +62,7 @@ write_arrow.RecordBatchWriter <- function(x, sink, ...){
 
 #' @export
 write_arrow.character <- function(x, sink, ...) {
+  x_out <- x
   assert_that(length(sink) == 1L)
   x <- to_arrow(x)
   file_stream <- FileOutputStream$create(sink)
@@ -74,6 +76,8 @@ write_arrow.character <- function(x, sink, ...) {
   # Available on R >= 3.5
   # on.exit(file_writer$close(), add = TRUE, after = FALSE)
   write_arrow(x, file_writer, ...)
+
+  invisible(x_out)
 }
 
 #' @export

r/tests/testthat/test-feather.R

@@ -25,6 +25,11 @@ test_that("Write a feather file", {
   expect_true(file.exists(feather_file))
 })
 
+test_that("write_feather() returns its input", {
+  tib_out <- write_feather(tib, feather_file)
+  expect_identical(tib_out, tib)
+})
+
 test_that("feather read/write round trip", {
   tf2 <- normalizePath(tempfile(), mustWork = FALSE)
   write_feather(tib, tf2)

r/tests/testthat/test-parquet.R

@@ -130,3 +130,11 @@ test_that("write_parquet() to stream", {
   con$close()
   expect_equal(read_parquet(tf), df)
 })
+
+test_that("write_parquet() returns its input", {
+  df <- tibble::tibble(x = 1:5)
+  tf <- tempfile()
+  on.exit(unlink(tf))
+  df_out <- write_parquet(df, tf)
+  expect_identical(df, df_out)
+})

r/tests/testthat/test-read-write.R

@@ -112,3 +112,12 @@ test_that("table round trip handles NA in integer and numeric", {
   expect_true(is.na(res$dbl[10]))
   unlink(tf)
 })
+
+
+test_that("write_arrow() returns its input", {
+  df <- tibble::tibble(x = 1:5)
+  tf <- tempfile()
+  on.exit(unlink(tf))
+  df_out <- write_arrow(df, tf)
+  expect_identical(df, df_out)
+})