GH-36271: [R] Split out R6 classes and convenience functions (#36394)

Closes: #36271 
* Closes: #36271

Authored-by: Nic Crane <thisisnic@gmail.com>
Signed-off-by: Nic Crane <thisisnic@gmail.com>

r/R/buffer.R

@@ -30,8 +30,8 @@
 #' - `$size` : size in memory, in bytes
 #' - `$capacity`: possible capacity, in bytes
 #'
-#' @rdname buffer
-#' @name buffer
+#' @rdname Buffer-class
+#' @name Buffer
 #' @examples
 #' my_buffer <- buffer(c(1, 2, 3, 4))
 #' my_buffer$is_mutable
@@ -69,8 +69,11 @@ Buffer$create <- function(x) {
   }
 }
 
+#' Create a Buffer
+#' @rdname buffer
 #' @param x R object. Only raw, numeric and integer vectors are currently supported
 #' @return an instance of `Buffer` that borrows memory from `x`
+#' @seealso [Buffer]
 #' @export
 buffer <- Buffer$create
 

r/R/chunked-array.R

@@ -55,7 +55,7 @@
 #' - `$Validate()`: Perform any validation checks to determine obvious inconsistencies
 #'    within the array's internal data. This can be an expensive check, potentially `O(length)`
 #'
-#' @rdname ChunkedArray
+#' @rdname ChunkedArray-class
 #' @name ChunkedArray
 #' @seealso [Array]
 #' @examples
@@ -154,9 +154,26 @@ c.ChunkedArray <- function(...) {
   ChunkedArray$create(...)
 }
 
-#' @param \dots Vectors to coerce
-#' @param type currently ignored
-#' @rdname ChunkedArray
+#' Create a Chunked Array
+#'
+#' @param ... R objects to coerce into a ChunkedArray. They must be of the same type.
+#' @param type An optional [data type][data-type]. If omitted, the type will be inferred from the data.
+#' @rdname chunked_array
+#' @examples
+#' # Pass items into chunked_array as separate objects to create chunks
+#' class_scores <- chunked_array(c(87, 88, 89), c(94, 93, 92), c(71, 72, 73))
+#'
+#' # If you pass a list into chunked_array, you get a list of length 1
+#' list_scores <- chunked_array(list(c(9.9, 9.6, 9.5), c(8.2, 8.3, 8.4), c(10.0, 9.9, 9.8)))
+#'
+#' # When constructing a ChunkedArray, the first chunk is used to infer type.
+#' infer_type(chunked_array(c(1, 2, 3), c(5L, 6L, 7L)))
+#'
+#' # Concatenating chunked arrays returns a new chunked array containing all chunks
+#' a <- chunked_array(c(1, 2), 3)
+#' b <- chunked_array(c(4, 5), 6)
+#' c(a, b)
+#' @seealso [ChunkedArray]
 #' @export
 chunked_array <- ChunkedArray$create
 

r/R/field.R

@@ -28,8 +28,8 @@
 #' - `f$ToString()`: convert to a string
 #' - `f$Equals(other)`: test for equality. More naturally called as `f == other`
 #'
-#' @rdname Field
 #' @name Field
