paleolimbot commented on a change in pull request #12467: URL: https://github.com/apache/arrow/pull/12467#discussion_r838771333
########## File path: r/R/extension.R ########## @@ -0,0 +1,543 @@ +# 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. + +#' @include arrow-package.R + + +#' @title class arrow::ExtensionArray +#' +#' @usage NULL +#' @format NULL +#' @docType class +#' +#' @section Methods: +#' +#' The `ExtensionArray` class inherits from `Array`, but also provides +#' access to the underlying storage of the extension. +#' +#' - `$storage()`: Returns the underlying [Array] used to store +#' values. +#' +#' The `ExtensionArray` is not intended to be subclassed for extension +#' types. +#' +#' @rdname ExtensionArray +#' @name ExtensionArray +#' @export +ExtensionArray <- R6Class("ExtensionArray", + inherit = Array, + public = list( + storage = function() { + ExtensionArray__storage(self) + }, + + as_vector = function() { + self$type$as_vector(self) + } + ) +) + +ExtensionArray$create <- function(x, type) { + assert_is(type, "ExtensionType") + if (inherits(x, "ExtensionArray") && type$Equals(x$type)) { + return(x) + } + + storage <- Array$create(x, type = type$storage_type()) + type$WrapArray(storage) +} + +#' @title class arrow::ExtensionType +#' +#' @usage NULL +#' @format NULL +#' @docType class +#' +#' @section Methods: +#' +#' The `ExtensionType` class inherits from `DataType`, but also defines +#' extra methods specific to extension types: +#' +#' - `$storage_type()`: Returns the underlying [DataType] used to store +#' values. +#' - `$storage_id()`: Returns the [Type] identifier corresponding to the +#' `$storage_type()`. +#' - `$extension_name()`: Returns the extension name. +#' - `$Serialize()`: Returns the serialized version of the extension +#' metadata as a [raw()] vector. +#' - `$WrapArray(array)`: Wraps a storage [Array] into an [ExtensionArray] +#' with this extension type. +#' +#' In addition, subclasses may override the following methos to customize +#' the behaviour of extension classes. +#' +#' - `$Deserialize()`: This method is called when a new [ExtensionType] +#' is initialized and is responsible for parsing and validating +#' the serialized extension_metadata (a [raw()] vector) +#' such that its contents can be inspected by fields and/or methods +#' of the R6 ExtensionType subclass. Implementations must also check the +#' `storage_type` to make sure it is compatible with the extension type. +#' - `$as_vector(extension_array)`: Convert an [Array] or [ChunkedArray] to an R +#' vector. This method is called by [as.vector()] on [ExtensionArray] +#' objects, when a [RecordBatch] containing an [ExtensionArray] is +#' converted to a [data.frame()], or when a [ChunkedArray] (e.g., a column +#' in a [Table]) is converted to an R vector. The default method returns the +#' converted storage array. +#' - `$ToString()` Return a string representation that will be printed +#' to the console when this type or an Array of this type is printed. +#' +#' @rdname ExtensionType +#' @name ExtensionType +#' @export +ExtensionType <- R6Class("ExtensionType", + inherit = DataType, + public = list( + + # In addition to the initialization that occurs for all + # ArrowObject instances, we call Deserialize(), which can + # be overridden to populate custom fields + initialize = function(xp) { + super$initialize(xp) + self$Deserialize() + }, + + # Because of how C++ shared_ptr<> objects are converted to R objects, + # the initial object that is instantiated will be of this class + # (ExtensionType), but the R6Class object that was registered is + # available from C++. We need this in order to produce the correct + # R6 subclass when a shared_ptr<ExtensionType> is returned to R. + r6_class = function() { + ExtensionType__r6_class(self) + }, + + storage_type = function() { + ExtensionType__storage_type(self) + }, + + storage_id = function() { + self$storage_type()$id + }, + + extension_name = function() { + ExtensionType__extension_name(self) + }, + + Serialize = function() { + ExtensionType__Serialize(self) + }, Review comment: I went with `deserialize_instance()` (we *are* deserializing, but maybe more clear that it's specific to this instance and not creating a new one?) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
