R: Proxy and restore

vec_proxy {vctrs} | R Documentation

## Proxy and restore

### Description

`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:

- A vector has vectorised attributes, i.e. metadata for each element of the vector. These record types are implemented in vctrs by returning a data frame in the proxy method. If you're starting your class from scratch, consider deriving from the `rcrd` class. It implements the appropriate data frame proxy and is generally the preferred way to create a record class.

- When you're implementing a vector on top of a non-vector type, like an environment or an S4 object. This is currently only partially supported.

- S3 lists are considered scalars by default. This is the safe choice for list objects such as returned by `stats::lm()`. To declare that your S3 list class is a vector, you normally add `"list"` to the right of your class vector. Explicit inheritance from list is generally the preferred way to declare an S3 list in R, for instance it makes it possible to dispatch on `generic.list` S3 methods.

  If you can't modify your class vector, you can implement an identity proxy (i.e. a proxy method that just returns its input) to let vctrs know this is a vector list and not a scalar.

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

- It undoes the transformations of `vec_proxy()`.

- It restores attributes and classes. These may be lost when the memory values are manipulated. For example slicing a subset of a vector's proxy causes a new proxy to be allocated.

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, ..., n = NULL)

### Arguments

`x` | A vector.
`...` | These dots are for future extensions and must be empty.
`to` | The original vector to restore to.
`n` | The total size to restore to. This is currently passed by `vec_slice()` to solve edge cases arising in data frame restoration. In most cases you don't need this information and can safely ignore that argument. This parameter should be considered internal and experimental, it might change in the future.

### Proxying

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

- An atomic vector

- A bare list

- A data frame

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`:

- It has the correct type.

- It has the correct names.

- It has the correct `dim` and `dimnames` attributes.

- It is unclassed. This way you can call vctrs generics with `x` without triggering an infinite loop of restoration.

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

- `x` must be a vector in the vctrs sense (see `vec_is()`)

- By default the underlying data is returned as is (identity proxy)

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.3.2 Index]