setAltMethod: Define altWrapper methods

In Jiefei-Wang/AltWrapper: Create an ALTREP object by defining ALTREP functions in R

Description

Define altWrapper methods which are wrappers of ALTREP APIs.

Usage

setAltMethod(className, inspect, getLength, getDataptr, getDataptrOrNull,
  getElement, getSubset, getRegion, duplicate, coerce, serialize,
  unserialize, isSorted, noNA, sum, min, max)

Arguments

className	Character, the name of the class
inspect	Function, see detail
getLength	Function, see detail
getDataptr	Function, see detail
getDataptrOrNull	Function, see detail
getElement	Function, see detail
getSubset	Function, see detail
getRegion	Function, see detail
duplicate	Function, see detail
coerce	Function, see detail
serialize	Function, see detail
unserialize	Function, see detail
isSorted	Function, see detail
noNA	Function, see detail
sum	Function, see detail
min	Function, see detail
max	Function, see detail

Details

This function defines the behavior of an altWrapper class. The altWrapper methods are fundamentally wrappers of ALTREP APIs. Any call to the ALTREP APIs will be converted to a call of the corresponding altWrapper methods.

Belows are the definitions of the altWrapper methods. x is the data of the altWrapper object.

Function	Arguments	Return value
inspect	x	A logical value
getLength	x	An integer/numeric value
getDataptr	x, writeable	Vector/External pointer
getDataptrOrNull	x	Vector/External pointer/NULL
getElement	x, i	An entry of the ALTREP vector
getSubset	x, i	A subset of the ALTREP vector
getRegion	x, start, length, output	Length of the true reads
duplicate	x, deep	The duplicated object
coerce	x, type	The coerced object
serialize	x	Any R object
unserialize	R_class, state	Any R object
isSorted	x	An integer value
noNA	x	An integer value
sum	x, na.rm	An integer/numeric value
min	x, na.rm	An integer/numeric value
max	x, na.rm	An integer/numeric value

inspect function determines the output of a .Internal(inspect(...)) call. Return value = FALSE means using the default method to inspect the object.

getLength function returns the length of the ALTREP object

getDataptr function returns the data pointer of the ALTREP object. The argument writeable means whether R will write data to the pointer. Unlike getDataptrOrNull function. This function must return a pointer. It is suggested to throw an error if the ALTREP object does not have a data pointer. Please note that before R 3.7, getDataptr is the only way to print out an ALTREP object without using S3 or S4 method dispatching when the data pointer of the object is not available.

getDataptrOrNull function is similar to getDataptr function, but it can return NULL if the data pointer is not available.

getElement function returns the value of the ALTREP vector at a given position. The argument i is a 1-based index of the vector.

getSubset function returns a subset of the ALTREP vector. The argument i is a 1-based subset.

getRegion function reads a continuous region of the ALTREP vector. The argument start is the 1-based starting position of the reads. length determines the length of the reads. Unlike most R functions, the result of the reads should be returned via the argument output instead of using return function. Users must use [<- operator to change the value of the output argument. The return value of getRegion function is the true number of reads in the output argument. In most case the return value is the same as length, it will be different only when start + length - 1 exceeds the length of the ALTREP vector.

duplicate function duplicates the ALTREP vector. The argument deep determines whether it is a deep copy or not. A default duplicate method will be used if the return value is NULL.

coerce function coerces the ALTREP vector to the other data type. The integer argument type is the index of the target type. Please refer to SEXPTYPEs to see the meaning of the index.

serialize function serialize the ALTREP object. The return value is called state and will be used in unserialize function.

unserialize function unserialize the ALTREP object. The argument state is the return value of serialize function. The argument R_class is for compatibility only.

isSorted whether the ALTREP vector is sorted in the ascending or descending order. The vector status can be unknown sortness, known unsorted, ascending, descending, ascending with NA first, descending with NA first. You can find the corresponding return values by accessing the list variable altrepSortStatus.

noNA check whether the ALTREP vector contains any NA value. The return value must be an element of the list altrepNAStatus.

sum, min and max have the same meaning as R's corresponding functions. These functions are only available for integer and double ALTREP class type.

Value

No return value

Examples

## Define the ALTREP functions
length_func <- function(x) length(x)
get_ptr_func <- function(x,writeable) x


## Define the altWrapper class and its functions
setAltClass(className = "example", classType = "integer")
setAltMethod(className = "example", getLength = length_func)
setAltMethod(className = "example", getDataptr = get_ptr_func)

## Create an altWrapper object by providing the class name and data.
A <- newAltrep(className = "example", x = 1L:10L)
A

Jiefei-Wang/AltWrapper documentation built on Oct. 30, 2019, 7:43 p.m.