ARROW-5505: [R] Stop masking base R functions

r/DESCRIPTION

@@ -78,4 +78,5 @@ Collate:
     'read_table.R'
     'reexports-bit64.R'
     'reexports-tidyselect.R'
+    'to-arrow.R'
     'write_arrow.R'

r/NAMESPACE

@@ -83,6 +83,9 @@ S3method(read_table,"arrow::ipc::RecordBatchStreamReader")
 S3method(read_table,character)
 S3method(read_table,fs_path)
 S3method(read_table,raw)
+S3method(to_arrow,"arrow::Object")
+S3method(to_arrow,data.frame)
+S3method(to_arrow,default)
 S3method(type,"arrow::Array")
 S3method(type,"arrow::ChunkedArray")
 S3method(type,"arrow::Column")
@@ -120,7 +123,6 @@ export(RecordBatchStreamWriter)
 export(StatusCode)
 export(TimeUnit)
 export(Type)
-export(array)
 export(arrow_available)
 export(boolean)
 export(buffer)
@@ -176,10 +178,11 @@ export(record_batch)
 export(schema)
 export(starts_with)
 export(struct)
-export(table)
+export(table_from_dots)
 export(time32)
 export(time64)
 export(timestamp)
+export(to_arrow)
 export(type)
 export(uint16)
 export(uint32)

r/R/Table.R

@@ -65,24 +65,6 @@
   )
 )
 
