diff --git a/r/R/buffer.R b/r/R/buffer.R index b7f6895a618c0..04d9e8c938ff3 100644 --- a/r/R/buffer.R +++ b/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 diff --git a/r/R/chunked-array.R b/r/R/chunked-array.R index dd1beb2afd14d..90b5f4115df94 100644 --- a/r/R/chunked-array.R +++ b/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 diff --git a/r/R/field.R b/r/R/field.R index fce193ab53a41..704c7b4ce85c0 100644 --- a/r/R/field.R +++ b/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 diff --git a/r/R/record-batch.R b/r/R/record-batch.R index 528ecef2f3d13..b137b374e9773 100644 --- a/r/R/record-batch.R +++ b/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) diff --git a/r/R/schema.R b/r/R/schema.R index 70e53f6b6c853..1ad18e314191e 100644 --- a/r/R/schema.R +++ b/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 diff --git a/r/R/table.R b/r/R/table.R index 02ba41578d84b..ac2cbc1440f5b 100644 --- a/r/R/table.R +++ b/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 diff --git a/r/R/type.R b/r/R/type.R index 1283fa256a88b..58d3267243220 100644 --- a/r/R/type.R +++ b/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. diff --git a/r/_pkgdown.yml b/r/_pkgdown.yml index 5331fad53a824..9facce9d1b28b 100644 --- a/r/_pkgdown.yml +++ b/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 diff --git a/r/man/Buffer-class.Rd b/r/man/Buffer-class.Rd new file mode 100644 index 0000000000000..edb56d41806a4 --- /dev/null +++ b/r/man/Buffer-class.Rd @@ -0,0 +1,32 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/buffer.R +\docType{class} +\name{Buffer} +\alias{Buffer} +\title{Buffer class} +\description{ +A Buffer is an object containing a pointer to a piece of +contiguous memory with a particular size. +} +\section{Factory}{ + +\code{buffer()} lets you create an \code{arrow::Buffer} from an R object +} + +\section{Methods}{ + +\itemize{ +\item \verb{$is_mutable} : is this buffer mutable? +\item \verb{$ZeroPadding()} : zero bytes in padding, i.e. bytes between size and capacity +\item \verb{$size} : size in memory, in bytes +\item \verb{$capacity}: possible capacity, in bytes +} +} + +\examples{ +my_buffer <- buffer(c(1, 2, 3, 4)) +my_buffer$is_mutable +my_buffer$ZeroPadding() +my_buffer$size +my_buffer$capacity +} diff --git a/r/man/ChunkedArray.Rd b/r/man/ChunkedArray-class.Rd similarity index 95% rename from r/man/ChunkedArray.Rd rename to r/man/ChunkedArray-class.Rd index 5cb3c4fe749a0..77fa58586686e 100644 --- a/r/man/ChunkedArray.Rd +++ b/r/man/ChunkedArray-class.Rd @@ -3,16 +3,7 @@ \docType{class} \name{ChunkedArray} \alias{ChunkedArray} -\alias{chunked_array} \title{ChunkedArray class} -\usage{ -chunked_array(..., type = NULL) -} -\arguments{ -\item{\dots}{Vectors to coerce} - -\item{type}{currently ignored} -} \description{ A \code{ChunkedArray} is a data structure managing a list of primitive Arrow \link[=Array]{Arrays} logically as one large array. Chunked arrays diff --git a/r/man/DataType.Rd b/r/man/DataType-class.Rd similarity index 100% rename from r/man/DataType.Rd rename to r/man/DataType-class.Rd diff --git a/r/man/Field-class.Rd b/r/man/Field-class.Rd new file mode 100644 index 0000000000000..35d8e236b2b3f --- /dev/null +++ b/r/man/Field-class.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/field.R +\docType{class} +\name{Field} +\alias{Field} +\title{Field class} +\description{ +\code{field()} lets you create an \code{arrow::Field} that maps a +\link[=data-type]{DataType} to a column name. Fields are contained in +\link[=Schema]{Schemas}. +} +\section{Methods}{ + +\itemize{ +\item \code{f$ToString()}: convert to a string +\item \code{f$Equals(other)}: test for equality. More naturally called as \code{f == other} +} +} + diff --git a/r/man/Field.Rd b/r/man/Field.Rd index 9c8f4794fc4b9..4d6fadcad3b09 100644 --- a/r/man/Field.Rd +++ b/r/man/Field.Rd @@ -1,10 +1,8 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/field.R -\docType{class} -\name{Field} -\alias{Field} +\name{field} \alias{field} -\title{Field class} +\title{Create a Field} \usage{ field(name, type, metadata, nullable = TRUE) } @@ -18,18 +16,11 @@ field(name, type, metadata, nullable = TRUE) \item{nullable}{TRUE if field is nullable} } \description{ -\code{field()} lets you create an \code{arrow::Field} that maps a -\link[=data-type]{DataType} to a column name. Fields are contained in -\link[=Schema]{Schemas}. +Create a Field } -\section{Methods}{ - -\itemize{ -\item \code{f$ToString()}: convert to a string -\item \code{f$Equals(other)}: test for equality. More naturally called as \code{f == other} -} -} - \examples{ field("x", int32()) } +\seealso{ +\link{Field} +} diff --git a/r/man/RecordBatch.Rd b/r/man/RecordBatch-class.Rd similarity index 82% rename from r/man/RecordBatch.Rd rename to r/man/RecordBatch-class.Rd index f936a6125b622..513301e8bbada 100644 --- a/r/man/RecordBatch.Rd +++ b/r/man/RecordBatch-class.Rd @@ -3,20 +3,7 @@ \docType{class} \name{RecordBatch} \alias{RecordBatch} -\alias{record_batch} \title{RecordBatch class} -\usage{ -record_batch(..., schema = NULL) -} -\arguments{ -\item{...}{A \code{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 -\code{InputStream}, \code{Message}, \code{Buffer}, or R \code{raw} object containing a \code{Buffer}.} - -\item{schema}{a \link{Schema}, or \code{NULL} (the default) to infer the schema from -the data in \code{...}. When providing an Arrow IPC buffer, \code{schema} is required.} -} \description{ A record batch is a collection of equal-length arrays matching a particular \link{Schema}. It is a table-like data structure that is semantically @@ -80,12 +67,3 @@ All list elements are coerced to string. See \code{schema()} for more informatio } } -\examples{ -batch <- record_batch(name = rownames(mtcars), mtcars) -dim(batch) -dim(head(batch)) -names(batch) -batch$mpg -batch[["cyl"]] -as.data.frame(batch[4:8, c("gear", "hp", "wt")]) -} diff --git a/r/man/schema-class.Rd b/r/man/Schema-class.Rd similarity index 100% rename from r/man/schema-class.Rd rename to r/man/Schema-class.Rd diff --git a/r/man/Table.Rd b/r/man/Table-class.Rd similarity index 82% rename from r/man/Table.Rd rename to r/man/Table-class.Rd index 0423728ef60cd..e8151f69f4569 100644 --- a/r/man/Table.Rd +++ b/r/man/Table-class.Rd @@ -3,20 +3,7 @@ \docType{class} \name{Table} \alias{Table} -\alias{arrow_table} \title{Table class} -\usage{ -arrow_table(..., schema = NULL) -} -\arguments{ -\item{...}{A \code{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 -\code{InputStream}, \code{Message}, \code{Buffer}, or R \code{raw} object containing a \code{Buffer}.} - -\item{schema}{a \link{Schema}, or \code{NULL} (the default) to infer the schema from -the data in \code{...}. When providing an Arrow IPC buffer, \code{schema} is required.} -} \description{ A Table is a sequence of \link[=ChunkedArray]{chunked arrays}. They have a similar interface to \link[=RecordBatch]{record batches}, but they can be @@ -80,12 +67,3 @@ All list elements are coerced to string. See \code{schema()} for more informatio } } -\examples{ -tbl <- arrow_table(name = rownames(mtcars), mtcars) -dim(tbl) -dim(head(tbl)) -names(tbl) -tbl$mpg -tbl[["cyl"]] -as.data.frame(tbl[4:8, c("gear", "hp", "wt")]) -} diff --git a/r/man/buffer.Rd b/r/man/buffer.Rd index 08d66ece5dc3f..c03fd99b00624 100644 --- a/r/man/buffer.Rd +++ b/r/man/buffer.Rd @@ -1,10 +1,8 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/buffer.R -\docType{class} \name{buffer} \alias{buffer} -\alias{Buffer} -\title{Buffer class} +\title{Create a Buffer} \usage{ buffer(x) } @@ -15,28 +13,8 @@ buffer(x) an instance of \code{Buffer} that borrows memory from \code{x} } \description{ -A Buffer is an object containing a pointer to a piece of -contiguous memory with a particular size. +Create a Buffer } -\section{Factory}{ - -\code{buffer()} lets you create an \code{arrow::Buffer} from an R object -} - -\section{Methods}{ - -\itemize{ -\item \verb{$is_mutable} : is this buffer mutable? -\item \verb{$ZeroPadding()} : zero bytes in padding, i.e. bytes between size and capacity -\item \verb{$size} : size in memory, in bytes -\item \verb{$capacity}: possible capacity, in bytes -} -} - -\examples{ -my_buffer <- buffer(c(1, 2, 3, 4)) -my_buffer$is_mutable -my_buffer$ZeroPadding() -my_buffer$size -my_buffer$capacity +\seealso{ +\link{Buffer} } diff --git a/r/man/chunked_array.Rd b/r/man/chunked_array.Rd new file mode 100644 index 0000000000000..b73fd454be18b --- /dev/null +++ b/r/man/chunked_array.Rd @@ -0,0 +1,34 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/chunked-array.R +\name{chunked_array} +\alias{chunked_array} +\title{Create a Chunked Array} +\usage{ +chunked_array(..., type = NULL) +} +\arguments{ +\item{...}{R objects to coerce into a ChunkedArray. They must be of the same type.} + +\item{type}{An optional \link[=data-type]{data type}. If omitted, the type will be inferred from the data.} +} +\description{ +Create a 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{ +\link{ChunkedArray} +} diff --git a/r/man/data-type.Rd b/r/man/data-type.Rd index 79b09a4f32164..214e8ddc1f6c7 100644 --- a/r/man/data-type.Rd +++ b/r/man/data-type.Rd @@ -40,7 +40,7 @@ \alias{fixed_size_list_of} \alias{MapType} \alias{map_of} -\title{Apache Arrow data types} +\title{Create Arrow data types} \usage{ int8() diff --git a/r/man/read_schema.Rd b/r/man/read_schema.Rd index 8738b8aebf740..94d35568de00b 100644 --- a/r/man/read_schema.Rd +++ b/r/man/read_schema.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/schema.R \name{read_schema} \alias{read_schema} -\title{read a Schema from a stream} +\title{Read a Schema from a stream} \usage{ read_schema(stream, ...) } @@ -15,5 +15,5 @@ read_schema(stream, ...) A \link{Schema} } \description{ -read a Schema from a stream +Read a Schema from a stream } diff --git a/r/man/record_batch.Rd b/r/man/record_batch.Rd new file mode 100644 index 0000000000000..6586009448e5c --- /dev/null +++ b/r/man/record_batch.Rd @@ -0,0 +1,29 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/record-batch.R +\name{record_batch} +\alias{record_batch} +\title{Create a RecordBatch} +\usage{ +record_batch(..., schema = NULL) +} +\arguments{ +\item{...}{A \code{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 +\code{InputStream}, \code{Message}, \code{Buffer}, or R \code{raw} object containing a \code{Buffer}.} + +\item{schema}{a \link{Schema}, or \code{NULL} (the default) to infer the schema from +the data in \code{...}. When providing an Arrow IPC buffer, \code{schema} is required.} +} +\description{ +Create a RecordBatch +} +\examples{ +batch <- record_batch(name = rownames(mtcars), mtcars) +dim(batch) +dim(head(batch)) +names(batch) +batch$mpg +batch[["cyl"]] +as.data.frame(batch[4:8, c("gear", "hp", "wt")]) +} diff --git a/r/man/schema.Rd b/r/man/schema.Rd index 42532d84b4271..65ab2eea0d27c 100644 --- a/r/man/schema.Rd +++ b/r/man/schema.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/schema.R \name{schema} \alias{schema} -\title{Schemas} +\title{Create a schema or extract one from an object.} \usage{ schema(...) } diff --git a/r/man/table.Rd b/r/man/table.Rd new file mode 100644 index 0000000000000..f83c56139beb0 --- /dev/null +++ b/r/man/table.Rd @@ -0,0 +1,32 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/table.R +\name{arrow_table} +\alias{arrow_table} +\title{Create an Arrow Table} +\usage{ +arrow_table(..., schema = NULL) +} +\arguments{ +\item{...}{A \code{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 +\code{InputStream}, \code{Message}, \code{Buffer}, or R \code{raw} object containing a \code{Buffer}.} + +\item{schema}{a \link{Schema}, or \code{NULL} (the default) to infer the schema from +the data in \code{...}. When providing an Arrow IPC buffer, \code{schema} is required.} +} +\description{ +Create an Arrow Table +} +\examples{ +tbl <- arrow_table(name = rownames(mtcars), mtcars) +dim(tbl) +dim(head(tbl)) +names(tbl) +tbl$mpg +tbl[["cyl"]] +as.data.frame(tbl[4:8, c("gear", "hp", "wt")]) +} +\seealso{ +\link{Table} +}