iv-genericity: Proxy and restore

In DavisVaughan/ivs: Interval Vectors

Proxy and restore

Description

• iv_proxy() is an S3 generic which allows you to write S3 methods for iv extension types to ensure that they are treated like iv objects. The input will be your iv extension object, x, and the return value should be an iv object.

• iv_restore() is an S3 generic that dispatches off to that allows you to restore a proxied iv extension type back to its original type. The inputs will be a bare iv object, x, and your original iv extension object, to, and the return value should correspond to x restored to the type of to, if possible.

You typically don't need to create an iv_proxy() method if your class directly extends iv through the class argument of new_iv(). You only need to implement this if your class has a different structure than a typical iv object. In particular, if vctrs::field(x, "start") and vctrs::field(x, "end") don't return the start and end of the interval vector respectively, then you probably need an iv_proxy() method.

You typically do need an iv_restore() method for custom iv extensions. If your class is simple, then you can generally just call your constructor, like new_my_iv(), to restore the class and any additional attributes that might be required. If your class doesn't use new_iv(), then an iv_restore() method is mandatory, as this is one of the ways that ivs detects that your class is compatible with ivs.

This system allows you to use any iv_*() function on your iv extension object without having to define S3 methods for all of them.

Note that the default method for iv_proxy() returns its input unchanged, even if it isn't an iv. Each iv_*() function does separate checking to ensure that the proxy is a valid iv, or implements an alternate behavior if no proxy method is implemented. In contrast, iv_restore() will error if a method for to isn't registered.

Usage

iv_proxy(x, ...)

iv_restore(x, to, ...)

Arguments

x	[vector] A vector.
...	These dots are for future extensions and must be empty.
to	[vector] The original vector to restore to.

Value

• iv_proxy() should return an iv object for further manipulation.

• iv_restore() should return an object of type to, if possible. In some cases, it may be required to fall back to returning an iv object.

Examples

if (FALSE) {
# Registering S3 methods outside of a package doesn't always work quite
# right (like on the pkgdown site), so this code should only be run by a
# user reading the manual. If that is you, fear not! It should run just fine
# in your console.

library(vctrs)

new_nested_iv <- function(iv) {
  fields <- list(iv = iv)
  new_rcrd(fields, class = "nested_iv")
}

format.nested_iv <- function(x, ...) {
  format(field(x, "iv"))
}

iv_proxy.nested_iv <- function(x, ...) {
  field(x, "iv")
}

iv_restore.nested_iv <- function(x, to, ...) {
  new_nested_iv(x)
}

iv <- new_iv(c(1, 5), c(2, 7))

x <- new_nested_iv(iv)
x

# Proxies, then accesses the `start` field
iv_start(x)

# Proxies, computes the complement to generate an iv,
# then restores to the original type
iv_set_complement(x)

}

DavisVaughan/ivs documentation built on March 18, 2023, 3:20 p.m.