-#' Create an arrow::Table from a data frame
-#'
-#' @param ... arrays, chunked arrays, or R vectors
-#' @param schema a schema. The default (`NULL`) infers the schema from the `...`
-#'
-#' @return an arrow::Table
-#'
-#' @export
-table <- function(..., schema = NULL){
-  dots <- list2(...)
-  # making sure there are always names
-  if (is.null(names(dots))) {
-    names(dots) <- rep_len("", length(dots))
-  }
-  stopifnot(length(dots) > 0)
-  shared_ptr(`arrow::Table`, Table__from_dots(dots, schema))
-}
-
 #' @export
 `as.data.frame.arrow::Table` <- function(x, row.names = NULL, optional = FALSE, use_threads = TRUE, ...){
   Table__to_dataframe(x, use_threads = option_use_threads())

r/R/array.R

@@ -147,13 +147,3 @@
 
 #' @export
 `==.arrow::Array` <- function(x, y) x$Equals(y)
-
-#' create an [arrow::Array][arrow__Array] from an R vector
-#'
-#' @param x R object
-#' @param type Explicit [type][arrow__DataType], or NULL (the default) to infer from the data
-#'
-#' @export
-array <- function(x, type = NULL){
-  `arrow::Array`$dispatch(Array__from_vector(x, type))
-}

r/R/to-arrow.R

@@ -0,0 +1,102 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+#' Send R data structures to Arrow
+#'
+#' @param x an R vector or `data.frame`
+#' @param ... additional arguments passed to some methods:
+#' * `table` logical: when providing a `data.frame` input, should it be made
+#' into an Arrow Table or a struct-type Array? Default is `TRUE` unless you
+#' specify a `type`.
+#' * `type` an explicit [type][arrow__DataType], or NULL (the default) to
+#' infer from `x`. Only valid when making an `Array`.
+#' * `schema` a schema. The default (`NULL`) infers the schema from the `x`.
+#' Only valid when making a `Table` from a `data.frame`
+#' @return An `arrow::Table` if `x` is a `data.frame` unless otherwise directed,
+#' or an `arrow::Array`.
+#' @examples
+#' \donttest{
+#' tbl <- data.frame(
+#'   int = 1:10,
+#'   dbl = as.numeric(1:10),
+#'   lgl = sample(c(TRUE, FALSE, NA), 10, replace = TRUE),
+#'   chr = letters[1:10],
+#'   stringsAsFactors = FALSE
+#' )
+#' tab <- to_arrow(tbl)
+#' tab$schema
+#'
+#' a <- to_arrow(tbl$int)
+#'
+#' # Making a struct column from a data.frame
+#' df <- tibble::tibble(x = 1:10, y = 1:10)
+#' a <- to_arrow(df, table = FALSE)
+#' # Or specify a type
+#' a <- to_arrow(df, type = struct(x = float64(), y = int16()))
+#' }
+#' @export
+to_arrow <- function(x, ...) {
+  UseMethod("to_arrow")
+}
+
+#' @export
+`to_arrow.arrow::Object` <- function(x, ...) x
+
+#' @export
+to_arrow.data.frame <- function(x, table = is.null(type), type = NULL, schema = NULL, ...) {
+  # Validate that at least one of type or schema is null?
+  if (table) {
+    # Default: make an arrow Table
+    shared_ptr(`arrow::Table`, Table__from_dots(x, schema_sxp = schema))
+  } else {
+    # Make this a struct array
+    to_arrow.default(x, type = type)
+  }
+}
+
+#' @export
+to_arrow.default <- function(x, type = NULL, ...) {
+  `arrow::Array`$dispatch(Array__from_vector(x, s_type = type))
+}
+
+#' Create an arrow::Table from diverse inputs
+#'
+#' Unlike [to_arrow()], this function splices together inputs to form a Table.
+#' When providing columns, they can be a mix of Arrow arrays and R vectors.
+#'
+#' @param ... arrays, chunked arrays, or R vectors that should define the
+#' columns of the Arrow Table; alternatively, if record batches are given,
+#' they will be stacked.
+#' @param schema a schema. The default (`NULL`) infers the schema from the `...`
+#'
+#' @return An `arrow::Table`
+#' @examples
+#' \donttest{
+#' tab1 <- table_from_dots(a = 1:10, b = letters[1:10])
+#' tab1
+#' as.data.frame(tab1)
+#' }
+#' @export
+table_from_dots <- function(..., schema = NULL){
+  dots <- list2(...)
+  # making sure there are always names
+  if (is.null(names(dots))) {
+    names(dots) <- rep_len("", length(dots))
+  }
+  stopifnot(length(dots) > 0)
+  shared_ptr(`arrow::Table`, Table__from_dots(dots, schema))
+}

r/R/write_arrow.R

@@ -15,17 +15,6 @@
 # specific language governing permissions and limitations
 # under the License.
 
-to_arrow <- function(x) {
-  UseMethod("to_arrow")
-}
-
-`to_arrow.arrow::RecordBatch` <- function(x) x
-`to_arrow.arrow::Table` <- function(x) x
-
-# splice the data frame as arguments of table()
-# see ?rlang::list2()
-`to_arrow.data.frame` <- function(x) table(!!!x)
-
 #' Write Arrow formatted data
 #'
 #' @param x an [arrow::Table][arrow__Table], an [arrow::RecordBatch][arrow__RecordBatch] or a data.frame

r/README.Rmd

@@ -54,7 +54,8 @@ When installing from source, if the R and C++ library versions do not match, ins
 library(arrow)
 set.seed(24)
 
-tab <- arrow::table(x = 1:10, y = rnorm(10))
+df <- data.frame(x = 1:10, y = rnorm(10))
+tab <- to_arrow(df)
 tab$schema
 tab
 as.data.frame(tab)

r/README.md

@@ -69,7 +69,8 @@ Arrow C++ library first.
 library(arrow)
 set.seed(24)
 
-tab <- arrow::table(x = 1:10, y = rnorm(10))
+df <- data.frame(x = 1:10, y = rnorm(10))
+tab <- to_arrow(df)
 tab$schema
 #> arrow::Schema 
 #> x: int32

r/_pkgdown.yml

@@ -62,12 +62,11 @@ reference:
   - parquet_file_reader
 - title: Arrow data containers
   contents:
+  - to_arrow
   - buffer
-  - array
   - chunked_array
   - record_batch
   - schema
-  - table
   - type
   - dictionary
   - field