+#' @rdname Field-class
 #' @export
 Field <- R6Class("Field",
   inherit = ArrowObject,
@@ -63,6 +63,8 @@ Field$create <- function(name, type, metadata, nullable = TRUE) {
 #' @include arrowExports.R
 Field$import_from_c <- ImportField
 
+#' Create a Field
+#'
 #' @param name field name
 #' @param type logical type, instance of [DataType]
 #' @param metadata currently ignored
@@ -71,6 +73,7 @@ Field$import_from_c <- ImportField
 #' @examples
 #' field("x", int32())
 #' @rdname Field
+#' @seealso [Field]
 #' @export
 field <- Field$create
 

r/R/record-batch.R

@@ -75,7 +75,7 @@
 #'    Modify or replace by assigning in (`batch$metadata <- new_metadata`).
 #'    All list elements are coerced to string. See `schema()` for more information.
 #' - `$columns`: Returns a list of `Array`s
-#' @rdname RecordBatch
+#' @rdname RecordBatch-class
 #' @name RecordBatch
 #' @export
 RecordBatch <- R6Class("RecordBatch",
@@ -169,13 +169,15 @@ RecordBatch$from_message <- function(obj, schema) {
 #' @include arrowExports.R
 RecordBatch$import_from_c <- ImportRecordBatch
 
+#' Create a RecordBatch
+#'
 #' @param ... A `data.frame` or a named set of Arrays or vectors. If given a
 #' mixture of data.frames and vectors, the inputs will be autospliced together
 #' (see examples). Alternatively, you can provide a single Arrow IPC
 #' `InputStream`, `Message`, `Buffer`, or R `raw` object containing a `Buffer`.
 #' @param schema a [Schema], or `NULL` (the default) to infer the schema from
 #' the data in `...`. When providing an Arrow IPC buffer, `schema` is required.
-#' @rdname RecordBatch
+#' @rdname record_batch
 #' @examples
 #' batch <- record_batch(name = rownames(mtcars), mtcars)
 #' dim(batch)

r/R/schema.R

@@ -75,8 +75,7 @@
 #'   Files with compressed metadata are readable by older versions of arrow, but
 #'   the metadata is dropped.
 #'
-#' @rdname schema-class
-#' @name Schema
+#' @rdname Schema-class
 #' @export
 Schema <- R6Class("Schema",
   inherit = ArrowObject,
@@ -230,8 +229,6 @@ print_schema_fields <- function(s) {
   paste(map_chr(s$fields, ~ .$ToString()), collapse = "\n")
 }
 
-#' Schemas
-#'
 #' Create a schema or extract one from an object.
 #'
 #' @seealso [Schema] for detailed documentation of the Schema R6 object
@@ -383,7 +380,7 @@ length.Schema <- function(x) x$num_fields
 #' @export
 as.list.Schema <- function(x, ...) x$fields
 
-#' read a Schema from a stream
+#' Read a Schema from a stream
 #'
 #' @param stream a `Message`, `InputStream`, or `Buffer`
 #' @param ... currently ignored

r/R/table.R

@@ -74,8 +74,7 @@
 #'    Modify or replace by assigning in (`tab$metadata <- new_metadata`).
 #'    All list elements are coerced to string. See `schema()` for more information.
 #' - `$columns`: Returns a list of `ChunkedArray`s
-#' @rdname Table
-#' @name Table
+#' @rdname Table-class
 #' @export
 Table <- R6Class("Table",
   inherit = ArrowTabular,
@@ -242,13 +241,15 @@ cbind.Table <- function(...) {
   Table$create(!!!columns)
 }
 
+#' Create an Arrow Table
+#'
 #' @param ... A `data.frame` or a named set of Arrays or vectors. If given a
 #' mixture of data.frames and named vectors, the inputs will be autospliced together
 #' (see examples). Alternatively, you can provide a single Arrow IPC
 #' `InputStream`, `Message`, `Buffer`, or R `raw` object containing a `Buffer`.
 #' @param schema a [Schema], or `NULL` (the default) to infer the schema from
 #' the data in `...`. When providing an Arrow IPC buffer, `schema` is required.
-#' @rdname Table
+#' @rdname table
 #' @examples
 #' tbl <- arrow_table(name = rownames(mtcars), mtcars)
 #' dim(tbl)
@@ -257,6 +258,7 @@ cbind.Table <- function(...) {
 #' tbl$mpg
 #' tbl[["cyl"]]
 #' as.data.frame(tbl[4:8, c("gear", "hp", "wt")])
+#' @seealso [Table]
 #' @export
 arrow_table <- Table$create
 

r/R/type.R

@@ -35,7 +35,7 @@
 #' - `$num_fields`: number of child fields.
 #'
 #' @seealso [infer_type()]
-#' @rdname DataType
+#' @rdname DataType-class
 #' @name DataType
 #' @seealso [`data-type`]
 DataType <- R6Class("DataType",
@@ -304,7 +304,7 @@ Decimal256Type <- R6Class("Decimal256Type", inherit = DecimalType)
 
 NestedType <- R6Class("NestedType", inherit = DataType)
 
-#' Apache Arrow data types
+#' Create Arrow data types
 #'
 #' These functions create type objects corresponding to Arrow types. Use them
 #' when defining a [schema()] or as inputs to other types, like `struct`. Most
@@ -378,6 +378,7 @@ NestedType <- R6Class("NestedType", inherit = DataType)
 #' @param ... For `struct()`, a named list of types to define the struct columns
 #'
 #' @name data-type
+#' @rdname data-type
 #' @return An Arrow type object inheriting from [DataType].
 #' @export
 #' @seealso [dictionary()] for creating a dictionary (factor-like) type.

r/_pkgdown.yml

@@ -179,9 +179,9 @@ reference:
   contents:
     - scalar
     - arrow_array
-    - ChunkedArray
-    - RecordBatch
-    - Table
+    - chunked_array
+    - record_batch
+    - arrow_table
     - buffer
     - vctrs_extension_array
 
@@ -207,7 +207,7 @@ reference:
 
 - title: Fields and schemas
   contents:
-  - Field
+  - field
   - schema
   - unify_schemas
   - as_schema
@@ -289,13 +289,18 @@ reference:
   - RecordBatchWriter
   - as_record_batch_reader
 
-- title: Arrow data types, schemas, and containers - R6 classes
+- title: Low-level C++ wrappers
   desc: >
-    R6 classes for Arrow data types.
+    Low-level R6 class representations of Arrow C++ objects intended for advanced users.
   contents:
+  - Buffer
   - Scalar
   - Array
+  - ChunkedArray
+  - RecordBatch
   - Schema
+  - Field
+  - Table
   - DataType
   - ArrayData
   - DictionaryType