This repository is home to the lazyvec package. lazyvec depends heavily on the (complete) ALTREP framework that was rolled out with R 3.6.0. Therefore, you need at least this version of R to build or use the package.

Overview

The lazyvec package for R provides an easy way to create custom ALTREP vectors without the need to write any C/C++ code. The package provides the necessary ALTREP method overrides that are normally implemented in C/C++ and allows the user to write their much simpler R equivalents.

In addition to providing the tools to generate custom ALTREP’s, lazyvec provides a diagnostic framework to observe the internal calls made to existing or custom ALTREP vectors.

Installation

You can install the package directly from GitHub:

# install.packages("devtools")
devtools::install_github("fstpackage/lazyvec")

Basic usage

From R version 3.5 onwards, several basic vectors are (internally) implemented as ALTREP vectors:

library(lazyvec)

x <- 1:10  # this is an ordered sequence

# ordered sequences are implemented as ALTREP vectors
is_altrep(x)
#> [1] TRUE

# ALTREP class
altrep_class(x)
#> [1] "compact_intseq"

# package in which the ALTREP definition is stored
altrep_package(x)
#> [1] "base"

# internal (compact) representation
altrep_data(x)
#> [1] 10  1  1

To study the inner workings of this ALTREP vector, we can add listeners to it:

# add listeners
y <- altrep_listener(x, "x")

We can already see R making calls to the ALTREP vector. Subsequent operations will reveal more of these internal calls to x:

# single element
y[2]
#> x : ALTREP length : result = integer[1] 10
#> x : ALTREP element : result = integer[1] 2
#> [1] 2

# vector length
length(y)
#> x : ALTREP length : result = integer[1] 10
#> x : ALTREP length : result = integer[1] 10
#> [1] 10

# sum
sum(y)
#> ALTREP sum, na.rm =  logical[1] FALSE, result:  integer[1] 55
#> [1] 55

As can be seen, no elements are actually retrieved to calculate the sum, only the internal ALTREP method for calculating the sum is called.

# print vector
min(y)
#> x : ALTREP min : result = NULL[0] 
#> x : ALTREP length : result = integer[1] 10
#> x : ALTREP dataptr_or_null, null returned:  logical[1] TRUE
#> x : ALTREP length : result = integer[1] 10
#> x : ALTREP dataptr_or_null, null returned:  logical[1] TRUE
#> x : ALTREP get_region : result = integer[1] 10, start = integer[1] 0, length = integer[1] 10
#> [1] 1