EVOLUTION-MANAGER
Edit File: reference-faq-compatibility.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: FAQ - Is my class compatible with vctrs?</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for reference-faq-compatibility {vctrs}"><tr><td>reference-faq-compatibility {vctrs}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>FAQ - Is my class compatible with vctrs?</h2> <h3>Description</h3> <p>vctrs provides a framework for working with vector classes in a generic way. However, it implements several compatibility fallbacks to base R methods. In this reference you will find how vctrs tries to be compatible with your vector class, and what base methods you need to implement for compatibility. </p> <p>If you’re starting from scratch, we think you’ll find it easier to start using <code><a href="new_vctr.html">new_vctr()</a></code> as documented in <code>vignette("s3-vector")</code>. This guide is aimed for developers with existing vector classes. </p> <h4>Aggregate operations with fallbacks</h4> <p>All vctrs operations are based on four primitive generics described in the next section. However there are many higher level operations. The most important ones implement fallbacks to base generics for maximum compatibility with existing classes. </p> <ul> <li> <p><code><a href="vec_slice.html">vec_slice()</a></code> falls back to the base <code>[</code> generic if no <code><a href="vec_proxy.html">vec_proxy()</a></code> method is implemented. This way foreign classes that do not implement <code><a href="vec_proxy.html">vec_restore()</a></code> can restore attributes based on the new subsetted contents. </p> </li> <li> <p><code><a href="vec_c.html">vec_c()</a></code> and <code><a href="vec_bind.html">vec_rbind()</a></code> now fall back to <code><a href="../../base/html/c.html">base::c()</a></code> if the inputs have a common parent class with a <code>c()</code> method (only if they have no self-to-self <code>vec_ptype2()</code> method). </p> <p>vctrs works hard to make your <code>c()</code> method success in various situations (with <code>NULL</code> and <code>NA</code> inputs, even as first input which would normally prevent dispatch to your method). The main downside compared to using vctrs primitives is that you can’t combine vectors of different classes since there is no extensible mechanism of coercion in <code>c()</code>, and it is less efficient in some cases. </p> </li></ul> <h4>The vctrs primitives</h4> <p>Most functions in vctrs are aggregate operations: they call other vctrs functions which themselves call other vctrs functions. The dependencies of a vctrs functions are listed in the Dependencies section of its documentation page. Take a look at <code><a href="vec_count.html">vec_count()</a></code> for an example. </p> <p>These dependencies form a tree whose leaves are the four vctrs primitives. Here is the diagram for <code>vec_count()</code>: </p> <p><img src="../help/figures/vec-count-deps.png" alt="vec-count-deps.png" /> </p> <h5>The coercion generics</h5> <p>The coercion mechanism in vctrs is based on two generics: </p> <ul> <li> <p><code><a href="vec_ptype2.html">vec_ptype2()</a></code> </p> </li> <li> <p><code><a href="vec_cast.html">vec_cast()</a></code> </p> </li></ul> <p>See the <a href="theory-faq-coercion.html">theory overview</a>. </p> <p>Two objects with the same class and the same attributes are always considered compatible by ptype2 and cast. If the attributes or classes differ, they throw an incompatible type error. </p> <p>Coercion errors are the main source of incompatibility with vctrs. See the <a href="howto-faq-coercion.html">howto guide</a> if you need to implement methods for these generics. </p> <h5>The proxy and restoration generics</h5> <ul> <li> <p><code><a href="vec_proxy.html">vec_proxy()</a></code> </p> </li> <li> <p><code><a href="vec_proxy.html">vec_restore()</a></code> </p> </li></ul> <p>These generics are essential for vctrs but mostly optional. <code>vec_proxy()</code> defaults to an <a href="../../base/html/identity.html">identity</a> function and you normally don’t need to implement it. The proxy a vector must be one of the atomic vector types, a list, or a data frame. By default, S3 lists that do not inherit from <code>"list"</code> do not have an identity proxy. In that case, you need to explicitly implement <code>vec_proxy()</code> or make your class inherit from list. </p> <hr /><div style="text-align: center;">[Package <em>vctrs</em> version 0.5.0 <a href="00Index.html">Index</a>]</div> </body></html>