vec_proxy {vctrs}R Documentation

Proxy and restore

Description

[Experimental]

vec_proxy() returns the data structure containing the values of a vector. This data structure is usually the vector itself. In this case the proxy is the identity function, which is the default vec_proxy() method.

Only experts should implement special vec_proxy() methods, for these cases:

vec_restore() is the inverse operation of vec_proxy(). It should only be called on vector proxies.

By default vctrs restores all attributes and classes automatically. You only need to implement a vec_restore() method if your class has attributes that depend on the data.

Usage

vec_proxy(x, ...)

vec_restore(x, to, ...)

Arguments

x

A vector.

...

These dots are for future extensions and must be empty.

to

The original vector to restore to.

Proxying

You should only implement vec_proxy() when your type is designed around a non-vector class. I.e. anything that is not either:

In this case, implement vec_proxy() to return such a vector class. The vctrs operations such as vec_slice() are applied on the proxy and vec_restore() is called to restore the original representation of your type.

The most common case where you need to implement vec_proxy() is for S3 lists. In vctrs, S3 lists are treated as scalars by default. This way we don't treat objects like model fits as vectors. To prevent vctrs from treating your S3 list as a scalar, unclass it in the vec_proxy() method. For instance, here is the definition for list_of:

vec_proxy.vctrs_list_of <- function(x) {
  unclass(x)
}

Another case where you need to implement a proxy is record types. Record types should return a data frame, as in the POSIXlt method:

vec_proxy.POSIXlt <- function(x) {
  new_data_frame(unclass(x))
}

Note that you don't need to implement vec_proxy() when your class inherits from vctrs_vctr or vctrs_rcrd.

Restoring

A restore is a specialised type of cast, primarily used in conjunction with NextMethod() or a C-level function that works on the underlying data structure. A vec_restore() method can make the following assumptions about x:

The length may be different (for example after vec_slice() has been called), and all other attributes may have been lost. The method should restore all attributes so that after restoration, vec_restore(vec_data(x), x) yields x.

To understand the difference between vec_cast() and vec_restore() think about factors: it doesn't make sense to cast an integer to a factor, but if NextMethod() or another low-level function has stripped attributes, you still need to be able to restore them.

The default method copies across all attributes so you only need to provide your own method if your attributes require special care (i.e. they are dependent on the data in some way). When implementing your own method, bear in mind that many R users add attributes to track additional metadata that is important to them, so you should preserve any attributes that don't require special handling for your class.

Dependencies

All vector classes have a proxy, even those who don't implement any vctrs methods. The exception is S3 lists that don't inherit from "list" explicitly. These might have to implement an identity proxy for compatibility with vctrs (see discussion above).


[Package vctrs version 0.6.5 Index]