<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta name="generator" content="pandoc" /> <meta http-equiv="X-UA-Compatible" content="IE=EDGE" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>S3 vectors</title> <script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to // be compatible with the behavior of Pandoc < 2.8). document.addEventListener('DOMContentLoaded', function(e) { var hs = document.querySelectorAll("div.section[class*='level'] > :first-child"); var i, h, a; for (i = 0; i < hs.length; i++) { h = hs[i]; if (!/^h[1-6]$/i.test(h.tagName)) continue; // it should be a header h1-h6 a = h.attributes; while (a.length > 0) h.removeAttribute(a[0].name); } }); </script> <style type="text/css"> code{white-space: pre-wrap;} span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} </style> <style type="text/css"> code { white-space: pre; } .sourceCode { overflow: visible; } </style> <style type="text/css" data-origin="pandoc"> pre > code.sourceCode { white-space: pre; position: relative; } pre > code.sourceCode > span { line-height: 1.25; } pre > code.sourceCode > span:empty { height: 1.2em; } .sourceCode { overflow: visible; } code.sourceCode > span { color: inherit; text-decoration: inherit; } div.sourceCode { margin: 1em 0; } pre.sourceCode { margin: 0; } @media screen { div.sourceCode { overflow: auto; } } @media print { pre > code.sourceCode { white-space: pre-wrap; } pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; } } pre.numberSource code { counter-reset: source-line 0; } pre.numberSource code > span { position: relative; left: -4em; counter-increment: source-line; } pre.numberSource code > span > a:first-child::before { content: counter(source-line); position: relative; left: -1em; text-align: right; vertical-align: baseline; border: none; display: inline-block; -webkit-touch-callout: none; -webkit-user-select: none; -khtml-user-select: none; -moz-user-select: none; -ms-user-select: none; user-select: none; padding: 0 4px; width: 4em; color: #aaaaaa; } pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; } div.sourceCode { } @media screen { pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } } code span.al { color: #ff0000; font-weight: bold; } code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } code span.at { color: #7d9029; } code span.bn { color: #40a070; } code span.bu { color: #008000; } code span.cf { color: #007020; font-weight: bold; } code span.ch { color: #4070a0; } code span.cn { color: #880000; } code span.co { color: #60a0b0; font-style: italic; } code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } code span.do { color: #ba2121; font-style: italic; } code span.dt { color: #902000; } code span.dv { color: #40a070; } code span.er { color: #ff0000; font-weight: bold; } code span.ex { } code span.fl { color: #40a070; } code span.fu { color: #06287e; } code span.im { color: #008000; font-weight: bold; } code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } code span.kw { color: #007020; font-weight: bold; } code span.op { color: #666666; } code span.ot { color: #007020; } code span.pp { color: #bc7a00; } code span.sc { color: #4070a0; } code span.ss { color: #bb6688; } code span.st { color: #4070a0; } code span.va { color: #19177c; } code span.vs { color: #4070a0; } code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } </style> <script> // apply pandoc div.sourceCode style to pre.sourceCode instead (function() { var sheets = document.styleSheets; for (var i = 0; i < sheets.length; i++) { if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue; try { var rules = sheets[i].cssRules; } catch (e) { continue; } var j = 0; while (j < rules.length) { var rule = rules[j]; // check if there is a div.sourceCode rule if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") { j++; continue; } var style = rule.style.cssText; // check if color or background-color is set if (rule.style.color === '' && rule.style.backgroundColor === '') { j++; continue; } // replace div.sourceCode by a pre.sourceCode rule sheets[i].deleteRule(j); sheets[i].insertRule('pre.sourceCode{' + style + '}', j); } } })(); </script> <style type="text/css">body { background-color: #fff; margin: 1em auto; max-width: 700px; overflow: visible; padding-left: 2em; padding-right: 2em; font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; font-size: 14px; line-height: 1.35; } #TOC { clear: both; margin: 0 0 10px 10px; padding: 4px; width: 400px; border: 1px solid #CCCCCC; border-radius: 5px; background-color: #f6f6f6; font-size: 13px; line-height: 1.3; } #TOC .toctitle { font-weight: bold; font-size: 15px; margin-left: 5px; } #TOC ul { padding-left: 40px; margin-left: -1.5em; margin-top: 5px; margin-bottom: 5px; } #TOC ul ul { margin-left: -2em; } #TOC li { line-height: 16px; } table { margin: 1em auto; border-width: 1px; border-color: #DDDDDD; border-style: outset; border-collapse: collapse; } table th { border-width: 2px; padding: 5px; border-style: inset; } table td { border-width: 1px; border-style: inset; line-height: 18px; padding: 5px 5px; } table, table th, table td { border-left-style: none; border-right-style: none; } table thead, table tr.even { background-color: #f7f7f7; } p { margin: 0.5em 0; } blockquote { background-color: #f6f6f6; padding: 0.25em 0.75em; } hr { border-style: solid; border: none; border-top: 1px solid #777; margin: 28px 0; } dl { margin-left: 0; } dl dd { margin-bottom: 13px; margin-left: 13px; } dl dt { font-weight: bold; } ul { margin-top: 0; } ul li { list-style: circle outside; } ul ul { margin-bottom: 0; } pre, code { background-color: #f7f7f7; border-radius: 3px; color: #333; white-space: pre-wrap; } pre { border-radius: 3px; margin: 5px 0px 10px 0px; padding: 10px; } pre:not([class]) { background-color: #f7f7f7; } code { font-family: Consolas, Monaco, 'Courier New', monospace; font-size: 85%; } p > code, li > code { padding: 2px 0px; } div.figure { text-align: center; } img { background-color: #FFFFFF; padding: 2px; border: 1px solid #DDDDDD; border-radius: 3px; border: 1px solid #CCCCCC; margin: 0 5px; } h1 { margin-top: 0; font-size: 35px; line-height: 40px; } h2 { border-bottom: 4px solid #f7f7f7; padding-top: 10px; padding-bottom: 2px; font-size: 145%; } h3 { border-bottom: 2px solid #f7f7f7; padding-top: 10px; font-size: 120%; } h4 { border-bottom: 1px solid #f7f7f7; margin-left: 8px; font-size: 105%; } h5, h6 { border-bottom: 1px solid #ccc; font-size: 105%; } a { color: #0033dd; text-decoration: none; } a:hover { color: #6666ff; } a:visited { color: #800080; } a:visited:hover { color: #BB00BB; } a[href^="http:"] { text-decoration: underline; } a[href^="https:"] { text-decoration: underline; } code > span.kw { color: #555; font-weight: bold; } code > span.dt { color: #902000; } code > span.dv { color: #40a070; } code > span.bn { color: #d14; } code > span.fl { color: #d14; } code > span.ch { color: #d14; } code > span.st { color: #d14; } code > span.co { color: #888888; font-style: italic; } code > span.ot { color: #007020; } code > span.al { color: #ff0000; font-weight: bold; } code > span.fu { color: #900; font-weight: bold; } code > span.er { color: #a61717; background-color: #e3d2d2; } </style> </head> <body> <h1 class="title toc-ignore">S3 vectors</h1> <p>This vignette shows you how to create your own S3 vector classes. It focuses on the aspects of making a vector class that every class needs to worry about; you’ll also need to provide methods that actually make the vector useful.</p> <p>I assume that you’re already familiar with the basic machinery of S3, and the vocabulary I use in Advanced R: constructor, helper, and validator. If not, I recommend reading at least the first two sections of <a href="https://adv-r.hadley.nz/s3.html">the S3 chapter</a> of <em>Advanced R</em>.</p> <p>This article refers to “vectors of numbers” as <em>double vectors</em>. Here, “double” stands for <a href="https://en.wikipedia.org/wiki/Double-precision_floating-point_format">“double precision floating point number”</a>, see also <code>double()</code>.</p> <div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" tabindex="-1"></a><span class="fu">library</span>(vctrs)</span> <span id="cb1-2"><a href="#cb1-2" tabindex="-1"></a><span class="fu">library</span>(rlang)</span> <span id="cb1-3"><a href="#cb1-3" tabindex="-1"></a><span class="fu">library</span>(zeallot)</span></code></pre></div> <p>This vignette works through five big topics:</p> <ul> <li>The basics of creating a new vector class with vctrs.</li> <li>The coercion and casting system.</li> <li>The record and list-of types.</li> <li>Equality and comparison proxies.</li> <li>Arithmetic operators.</li> </ul> <p>They’re collectively demonstrated with a number of simple S3 classes:</p> <ul> <li><p>Percent: a double vector that prints as a percentage. This illustrates the basic mechanics of class creation, coercion, and casting.</p></li> <li><p>Decimal: a double vector that always prints with a fixed number of decimal places. This class has an attribute which needs a little extra care in casts and coercions.</p></li> <li><p>Cached sum: a double vector that caches the total sum in an attribute. The attribute depends on the data, so needs extra care.</p></li> <li><p>Rational: a pair of integer vectors that defines a rational number like <code>2 / 3</code>. This introduces you to the record style, and to the equality and comparison operators. It also needs special handling for <code>+</code>, <code>-</code>, and friends.</p></li> <li><p>Polynomial: a list of integer vectors that define polynomials like <code>1 + x - x^3</code>. Sorting such vectors correctly requires a custom equality method.</p></li> <li><p>Meter: a numeric vector with meter units. This is the simplest possible class with interesting algebraic properties.</p></li> <li><p>Period and frequency: a pair of classes represent a period, or its inverse, frequency. This allows us to explore more arithmetic operators.</p></li> </ul> <div id="basics" class="section level2"> <h2>Basics</h2> <p>In this section you’ll learn how to create a new vctrs class by calling <code>new_vctr()</code>. This creates an object with class <code>vctrs_vctr</code> which has a number of methods. These are designed to make your life as easy as possible. For example:</p> <ul> <li><p>The <code>print()</code> and <code>str()</code> methods are defined in terms of <code>format()</code> so you get a pleasant, consistent display as soon as you’ve made your <code>format()</code> method.</p></li> <li><p>You can immediately put your new vector class in a data frame because <code>as.data.frame.vctrs_vctr()</code> does the right thing.</p></li> <li><p>Subsetting (<code>[</code>, <code>[[</code>, and <code>$</code>), <code>length<-</code>, and <code>rep()</code> methods automatically preserve attributes because they use <code>vec_restore()</code>. A default <code>vec_restore()</code> works for all classes where the attributes are data-independent, and can easily be customised when the attributes do depend on the data.</p></li> <li><p>Default subset-assignment methods (<code>[<-</code>, <code>[[<-</code>, and <code>$<-</code>) follow the principle that the new values should be coerced to match the existing vector. This gives predictable behaviour and clear error messages.</p></li> </ul> <div id="percent-class" class="section level3"> <h3>Percent class</h3> <p>In this section, I’ll show you how to make a <code>percent</code> class, i.e., a double vector that is printed as a percentage. We start by defining a low-level <a href="https://adv-r.hadley.nz/s3.html#s3-constrcutor">constructor</a> to check types and/or sizes and call <code>new_vctr()</code>.</p> <p><code>percent</code> is built on a double vector of any length and doesn’t have any attributes.</p> <div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1" tabindex="-1"></a>new_percent <span class="ot"><-</span> <span class="cf">function</span>(<span class="at">x =</span> <span class="fu">double</span>()) {</span> <span id="cb2-2"><a href="#cb2-2" tabindex="-1"></a> <span class="cf">if</span> (<span class="sc">!</span><span class="fu">is_double</span>(x)) {</span> <span id="cb2-3"><a href="#cb2-3" tabindex="-1"></a> <span class="fu">abort</span>(<span class="st">"`x` must be a double vector."</span>)</span> <span id="cb2-4"><a href="#cb2-4" tabindex="-1"></a> }</span> <span id="cb2-5"><a href="#cb2-5" tabindex="-1"></a> <span class="fu">new_vctr</span>(x, <span class="at">class =</span> <span class="st">"vctrs_percent"</span>)</span> <span id="cb2-6"><a href="#cb2-6" tabindex="-1"></a>}</span> <span id="cb2-7"><a href="#cb2-7" tabindex="-1"></a></span> <span id="cb2-8"><a href="#cb2-8" tabindex="-1"></a>x <span class="ot"><-</span> <span class="fu">new_percent</span>(<span class="fu">c</span>(<span class="fu">seq</span>(<span class="dv">0</span>, <span class="dv">1</span>, <span class="at">length.out =</span> <span class="dv">4</span>), <span class="cn">NA</span>))</span> <span id="cb2-9"><a href="#cb2-9" tabindex="-1"></a>x</span> <span id="cb2-10"><a href="#cb2-10" tabindex="-1"></a><span class="co">#> <vctrs_percent[5]></span></span> <span id="cb2-11"><a href="#cb2-11" tabindex="-1"></a><span class="co">#> [1] 0.0000000 0.3333333 0.6666667 1.0000000 NA</span></span> <span id="cb2-12"><a href="#cb2-12" tabindex="-1"></a></span> <span id="cb2-13"><a href="#cb2-13" tabindex="-1"></a><span class="fu">str</span>(x)</span> <span id="cb2-14"><a href="#cb2-14" tabindex="-1"></a><span class="co">#> vctrs_pr [1:5] 0.0000000, 0.3333333, 0.6666667, 1.0000000, NA</span></span></code></pre></div> <p>Note that we prefix the name of the class with the name of the package. This prevents conflicting definitions between packages. For packages that implement only one class (such as <a href="https://blob.tidyverse.org/">blob</a>), it’s fine to use the package name without prefix as the class name.</p> <p>We then follow up with a user friendly <a href="https://adv-r.hadley.nz/s3.html#helpers">helper</a>. Here we’ll use <code>vec_cast()</code> to allow it to accept anything coercible to a double:</p> <div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1" tabindex="-1"></a>percent <span class="ot"><-</span> <span class="cf">function</span>(<span class="at">x =</span> <span class="fu">double</span>()) {</span> <span id="cb3-2"><a href="#cb3-2" tabindex="-1"></a> x <span class="ot"><-</span> <span class="fu">vec_cast</span>(x, <span class="fu">double</span>())</span> <span id="cb3-3"><a href="#cb3-3" tabindex="-1"></a> <span class="fu">new_percent</span>(x)</span> <span id="cb3-4"><a href="#cb3-4" tabindex="-1"></a>}</span></code></pre></div> <p>Before you go on, check that user-friendly constructor returns a zero-length vector when called with no arguments. This makes it easy to use as a prototype.</p> <div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb4-1"><a href="#cb4-1" tabindex="-1"></a><span class="fu">new_percent</span>()</span> <span id="cb4-2"><a href="#cb4-2" tabindex="-1"></a><span class="co">#> <vctrs_percent[0]></span></span> <span id="cb4-3"><a href="#cb4-3" tabindex="-1"></a><span class="fu">percent</span>()</span> <span id="cb4-4"><a href="#cb4-4" tabindex="-1"></a><span class="co">#> <vctrs_percent[0]></span></span></code></pre></div> <p>For the convenience of your users, consider implementing an <code>is_percent()</code> function:</p> <div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb5-1"><a href="#cb5-1" tabindex="-1"></a>is_percent <span class="ot"><-</span> <span class="cf">function</span>(x) {</span> <span id="cb5-2"><a href="#cb5-2" tabindex="-1"></a> <span class="fu">inherits</span>(x, <span class="st">"vctrs_percent"</span>)</span> <span id="cb5-3"><a href="#cb5-3" tabindex="-1"></a>}</span></code></pre></div> </div> <div id="format-method" class="section level3"> <h3><code>format()</code> method</h3> <p>The first method for every class should almost always be a <code>format()</code> method. This should return a character vector the same length as <code>x</code>. The easiest way to do this is to rely on one of R’s low-level formatting functions like <code>formatC()</code>:</p> <div class="sourceCode" id="cb6"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb6-1"><a href="#cb6-1" tabindex="-1"></a>format.vctrs_percent <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb6-2"><a href="#cb6-2" tabindex="-1"></a> out <span class="ot"><-</span> <span class="fu">formatC</span>(<span class="fu">signif</span>(<span class="fu">vec_data</span>(x) <span class="sc">*</span> <span class="dv">100</span>, <span class="dv">3</span>))</span> <span id="cb6-3"><a href="#cb6-3" tabindex="-1"></a> out[<span class="fu">is.na</span>(x)] <span class="ot"><-</span> <span class="cn">NA</span></span> <span id="cb6-4"><a href="#cb6-4" tabindex="-1"></a> out[<span class="sc">!</span><span class="fu">is.na</span>(x)] <span class="ot"><-</span> <span class="fu">paste0</span>(out[<span class="sc">!</span><span class="fu">is.na</span>(x)], <span class="st">"%"</span>)</span> <span id="cb6-5"><a href="#cb6-5" tabindex="-1"></a> out</span> <span id="cb6-6"><a href="#cb6-6" tabindex="-1"></a>}</span></code></pre></div> <div class="sourceCode" id="cb7"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb7-1"><a href="#cb7-1" tabindex="-1"></a>x</span> <span id="cb7-2"><a href="#cb7-2" tabindex="-1"></a><span class="co">#> <vctrs_percent[5]></span></span> <span id="cb7-3"><a href="#cb7-3" tabindex="-1"></a><span class="co">#> [1] 0% 33.3% 66.7% 100% <NA></span></span></code></pre></div> <p>(Note the use of <code>vec_data()</code> so <code>format()</code> doesn’t get stuck in an infinite loop, and that I take a little care to not convert <code>NA</code> to <code>"NA"</code>; this leads to better printing.)</p> <p>The format method is also used by data frames, tibbles, and <code>str()</code>:</p> <div class="sourceCode" id="cb8"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb8-1"><a href="#cb8-1" tabindex="-1"></a><span class="fu">data.frame</span>(x)</span> <span id="cb8-2"><a href="#cb8-2" tabindex="-1"></a><span class="co">#> x</span></span> <span id="cb8-3"><a href="#cb8-3" tabindex="-1"></a><span class="co">#> 1 0%</span></span> <span id="cb8-4"><a href="#cb8-4" tabindex="-1"></a><span class="co">#> 2 33.3%</span></span> <span id="cb8-5"><a href="#cb8-5" tabindex="-1"></a><span class="co">#> 3 66.7%</span></span> <span id="cb8-6"><a href="#cb8-6" tabindex="-1"></a><span class="co">#> 4 100%</span></span> <span id="cb8-7"><a href="#cb8-7" tabindex="-1"></a><span class="co">#> 5 <NA></span></span></code></pre></div> <p>For optimal display, I recommend also defining an abbreviated type name, which should be 4-5 letters for commonly used vectors. This is used in tibbles and in <code>str()</code>:</p> <div class="sourceCode" id="cb9"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb9-1"><a href="#cb9-1" tabindex="-1"></a>vec_ptype_abbr.vctrs_percent <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb9-2"><a href="#cb9-2" tabindex="-1"></a> <span class="st">"prcnt"</span></span> <span id="cb9-3"><a href="#cb9-3" tabindex="-1"></a>}</span> <span id="cb9-4"><a href="#cb9-4" tabindex="-1"></a></span> <span id="cb9-5"><a href="#cb9-5" tabindex="-1"></a>tibble<span class="sc">::</span><span class="fu">tibble</span>(x)</span> <span id="cb9-6"><a href="#cb9-6" tabindex="-1"></a><span class="co">#> # A tibble: 5 × 1</span></span> <span id="cb9-7"><a href="#cb9-7" tabindex="-1"></a><span class="co">#> x</span></span> <span id="cb9-8"><a href="#cb9-8" tabindex="-1"></a><span class="co">#> <prcnt></span></span> <span id="cb9-9"><a href="#cb9-9" tabindex="-1"></a><span class="co">#> 1 0%</span></span> <span id="cb9-10"><a href="#cb9-10" tabindex="-1"></a><span class="co">#> 2 33.3%</span></span> <span id="cb9-11"><a href="#cb9-11" tabindex="-1"></a><span class="co">#> 3 66.7%</span></span> <span id="cb9-12"><a href="#cb9-12" tabindex="-1"></a><span class="co">#> 4 100%</span></span> <span id="cb9-13"><a href="#cb9-13" tabindex="-1"></a><span class="co">#> 5 NA</span></span> <span id="cb9-14"><a href="#cb9-14" tabindex="-1"></a></span> <span id="cb9-15"><a href="#cb9-15" tabindex="-1"></a><span class="fu">str</span>(x)</span> <span id="cb9-16"><a href="#cb9-16" tabindex="-1"></a><span class="co">#> prcnt [1:5] 0%, 33.3%, 66.7%, 100%, <NA></span></span></code></pre></div> <p>If you need more control over printing in tibbles, implement a method for <code>pillar::pillar_shaft()</code>. See <code>vignette("pillar", package = "vctrs")</code> for details.</p> </div> </div> <div id="casting-and-coercion" class="section level2"> <h2>Casting and coercion</h2> <p>The next set of methods you are likely to need are those related to coercion and casting. Coercion and casting are two sides of the same coin: changing the prototype of an existing object. When the change happens <em>implicitly</em> (e.g in <code>c()</code>) we call it <strong>coercion</strong>; when the change happens <em>explicitly</em> (e.g. with <code>as.integer(x)</code>), we call it <strong>casting</strong>.</p> <p>One of the main goals of vctrs is to put coercion and casting on a robust theoretical footing so it’s possible to make accurate predictions about what (e.g.) <code>c(x, y)</code> should do when <code>x</code> and <code>y</code> have different prototypes. vctrs achieves this goal through two generics:</p> <ul> <li><p><code>vec_ptype2(x, y)</code> defines possible set of coercions. It returns a prototype if <code>x</code> and <code>y</code> can be safely coerced to the same prototype; otherwise it returns an error. The set of automatic coercions is usually quite small because too many tend to make code harder to reason about and silently propagate mistakes.</p></li> <li><p><code>vec_cast(x, to)</code> defines the possible sets of casts. It returns <code>x</code> translated to have prototype <code>to</code>, or throws an error if the conversion isn’t possible. The set of possible casts is a superset of possible coercions because they’re requested explicitly.</p></li> </ul> <div id="double-dispatch" class="section level3"> <h3>Double dispatch</h3> <p>Both generics use <a href="https://en.wikipedia.org/wiki/Double_dispatch"><strong>double dispatch</strong></a> which means that the implementation is selected based on the class of two arguments, not just one. S3 does not natively support double dispatch, so we implement our own dispatch mechanism. In practice, this means:</p> <ul> <li><p>You end up with method names with two classes, like <code>vec_ptype2.foo.bar()</code>.</p></li> <li><p>You don’t need to implement default methods (they would never be called if you do).</p></li> <li><p>You can’t call <code>NextMethod()</code>.</p></li> </ul> </div> <div id="percent" class="section level3"> <h3>Percent class</h3> <p>We’ll make our percent class coercible back and forth with double vectors.</p> <p><code>vec_ptype2()</code> provides a user friendly error message if the coercion doesn’t exist and makes sure <code>NA</code> is handled in a standard way. <code>NA</code> is technically a logical vector, but we want to stand in for a missing value of any type.</p> <div class="sourceCode" id="cb10"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb10-1"><a href="#cb10-1" tabindex="-1"></a><span class="fu">vec_ptype2</span>(<span class="st">"bogus"</span>, <span class="fu">percent</span>())</span> <span id="cb10-2"><a href="#cb10-2" tabindex="-1"></a><span class="co">#> Error:</span></span> <span id="cb10-3"><a href="#cb10-3" tabindex="-1"></a><span class="co">#> ! Can't combine `"bogus"` <character> and `percent()` <vctrs_percent>.</span></span> <span id="cb10-4"><a href="#cb10-4" tabindex="-1"></a><span class="fu">vec_ptype2</span>(<span class="fu">percent</span>(), <span class="cn">NA</span>)</span> <span id="cb10-5"><a href="#cb10-5" tabindex="-1"></a><span class="co">#> <vctrs_percent[0]></span></span> <span id="cb10-6"><a href="#cb10-6" tabindex="-1"></a><span class="fu">vec_ptype2</span>(<span class="cn">NA</span>, <span class="fu">percent</span>())</span> <span id="cb10-7"><a href="#cb10-7" tabindex="-1"></a><span class="co">#> <vctrs_percent[0]></span></span></code></pre></div> <p>By default and in simple cases, an object of the same class is compatible with itself:</p> <div class="sourceCode" id="cb11"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb11-1"><a href="#cb11-1" tabindex="-1"></a><span class="fu">vec_ptype2</span>(<span class="fu">percent</span>(), <span class="fu">percent</span>())</span> <span id="cb11-2"><a href="#cb11-2" tabindex="-1"></a><span class="co">#> <vctrs_percent[0]></span></span></code></pre></div> <p>However this only works if the attributes for both objects are the same. Also the default methods are a bit slower. It is always a good idea to provide an explicit coercion method for the case of identical classes. So we’ll start by saying that a <code>vctrs_percent</code> combined with a <code>vctrs_percent</code> yields a <code>vctrs_percent</code>, which we indicate by returning a prototype generated by the constructor.</p> <div class="sourceCode" id="cb12"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb12-1"><a href="#cb12-1" tabindex="-1"></a>vec_ptype2.vctrs_percent.vctrs_percent <span class="ot"><-</span> <span class="cf">function</span>(x, y, ...) <span class="fu">new_percent</span>()</span></code></pre></div> <p>Next we define methods that say that combining a <code>percent</code> and double should yield a <code>double</code>. We avoid returning a <code>percent</code> here because errors in the scale (1 vs. 0.01) are more obvious with raw numbers.</p> <p>Because double dispatch is a bit of a hack, we need to provide two methods. It’s your responsibility to ensure that each member of the pair returns the same result: if they don’t you will get weird and unpredictable behaviour.</p> <p>The double dispatch mechanism requires us to refer to the underlying type, <code>double</code>, in the method name. If we implemented <code>vec_ptype2.vctrs_percent.numeric()</code>, it would never be called.</p> <div class="sourceCode" id="cb13"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb13-1"><a href="#cb13-1" tabindex="-1"></a>vec_ptype2.vctrs_percent.double <span class="ot"><-</span> <span class="cf">function</span>(x, y, ...) <span class="fu">double</span>()</span> <span id="cb13-2"><a href="#cb13-2" tabindex="-1"></a>vec_ptype2.double.vctrs_percent <span class="ot"><-</span> <span class="cf">function</span>(x, y, ...) <span class="fu">double</span>()</span></code></pre></div> <p>We can check that we’ve implemented this correctly with <code>vec_ptype_show()</code>:</p> <div class="sourceCode" id="cb14"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb14-1"><a href="#cb14-1" tabindex="-1"></a><span class="fu">vec_ptype_show</span>(<span class="fu">percent</span>(), <span class="fu">double</span>(), <span class="fu">percent</span>())</span> <span id="cb14-2"><a href="#cb14-2" tabindex="-1"></a><span class="co">#> Prototype: <double></span></span> <span id="cb14-3"><a href="#cb14-3" tabindex="-1"></a><span class="co">#> 0. ( , <vctrs_percent> ) = <vctrs_percent></span></span> <span id="cb14-4"><a href="#cb14-4" tabindex="-1"></a><span class="co">#> 1. ( <vctrs_percent> , <double> ) = <double> </span></span> <span id="cb14-5"><a href="#cb14-5" tabindex="-1"></a><span class="co">#> 2. ( <double> , <vctrs_percent> ) = <double></span></span></code></pre></div> <p>The <code>vec_ptype2()</code> methods define which input is the richer type that vctrs should coerce to. However, they don’t perform any conversion. This is the job of <code>vec_cast()</code>, which we implement next. We’ll provide a method to cast a percent to a percent:</p> <div class="sourceCode" id="cb15"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb15-1"><a href="#cb15-1" tabindex="-1"></a>vec_cast.vctrs_percent.vctrs_percent <span class="ot"><-</span> <span class="cf">function</span>(x, to, ...) x</span></code></pre></div> <p>And then for converting back and forth between doubles. To convert a double to a percent we use the <code>percent()</code> helper (not the constructor; this is unvalidated user input). To convert a <code>percent</code> to a double, we strip the attributes.</p> <p>Note that for historical reasons the order of argument in the signature is the opposite as for <code>vec_ptype2()</code>. The class for <code>to</code> comes first, and the class for <code>x</code> comes second.</p> <p>Again, the double dispatch mechanism requires us to refer to the underlying type, <code>double</code>, in the method name. Implementing <code>vec_cast.vctrs_percent.numeric()</code> has no effect.</p> <div class="sourceCode" id="cb16"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb16-1"><a href="#cb16-1" tabindex="-1"></a>vec_cast.vctrs_percent.double <span class="ot"><-</span> <span class="cf">function</span>(x, to, ...) <span class="fu">percent</span>(x)</span> <span id="cb16-2"><a href="#cb16-2" tabindex="-1"></a>vec_cast.double.vctrs_percent <span class="ot"><-</span> <span class="cf">function</span>(x, to, ...) <span class="fu">vec_data</span>(x)</span></code></pre></div> <p>Then we can check this works with <code>vec_cast()</code>:</p> <div class="sourceCode" id="cb17"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb17-1"><a href="#cb17-1" tabindex="-1"></a><span class="fu">vec_cast</span>(<span class="fl">0.5</span>, <span class="fu">percent</span>())</span> <span id="cb17-2"><a href="#cb17-2" tabindex="-1"></a><span class="co">#> <vctrs_percent[1]></span></span> <span id="cb17-3"><a href="#cb17-3" tabindex="-1"></a><span class="co">#> [1] 50%</span></span> <span id="cb17-4"><a href="#cb17-4" tabindex="-1"></a><span class="fu">vec_cast</span>(<span class="fu">percent</span>(<span class="fl">0.5</span>), <span class="fu">double</span>())</span> <span id="cb17-5"><a href="#cb17-5" tabindex="-1"></a><span class="co">#> [1] 0.5</span></span></code></pre></div> <p>Once you’ve implemented <code>vec_ptype2()</code> and <code>vec_cast()</code>, you get <code>vec_c()</code>, <code>[<-</code>, and <code>[[<-</code> implementations for free.</p> <div class="sourceCode" id="cb18"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb18-1"><a href="#cb18-1" tabindex="-1"></a><span class="fu">vec_c</span>(<span class="fu">percent</span>(<span class="fl">0.5</span>), <span class="dv">1</span>)</span> <span id="cb18-2"><a href="#cb18-2" tabindex="-1"></a><span class="co">#> [1] 0.5 1.0</span></span> <span id="cb18-3"><a href="#cb18-3" tabindex="-1"></a><span class="fu">vec_c</span>(<span class="cn">NA</span>, <span class="fu">percent</span>(<span class="fl">0.5</span>))</span> <span id="cb18-4"><a href="#cb18-4" tabindex="-1"></a><span class="co">#> <vctrs_percent[2]></span></span> <span id="cb18-5"><a href="#cb18-5" tabindex="-1"></a><span class="co">#> [1] <NA> 50%</span></span> <span id="cb18-6"><a href="#cb18-6" tabindex="-1"></a><span class="co"># but</span></span> <span id="cb18-7"><a href="#cb18-7" tabindex="-1"></a><span class="fu">vec_c</span>(<span class="cn">TRUE</span>, <span class="fu">percent</span>(<span class="fl">0.5</span>))</span> <span id="cb18-8"><a href="#cb18-8" tabindex="-1"></a><span class="co">#> Error in `vec_c()`:</span></span> <span id="cb18-9"><a href="#cb18-9" tabindex="-1"></a><span class="co">#> ! Can't combine `..1` <logical> and `..2` <vctrs_percent>.</span></span> <span id="cb18-10"><a href="#cb18-10" tabindex="-1"></a></span> <span id="cb18-11"><a href="#cb18-11" tabindex="-1"></a>x <span class="ot"><-</span> <span class="fu">percent</span>(<span class="fu">c</span>(<span class="fl">0.5</span>, <span class="dv">1</span>, <span class="dv">2</span>))</span> <span id="cb18-12"><a href="#cb18-12" tabindex="-1"></a>x[<span class="dv">1</span><span class="sc">:</span><span class="dv">2</span>] <span class="ot"><-</span> <span class="dv">2</span><span class="sc">:</span><span class="dv">1</span></span> <span id="cb18-13"><a href="#cb18-13" tabindex="-1"></a><span class="co">#> Error in `vec_restore_dispatch()`:</span></span> <span id="cb18-14"><a href="#cb18-14" tabindex="-1"></a><span class="co">#> ! Can't convert <integer> to <vctrs_percent>.</span></span> <span id="cb18-15"><a href="#cb18-15" tabindex="-1"></a>x[[<span class="dv">3</span>]] <span class="ot"><-</span> <span class="fl">0.5</span></span> <span id="cb18-16"><a href="#cb18-16" tabindex="-1"></a>x</span> <span id="cb18-17"><a href="#cb18-17" tabindex="-1"></a><span class="co">#> <vctrs_percent[3]></span></span> <span id="cb18-18"><a href="#cb18-18" tabindex="-1"></a><span class="co">#> [1] 50% 100% 50%</span></span></code></pre></div> <p>You’ll also get mostly correct behaviour for <code>c()</code>. The exception is when you use <code>c()</code> with a base R class:</p> <div class="sourceCode" id="cb19"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb19-1"><a href="#cb19-1" tabindex="-1"></a><span class="co"># Correct</span></span> <span id="cb19-2"><a href="#cb19-2" tabindex="-1"></a><span class="fu">c</span>(<span class="fu">percent</span>(<span class="fl">0.5</span>), <span class="dv">1</span>)</span> <span id="cb19-3"><a href="#cb19-3" tabindex="-1"></a><span class="co">#> [1] 0.5 1.0</span></span> <span id="cb19-4"><a href="#cb19-4" tabindex="-1"></a><span class="fu">c</span>(<span class="fu">percent</span>(<span class="fl">0.5</span>), <span class="fu">factor</span>(<span class="dv">1</span>))</span> <span id="cb19-5"><a href="#cb19-5" tabindex="-1"></a><span class="co">#> Error in `vec_c()`:</span></span> <span id="cb19-6"><a href="#cb19-6" tabindex="-1"></a><span class="co">#> ! Can't combine `..1` <vctrs_percent> and `..2` <factor<25c7e>>.</span></span> <span id="cb19-7"><a href="#cb19-7" tabindex="-1"></a></span> <span id="cb19-8"><a href="#cb19-8" tabindex="-1"></a><span class="co"># Incorrect</span></span> <span id="cb19-9"><a href="#cb19-9" tabindex="-1"></a><span class="fu">c</span>(<span class="fu">factor</span>(<span class="dv">1</span>), <span class="fu">percent</span>(<span class="fl">0.5</span>))</span> <span id="cb19-10"><a href="#cb19-10" tabindex="-1"></a><span class="co">#> [1] 1.0 0.5</span></span></code></pre></div> <p>Unfortunately there’s no way to fix this problem with the current design of <code>c()</code>.</p> <p>Again, as a convenience, consider providing an <code>as_percent()</code> function that makes use of the casts defined in your <code>vec_cast.vctrs_percent()</code> methods:</p> <div class="sourceCode" id="cb20"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb20-1"><a href="#cb20-1" tabindex="-1"></a>as_percent <span class="ot"><-</span> <span class="cf">function</span>(x) {</span> <span id="cb20-2"><a href="#cb20-2" tabindex="-1"></a> <span class="fu">vec_cast</span>(x, <span class="fu">new_percent</span>())</span> <span id="cb20-3"><a href="#cb20-3" tabindex="-1"></a>}</span></code></pre></div> <p>Occasionally, it is useful to provide conversions that go beyond what’s allowed in casting. For example, we could offer a parsing method for character vectors. In this case, <code>as_percent()</code> should be generic, the default method should cast, and then additional methods should implement more flexible conversion:</p> <div class="sourceCode" id="cb21"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb21-1"><a href="#cb21-1" tabindex="-1"></a>as_percent <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb21-2"><a href="#cb21-2" tabindex="-1"></a> <span class="fu">UseMethod</span>(<span class="st">"as_percent"</span>)</span> <span id="cb21-3"><a href="#cb21-3" tabindex="-1"></a>}</span> <span id="cb21-4"><a href="#cb21-4" tabindex="-1"></a></span> <span id="cb21-5"><a href="#cb21-5" tabindex="-1"></a>as_percent.default <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb21-6"><a href="#cb21-6" tabindex="-1"></a> <span class="fu">vec_cast</span>(x, <span class="fu">new_percent</span>())</span> <span id="cb21-7"><a href="#cb21-7" tabindex="-1"></a>}</span> <span id="cb21-8"><a href="#cb21-8" tabindex="-1"></a></span> <span id="cb21-9"><a href="#cb21-9" tabindex="-1"></a>as_percent.character <span class="ot"><-</span> <span class="cf">function</span>(x) {</span> <span id="cb21-10"><a href="#cb21-10" tabindex="-1"></a> value <span class="ot"><-</span> <span class="fu">as.numeric</span>(<span class="fu">gsub</span>(<span class="st">" *% *$"</span>, <span class="st">""</span>, x)) <span class="sc">/</span> <span class="dv">100</span></span> <span id="cb21-11"><a href="#cb21-11" tabindex="-1"></a> <span class="fu">new_percent</span>(value)</span> <span id="cb21-12"><a href="#cb21-12" tabindex="-1"></a>}</span></code></pre></div> </div> <div id="decimal-class" class="section level3"> <h3>Decimal class</h3> <p>Now that you’ve seen the basics with a very simple S3 class, we’ll gradually explore more complicated scenarios. This section creates a <code>decimal</code> class that prints with the specified number of decimal places. This is very similar to <code>percent</code> but now the class needs an attribute: the number of decimal places to display (an integer vector of length 1).</p> <p>We start off as before, defining a low-level constructor, a user-friendly constructor, a <code>format()</code> method, and a <code>vec_ptype_abbr()</code>. Note that additional object attributes are simply passed along to <code>new_vctr()</code>:</p> <div class="sourceCode" id="cb22"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb22-1"><a href="#cb22-1" tabindex="-1"></a>new_decimal <span class="ot"><-</span> <span class="cf">function</span>(<span class="at">x =</span> <span class="fu">double</span>(), <span class="at">digits =</span> <span class="dv">2</span><span class="dt">L</span>) {</span> <span id="cb22-2"><a href="#cb22-2" tabindex="-1"></a> <span class="cf">if</span> (<span class="sc">!</span><span class="fu">is_double</span>(x)) {</span> <span id="cb22-3"><a href="#cb22-3" tabindex="-1"></a> <span class="fu">abort</span>(<span class="st">"`x` must be a double vector."</span>)</span> <span id="cb22-4"><a href="#cb22-4" tabindex="-1"></a> }</span> <span id="cb22-5"><a href="#cb22-5" tabindex="-1"></a> <span class="cf">if</span> (<span class="sc">!</span><span class="fu">is_integer</span>(digits)) {</span> <span id="cb22-6"><a href="#cb22-6" tabindex="-1"></a> <span class="fu">abort</span>(<span class="st">"`digits` must be an integer vector."</span>)</span> <span id="cb22-7"><a href="#cb22-7" tabindex="-1"></a> }</span> <span id="cb22-8"><a href="#cb22-8" tabindex="-1"></a> <span class="fu">vec_check_size</span>(digits, <span class="at">size =</span> <span class="dv">1</span><span class="dt">L</span>)</span> <span id="cb22-9"><a href="#cb22-9" tabindex="-1"></a></span> <span id="cb22-10"><a href="#cb22-10" tabindex="-1"></a> <span class="fu">new_vctr</span>(x, <span class="at">digits =</span> digits, <span class="at">class =</span> <span class="st">"vctrs_decimal"</span>)</span> <span id="cb22-11"><a href="#cb22-11" tabindex="-1"></a>}</span> <span id="cb22-12"><a href="#cb22-12" tabindex="-1"></a></span> <span id="cb22-13"><a href="#cb22-13" tabindex="-1"></a>decimal <span class="ot"><-</span> <span class="cf">function</span>(<span class="at">x =</span> <span class="fu">double</span>(), <span class="at">digits =</span> <span class="dv">2</span><span class="dt">L</span>) {</span> <span id="cb22-14"><a href="#cb22-14" tabindex="-1"></a> x <span class="ot"><-</span> <span class="fu">vec_cast</span>(x, <span class="fu">double</span>())</span> <span id="cb22-15"><a href="#cb22-15" tabindex="-1"></a> digits <span class="ot"><-</span> <span class="fu">vec_recycle</span>(<span class="fu">vec_cast</span>(digits, <span class="fu">integer</span>()), <span class="dv">1</span><span class="dt">L</span>)</span> <span id="cb22-16"><a href="#cb22-16" tabindex="-1"></a></span> <span id="cb22-17"><a href="#cb22-17" tabindex="-1"></a> <span class="fu">new_decimal</span>(x, <span class="at">digits =</span> digits)</span> <span id="cb22-18"><a href="#cb22-18" tabindex="-1"></a>}</span> <span id="cb22-19"><a href="#cb22-19" tabindex="-1"></a></span> <span id="cb22-20"><a href="#cb22-20" tabindex="-1"></a>digits <span class="ot"><-</span> <span class="cf">function</span>(x) <span class="fu">attr</span>(x, <span class="st">"digits"</span>)</span> <span id="cb22-21"><a href="#cb22-21" tabindex="-1"></a></span> <span id="cb22-22"><a href="#cb22-22" tabindex="-1"></a>format.vctrs_decimal <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb22-23"><a href="#cb22-23" tabindex="-1"></a> <span class="fu">sprintf</span>(<span class="fu">paste0</span>(<span class="st">"%-0."</span>, <span class="fu">digits</span>(x), <span class="st">"f"</span>), x)</span> <span id="cb22-24"><a href="#cb22-24" tabindex="-1"></a>}</span> <span id="cb22-25"><a href="#cb22-25" tabindex="-1"></a></span> <span id="cb22-26"><a href="#cb22-26" tabindex="-1"></a>vec_ptype_abbr.vctrs_decimal <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb22-27"><a href="#cb22-27" tabindex="-1"></a> <span class="st">"dec"</span></span> <span id="cb22-28"><a href="#cb22-28" tabindex="-1"></a>}</span> <span id="cb22-29"><a href="#cb22-29" tabindex="-1"></a></span> <span id="cb22-30"><a href="#cb22-30" tabindex="-1"></a>x <span class="ot"><-</span> <span class="fu">decimal</span>(<span class="fu">runif</span>(<span class="dv">10</span>), <span class="dv">1</span><span class="dt">L</span>)</span> <span id="cb22-31"><a href="#cb22-31" tabindex="-1"></a>x</span> <span id="cb22-32"><a href="#cb22-32" tabindex="-1"></a><span class="co">#> <vctrs_decimal[10]></span></span> <span id="cb22-33"><a href="#cb22-33" tabindex="-1"></a><span class="co">#> [1] 0.1 0.8 0.6 0.2 0.0 0.5 0.5 0.3 0.7 0.8</span></span></code></pre></div> <p>Note that I provide a little helper to extract the <code>digits</code> attribute. This makes the code a little easier to read and should not be exported.</p> <p>By default, vctrs assumes that attributes are independent of the data and so are automatically preserved. You’ll see what to do if the attributes are data dependent in the next section.</p> <div class="sourceCode" id="cb23"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb23-1"><a href="#cb23-1" tabindex="-1"></a>x[<span class="dv">1</span><span class="sc">:</span><span class="dv">2</span>]</span> <span id="cb23-2"><a href="#cb23-2" tabindex="-1"></a><span class="co">#> <vctrs_decimal[2]></span></span> <span id="cb23-3"><a href="#cb23-3" tabindex="-1"></a><span class="co">#> [1] 0.1 0.8</span></span> <span id="cb23-4"><a href="#cb23-4" tabindex="-1"></a>x[[<span class="dv">1</span>]]</span> <span id="cb23-5"><a href="#cb23-5" tabindex="-1"></a><span class="co">#> <vctrs_decimal[1]></span></span> <span id="cb23-6"><a href="#cb23-6" tabindex="-1"></a><span class="co">#> [1] 0.1</span></span></code></pre></div> <p>For the sake of exposition, we’ll assume that <code>digits</code> is an important attribute of the class and should be included in the full type:</p> <div class="sourceCode" id="cb24"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb24-1"><a href="#cb24-1" tabindex="-1"></a>vec_ptype_full.vctrs_decimal <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb24-2"><a href="#cb24-2" tabindex="-1"></a> <span class="fu">paste0</span>(<span class="st">"decimal<"</span>, <span class="fu">digits</span>(x), <span class="st">">"</span>)</span> <span id="cb24-3"><a href="#cb24-3" tabindex="-1"></a>}</span> <span id="cb24-4"><a href="#cb24-4" tabindex="-1"></a></span> <span id="cb24-5"><a href="#cb24-5" tabindex="-1"></a>x</span> <span id="cb24-6"><a href="#cb24-6" tabindex="-1"></a><span class="co">#> <decimal<1>[10]></span></span> <span id="cb24-7"><a href="#cb24-7" tabindex="-1"></a><span class="co">#> [1] 0.1 0.8 0.6 0.2 0.0 0.5 0.5 0.3 0.7 0.8</span></span></code></pre></div> <p>Now consider <code>vec_cast()</code> and <code>vec_ptype2()</code>. Casting and coercing from one decimal to another requires a little thought as the values of the <code>digits</code> attribute might be different, and we need some way to reconcile them. Here I’ve decided to chose the maximum of the two; other reasonable options are to take the value from the left-hand side or throw an error.</p> <div class="sourceCode" id="cb25"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb25-1"><a href="#cb25-1" tabindex="-1"></a>vec_ptype2.vctrs_decimal.vctrs_decimal <span class="ot"><-</span> <span class="cf">function</span>(x, y, ...) {</span> <span id="cb25-2"><a href="#cb25-2" tabindex="-1"></a> <span class="fu">new_decimal</span>(<span class="at">digits =</span> <span class="fu">max</span>(<span class="fu">digits</span>(x), <span class="fu">digits</span>(y)))</span> <span id="cb25-3"><a href="#cb25-3" tabindex="-1"></a>}</span> <span id="cb25-4"><a href="#cb25-4" tabindex="-1"></a>vec_cast.vctrs_decimal.vctrs_decimal <span class="ot"><-</span> <span class="cf">function</span>(x, to, ...) {</span> <span id="cb25-5"><a href="#cb25-5" tabindex="-1"></a> <span class="fu">new_decimal</span>(<span class="fu">vec_data</span>(x), <span class="at">digits =</span> <span class="fu">digits</span>(to))</span> <span id="cb25-6"><a href="#cb25-6" tabindex="-1"></a>}</span> <span id="cb25-7"><a href="#cb25-7" tabindex="-1"></a></span> <span id="cb25-8"><a href="#cb25-8" tabindex="-1"></a><span class="fu">vec_c</span>(<span class="fu">decimal</span>(<span class="dv">1</span><span class="sc">/</span><span class="dv">100</span>, <span class="at">digits =</span> <span class="dv">3</span>), <span class="fu">decimal</span>(<span class="dv">2</span><span class="sc">/</span><span class="dv">100</span>, <span class="at">digits =</span> <span class="dv">2</span>))</span> <span id="cb25-9"><a href="#cb25-9" tabindex="-1"></a><span class="co">#> <decimal<3>[2]></span></span> <span id="cb25-10"><a href="#cb25-10" tabindex="-1"></a><span class="co">#> [1] 0.010 0.020</span></span></code></pre></div> <p>Finally, I can implement coercion to and from other types, like doubles. When automatically coercing, I choose the richer type (i.e., the decimal).</p> <div class="sourceCode" id="cb26"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb26-1"><a href="#cb26-1" tabindex="-1"></a>vec_ptype2.vctrs_decimal.double <span class="ot"><-</span> <span class="cf">function</span>(x, y, ...) x</span> <span id="cb26-2"><a href="#cb26-2" tabindex="-1"></a>vec_ptype2.double.vctrs_decimal <span class="ot"><-</span> <span class="cf">function</span>(x, y, ...) y</span> <span id="cb26-3"><a href="#cb26-3" tabindex="-1"></a></span> <span id="cb26-4"><a href="#cb26-4" tabindex="-1"></a>vec_cast.vctrs_decimal.double <span class="ot"><-</span> <span class="cf">function</span>(x, to, ...) <span class="fu">new_decimal</span>(x, <span class="at">digits =</span> <span class="fu">digits</span>(to))</span> <span id="cb26-5"><a href="#cb26-5" tabindex="-1"></a>vec_cast.double.vctrs_decimal <span class="ot"><-</span> <span class="cf">function</span>(x, to, ...) <span class="fu">vec_data</span>(x)</span> <span id="cb26-6"><a href="#cb26-6" tabindex="-1"></a></span> <span id="cb26-7"><a href="#cb26-7" tabindex="-1"></a><span class="fu">vec_c</span>(<span class="fu">decimal</span>(<span class="dv">1</span>, <span class="at">digits =</span> <span class="dv">1</span>), pi)</span> <span id="cb26-8"><a href="#cb26-8" tabindex="-1"></a><span class="co">#> <decimal<1>[2]></span></span> <span id="cb26-9"><a href="#cb26-9" tabindex="-1"></a><span class="co">#> [1] 1.0 3.1</span></span> <span id="cb26-10"><a href="#cb26-10" tabindex="-1"></a><span class="fu">vec_c</span>(pi, <span class="fu">decimal</span>(<span class="dv">1</span>, <span class="at">digits =</span> <span class="dv">1</span>))</span> <span id="cb26-11"><a href="#cb26-11" tabindex="-1"></a><span class="co">#> <decimal<1>[2]></span></span> <span id="cb26-12"><a href="#cb26-12" tabindex="-1"></a><span class="co">#> [1] 3.1 1.0</span></span></code></pre></div> <p>If type <code>x</code> has greater resolution than <code>y</code>, there will be some inputs that lose precision. These should generate errors using <code>stop_lossy_cast()</code>. You can see that in action when casting from doubles to integers; only some doubles can become integers without losing resolution.</p> <div class="sourceCode" id="cb27"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb27-1"><a href="#cb27-1" tabindex="-1"></a><span class="fu">vec_cast</span>(<span class="fu">c</span>(<span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">10</span>), <span class="at">to =</span> <span class="fu">integer</span>())</span> <span id="cb27-2"><a href="#cb27-2" tabindex="-1"></a><span class="co">#> [1] 1 2 10</span></span> <span id="cb27-3"><a href="#cb27-3" tabindex="-1"></a></span> <span id="cb27-4"><a href="#cb27-4" tabindex="-1"></a><span class="fu">vec_cast</span>(<span class="fu">c</span>(<span class="fl">1.5</span>, <span class="dv">2</span>, <span class="fl">10.5</span>), <span class="at">to =</span> <span class="fu">integer</span>())</span> <span id="cb27-5"><a href="#cb27-5" tabindex="-1"></a><span class="co">#> Error:</span></span> <span id="cb27-6"><a href="#cb27-6" tabindex="-1"></a><span class="co">#> ! Can't convert from `c(1.5, 2, 10.5)` <double> to <integer> due to loss of precision.</span></span> <span id="cb27-7"><a href="#cb27-7" tabindex="-1"></a><span class="co">#> • Locations: 1, 3</span></span></code></pre></div> </div> <div id="cached-sum" class="section level3"> <h3>Cached sum class</h3> <p>The next level up in complexity is an object that has data-dependent attributes. To explore this idea we’ll create a vector that caches the sum of its values. As usual, we start with low-level and user-friendly constructors:</p> <div class="sourceCode" id="cb28"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb28-1"><a href="#cb28-1" tabindex="-1"></a>new_cached_sum <span class="ot"><-</span> <span class="cf">function</span>(<span class="at">x =</span> <span class="fu">double</span>(), <span class="at">sum =</span> <span class="dv">0</span><span class="dt">L</span>) {</span> <span id="cb28-2"><a href="#cb28-2" tabindex="-1"></a> <span class="cf">if</span> (<span class="sc">!</span><span class="fu">is_double</span>(x)) {</span> <span id="cb28-3"><a href="#cb28-3" tabindex="-1"></a> <span class="fu">abort</span>(<span class="st">"`x` must be a double vector."</span>)</span> <span id="cb28-4"><a href="#cb28-4" tabindex="-1"></a> }</span> <span id="cb28-5"><a href="#cb28-5" tabindex="-1"></a> <span class="cf">if</span> (<span class="sc">!</span><span class="fu">is_double</span>(sum)) {</span> <span id="cb28-6"><a href="#cb28-6" tabindex="-1"></a> <span class="fu">abort</span>(<span class="st">"`sum` must be a double vector."</span>)</span> <span id="cb28-7"><a href="#cb28-7" tabindex="-1"></a> }</span> <span id="cb28-8"><a href="#cb28-8" tabindex="-1"></a> <span class="fu">vec_check_size</span>(sum, <span class="at">size =</span> <span class="dv">1</span><span class="dt">L</span>)</span> <span id="cb28-9"><a href="#cb28-9" tabindex="-1"></a></span> <span id="cb28-10"><a href="#cb28-10" tabindex="-1"></a> <span class="fu">new_vctr</span>(x, <span class="at">sum =</span> sum, <span class="at">class =</span> <span class="st">"vctrs_cached_sum"</span>)</span> <span id="cb28-11"><a href="#cb28-11" tabindex="-1"></a>}</span> <span id="cb28-12"><a href="#cb28-12" tabindex="-1"></a></span> <span id="cb28-13"><a href="#cb28-13" tabindex="-1"></a>cached_sum <span class="ot"><-</span> <span class="cf">function</span>(x) {</span> <span id="cb28-14"><a href="#cb28-14" tabindex="-1"></a> x <span class="ot"><-</span> <span class="fu">vec_cast</span>(x, <span class="fu">double</span>())</span> <span id="cb28-15"><a href="#cb28-15" tabindex="-1"></a> <span class="fu">new_cached_sum</span>(x, <span class="fu">sum</span>(x))</span> <span id="cb28-16"><a href="#cb28-16" tabindex="-1"></a>}</span></code></pre></div> <p>For this class, we can use the default <code>format()</code> method, and instead, we’ll customise the <code>obj_print_footer()</code> method. This is a good place to display user facing attributes.</p> <div class="sourceCode" id="cb29"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb29-1"><a href="#cb29-1" tabindex="-1"></a>obj_print_footer.vctrs_cached_sum <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb29-2"><a href="#cb29-2" tabindex="-1"></a> <span class="fu">cat</span>(<span class="st">"# Sum: "</span>, <span class="fu">format</span>(<span class="fu">attr</span>(x, <span class="st">"sum"</span>), <span class="at">digits =</span> <span class="dv">3</span>), <span class="st">"</span><span class="sc">\n</span><span class="st">"</span>, <span class="at">sep =</span> <span class="st">""</span>)</span> <span id="cb29-3"><a href="#cb29-3" tabindex="-1"></a>}</span> <span id="cb29-4"><a href="#cb29-4" tabindex="-1"></a></span> <span id="cb29-5"><a href="#cb29-5" tabindex="-1"></a>x <span class="ot"><-</span> <span class="fu">cached_sum</span>(<span class="fu">runif</span>(<span class="dv">10</span>))</span> <span id="cb29-6"><a href="#cb29-6" tabindex="-1"></a>x</span> <span id="cb29-7"><a href="#cb29-7" tabindex="-1"></a><span class="co">#> <vctrs_cached_sum[10]></span></span> <span id="cb29-8"><a href="#cb29-8" tabindex="-1"></a><span class="co">#> [1] 0.87460066 0.17494063 0.03424133 0.32038573 0.40232824 0.19566983</span></span> <span id="cb29-9"><a href="#cb29-9" tabindex="-1"></a><span class="co">#> [7] 0.40353812 0.06366146 0.38870131 0.97554784</span></span> <span id="cb29-10"><a href="#cb29-10" tabindex="-1"></a><span class="co">#> # Sum: 3.83</span></span></code></pre></div> <p>We’ll also override <code>sum()</code> and <code>mean()</code> to use the attribute. This is easiest to do with <code>vec_math()</code>, which you’ll learn about later.</p> <div class="sourceCode" id="cb30"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb30-1"><a href="#cb30-1" tabindex="-1"></a>vec_math.vctrs_cached_sum <span class="ot"><-</span> <span class="cf">function</span>(.fn, .x, ...) {</span> <span id="cb30-2"><a href="#cb30-2" tabindex="-1"></a> <span class="fu">cat</span>(<span class="st">"Using cache</span><span class="sc">\n</span><span class="st">"</span>)</span> <span id="cb30-3"><a href="#cb30-3" tabindex="-1"></a> <span class="cf">switch</span>(.fn,</span> <span id="cb30-4"><a href="#cb30-4" tabindex="-1"></a> <span class="at">sum =</span> <span class="fu">attr</span>(.x, <span class="st">"sum"</span>),</span> <span id="cb30-5"><a href="#cb30-5" tabindex="-1"></a> <span class="at">mean =</span> <span class="fu">attr</span>(.x, <span class="st">"sum"</span>) <span class="sc">/</span> <span class="fu">length</span>(.x),</span> <span id="cb30-6"><a href="#cb30-6" tabindex="-1"></a> <span class="fu">vec_math_base</span>(.fn, .x, ...)</span> <span id="cb30-7"><a href="#cb30-7" tabindex="-1"></a> )</span> <span id="cb30-8"><a href="#cb30-8" tabindex="-1"></a>}</span> <span id="cb30-9"><a href="#cb30-9" tabindex="-1"></a></span> <span id="cb30-10"><a href="#cb30-10" tabindex="-1"></a><span class="fu">sum</span>(x)</span> <span id="cb30-11"><a href="#cb30-11" tabindex="-1"></a><span class="co">#> Using cache</span></span> <span id="cb30-12"><a href="#cb30-12" tabindex="-1"></a><span class="co">#> [1] 3.833615</span></span></code></pre></div> <p>As mentioned above, vctrs assumes that attributes are independent of the data. This means that when we take advantage of the default methods, they’ll work, but return the incorrect result:</p> <div class="sourceCode" id="cb31"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb31-1"><a href="#cb31-1" tabindex="-1"></a>x[<span class="dv">1</span><span class="sc">:</span><span class="dv">2</span>]</span> <span id="cb31-2"><a href="#cb31-2" tabindex="-1"></a><span class="co">#> <vctrs_cached_sum[2]></span></span> <span id="cb31-3"><a href="#cb31-3" tabindex="-1"></a><span class="co">#> [1] 0.8746007 0.1749406</span></span> <span id="cb31-4"><a href="#cb31-4" tabindex="-1"></a><span class="co">#> # Sum: 3.83</span></span></code></pre></div> <p>To fix this, you need to provide a <code>vec_restore()</code> method. Note that this method dispatches on the <code>to</code> argument.</p> <div class="sourceCode" id="cb32"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb32-1"><a href="#cb32-1" tabindex="-1"></a>vec_restore.vctrs_cached_sum <span class="ot"><-</span> <span class="cf">function</span>(x, to, ..., <span class="at">i =</span> <span class="cn">NULL</span>) {</span> <span id="cb32-2"><a href="#cb32-2" tabindex="-1"></a> <span class="fu">new_cached_sum</span>(x, <span class="fu">sum</span>(x))</span> <span id="cb32-3"><a href="#cb32-3" tabindex="-1"></a>}</span> <span id="cb32-4"><a href="#cb32-4" tabindex="-1"></a></span> <span id="cb32-5"><a href="#cb32-5" tabindex="-1"></a>x[<span class="dv">1</span>]</span> <span id="cb32-6"><a href="#cb32-6" tabindex="-1"></a><span class="co">#> <vctrs_cached_sum[1]></span></span> <span id="cb32-7"><a href="#cb32-7" tabindex="-1"></a><span class="co">#> [1] 0.8746007</span></span> <span id="cb32-8"><a href="#cb32-8" tabindex="-1"></a><span class="co">#> # Sum: 0.875</span></span></code></pre></div> <p>This works because most of the vctrs methods dispatch to the underlying base function by first stripping off extra attributes with <code>vec_data()</code> and then reapplying them again with <code>vec_restore()</code>. The default <code>vec_restore()</code> method copies over all attributes, which is not appropriate when the attributes depend on the data.</p> <p>Note that <code>vec_restore.class</code> is subtly different from <code>vec_cast.class.class()</code>. <code>vec_restore()</code> is used when restoring attributes that have been lost; <code>vec_cast()</code> is used for coercions. This is easier to understand with a concrete example. Imagine factors were implemented with <code>new_vctr()</code>. <code>vec_restore.factor()</code> would restore attributes back to an integer vector, but you would not want to allow manually casting an integer to a factor with <code>vec_cast()</code>.</p> </div> </div> <div id="record-style-objects" class="section level2"> <h2>Record-style objects</h2> <p>Record-style objects use a list of equal-length vectors to represent individual components of the object. The best example of this is <code>POSIXlt</code>, which underneath the hood is a list of 11 fields like year, month, and day. Record-style classes override <code>length()</code> and subsetting methods to conceal this implementation detail.</p> <div class="sourceCode" id="cb33"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb33-1"><a href="#cb33-1" tabindex="-1"></a>x <span class="ot"><-</span> <span class="fu">as.POSIXlt</span>(<span class="fu">ISOdatetime</span>(<span class="dv">2020</span>, <span class="dv">1</span>, <span class="dv">1</span>, <span class="dv">0</span>, <span class="dv">0</span>, <span class="dv">1</span><span class="sc">:</span><span class="dv">3</span>))</span> <span id="cb33-2"><a href="#cb33-2" tabindex="-1"></a>x</span> <span id="cb33-3"><a href="#cb33-3" tabindex="-1"></a><span class="co">#> [1] "2020-01-01 00:00:01 EST" "2020-01-01 00:00:02 EST"</span></span> <span id="cb33-4"><a href="#cb33-4" tabindex="-1"></a><span class="co">#> [3] "2020-01-01 00:00:03 EST"</span></span> <span id="cb33-5"><a href="#cb33-5" tabindex="-1"></a></span> <span id="cb33-6"><a href="#cb33-6" tabindex="-1"></a><span class="fu">length</span>(x)</span> <span id="cb33-7"><a href="#cb33-7" tabindex="-1"></a><span class="co">#> [1] 3</span></span> <span id="cb33-8"><a href="#cb33-8" tabindex="-1"></a><span class="fu">length</span>(<span class="fu">unclass</span>(x))</span> <span id="cb33-9"><a href="#cb33-9" tabindex="-1"></a><span class="co">#> [1] 11</span></span> <span id="cb33-10"><a href="#cb33-10" tabindex="-1"></a></span> <span id="cb33-11"><a href="#cb33-11" tabindex="-1"></a>x[[<span class="dv">1</span>]] <span class="co"># the first date time</span></span> <span id="cb33-12"><a href="#cb33-12" tabindex="-1"></a><span class="co">#> [1] "2020-01-01 00:00:01 EST"</span></span> <span id="cb33-13"><a href="#cb33-13" tabindex="-1"></a><span class="fu">unclass</span>(x)[[<span class="dv">1</span>]] <span class="co"># the first component, the number of seconds</span></span> <span id="cb33-14"><a href="#cb33-14" tabindex="-1"></a><span class="co">#> [1] 1 2 3</span></span></code></pre></div> <p>vctrs makes it easy to create new record-style classes using <code>new_rcrd()</code>, which has a wide selection of default methods.</p> <div id="rational-class" class="section level3"> <h3>Rational class</h3> <p>A fraction, or rational number, can be represented by a pair of integer vectors representing the numerator (the number on top) and the denominator (the number on bottom), where the length of each vector must be the same. To represent such a data structure we turn to a new base data type: the record (or rcrd for short).</p> <p>As usual we start with low-level and user-friendly constructors. The low-level constructor calls <code>new_rcrd()</code>, which needs a named list of equal-length vectors.</p> <div class="sourceCode" id="cb34"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb34-1"><a href="#cb34-1" tabindex="-1"></a>new_rational <span class="ot"><-</span> <span class="cf">function</span>(<span class="at">n =</span> <span class="fu">integer</span>(), <span class="at">d =</span> <span class="fu">integer</span>()) {</span> <span id="cb34-2"><a href="#cb34-2" tabindex="-1"></a> <span class="cf">if</span> (<span class="sc">!</span><span class="fu">is_integer</span>(n)) {</span> <span id="cb34-3"><a href="#cb34-3" tabindex="-1"></a> <span class="fu">abort</span>(<span class="st">"`n` must be an integer vector."</span>)</span> <span id="cb34-4"><a href="#cb34-4" tabindex="-1"></a> }</span> <span id="cb34-5"><a href="#cb34-5" tabindex="-1"></a> <span class="cf">if</span> (<span class="sc">!</span><span class="fu">is_integer</span>(d)) {</span> <span id="cb34-6"><a href="#cb34-6" tabindex="-1"></a> <span class="fu">abort</span>(<span class="st">"`d` must be an integer vector."</span>)</span> <span id="cb34-7"><a href="#cb34-7" tabindex="-1"></a> }</span> <span id="cb34-8"><a href="#cb34-8" tabindex="-1"></a></span> <span id="cb34-9"><a href="#cb34-9" tabindex="-1"></a> <span class="fu">new_rcrd</span>(<span class="fu">list</span>(<span class="at">n =</span> n, <span class="at">d =</span> d), <span class="at">class =</span> <span class="st">"vctrs_rational"</span>)</span> <span id="cb34-10"><a href="#cb34-10" tabindex="-1"></a>}</span></code></pre></div> <p>Our user friendly constructor casts <code>n</code> and <code>d</code> to integers and recycles them to the same length.</p> <div class="sourceCode" id="cb35"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb35-1"><a href="#cb35-1" tabindex="-1"></a>rational <span class="ot"><-</span> <span class="cf">function</span>(<span class="at">n =</span> <span class="fu">integer</span>(), <span class="at">d =</span> <span class="fu">integer</span>()) {</span> <span id="cb35-2"><a href="#cb35-2" tabindex="-1"></a> <span class="fu">c</span>(n, d) <span class="sc">%<-%</span> <span class="fu">vec_cast_common</span>(n, d, <span class="at">.to =</span> <span class="fu">integer</span>())</span> <span id="cb35-3"><a href="#cb35-3" tabindex="-1"></a> <span class="fu">c</span>(n, d) <span class="sc">%<-%</span> <span class="fu">vec_recycle_common</span>(n, d)</span> <span id="cb35-4"><a href="#cb35-4" tabindex="-1"></a></span> <span id="cb35-5"><a href="#cb35-5" tabindex="-1"></a> <span class="fu">new_rational</span>(n, d)</span> <span id="cb35-6"><a href="#cb35-6" tabindex="-1"></a>}</span> <span id="cb35-7"><a href="#cb35-7" tabindex="-1"></a></span> <span id="cb35-8"><a href="#cb35-8" tabindex="-1"></a>x <span class="ot"><-</span> <span class="fu">rational</span>(<span class="dv">1</span>, <span class="dv">1</span><span class="sc">:</span><span class="dv">10</span>)</span></code></pre></div> <p>Behind the scenes, <code>x</code> is a named list with two elements. But those details are hidden so that it behaves like a vector:</p> <div class="sourceCode" id="cb36"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb36-1"><a href="#cb36-1" tabindex="-1"></a><span class="fu">names</span>(x)</span> <span id="cb36-2"><a href="#cb36-2" tabindex="-1"></a><span class="co">#> NULL</span></span> <span id="cb36-3"><a href="#cb36-3" tabindex="-1"></a><span class="fu">length</span>(x)</span> <span id="cb36-4"><a href="#cb36-4" tabindex="-1"></a><span class="co">#> [1] 10</span></span></code></pre></div> <p>To access the underlying fields we need to use <code>field()</code> and <code>fields()</code>:</p> <div class="sourceCode" id="cb37"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb37-1"><a href="#cb37-1" tabindex="-1"></a><span class="fu">fields</span>(x)</span> <span id="cb37-2"><a href="#cb37-2" tabindex="-1"></a><span class="co">#> [1] "n" "d"</span></span> <span id="cb37-3"><a href="#cb37-3" tabindex="-1"></a><span class="fu">field</span>(x, <span class="st">"n"</span>)</span> <span id="cb37-4"><a href="#cb37-4" tabindex="-1"></a><span class="co">#> [1] 1 1 1 1 1 1 1 1 1 1</span></span></code></pre></div> <p>Notice that we can’t <code>print()</code> or <code>str()</code> the new rational vector <code>x</code> yet. Printing causes an error:</p> <div class="sourceCode" id="cb38"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb38-1"><a href="#cb38-1" tabindex="-1"></a>x</span> <span id="cb38-2"><a href="#cb38-2" tabindex="-1"></a><span class="co">#> <vctrs_rational[10]></span></span> <span id="cb38-3"><a href="#cb38-3" tabindex="-1"></a><span class="co">#> Error in `format()`:</span></span> <span id="cb38-4"><a href="#cb38-4" tabindex="-1"></a><span class="co">#> ! `format.vctrs_rational()` not implemented.</span></span> <span id="cb38-5"><a href="#cb38-5" tabindex="-1"></a></span> <span id="cb38-6"><a href="#cb38-6" tabindex="-1"></a><span class="fu">str</span>(x)</span> <span id="cb38-7"><a href="#cb38-7" tabindex="-1"></a><span class="co">#> Error in `format()`:</span></span> <span id="cb38-8"><a href="#cb38-8" tabindex="-1"></a><span class="co">#> ! `format.vctrs_rational()` not implemented.</span></span></code></pre></div> <p>This is because we haven’t defined how our class can be printed from the underlying data. Note that if you want to look under the hood during development, you can always call <code>vec_data(x)</code>.</p> <div class="sourceCode" id="cb39"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb39-1"><a href="#cb39-1" tabindex="-1"></a><span class="fu">vec_data</span>(x)</span> <span id="cb39-2"><a href="#cb39-2" tabindex="-1"></a><span class="co">#> n d</span></span> <span id="cb39-3"><a href="#cb39-3" tabindex="-1"></a><span class="co">#> 1 1 1</span></span> <span id="cb39-4"><a href="#cb39-4" tabindex="-1"></a><span class="co">#> 2 1 2</span></span> <span id="cb39-5"><a href="#cb39-5" tabindex="-1"></a><span class="co">#> 3 1 3</span></span> <span id="cb39-6"><a href="#cb39-6" tabindex="-1"></a><span class="co">#> 4 1 4</span></span> <span id="cb39-7"><a href="#cb39-7" tabindex="-1"></a><span class="co">#> 5 1 5</span></span> <span id="cb39-8"><a href="#cb39-8" tabindex="-1"></a><span class="co">#> 6 1 6</span></span> <span id="cb39-9"><a href="#cb39-9" tabindex="-1"></a><span class="co">#> 7 1 7</span></span> <span id="cb39-10"><a href="#cb39-10" tabindex="-1"></a><span class="co">#> 8 1 8</span></span> <span id="cb39-11"><a href="#cb39-11" tabindex="-1"></a><span class="co">#> 9 1 9</span></span> <span id="cb39-12"><a href="#cb39-12" tabindex="-1"></a><span class="co">#> 10 1 10</span></span> <span id="cb39-13"><a href="#cb39-13" tabindex="-1"></a></span> <span id="cb39-14"><a href="#cb39-14" tabindex="-1"></a><span class="fu">str</span>(<span class="fu">vec_data</span>(x))</span> <span id="cb39-15"><a href="#cb39-15" tabindex="-1"></a><span class="co">#> 'data.frame': 10 obs. of 2 variables:</span></span> <span id="cb39-16"><a href="#cb39-16" tabindex="-1"></a><span class="co">#> $ n: int 1 1 1 1 1 1 1 1 1 1</span></span> <span id="cb39-17"><a href="#cb39-17" tabindex="-1"></a><span class="co">#> $ d: int 1 2 3 4 5 6 7 8 9 10</span></span></code></pre></div> <p>It is generally best to define a formatting method early in the development of a class. The format method defines how to display the class so that it can be printed in the normal way:</p> <div class="sourceCode" id="cb40"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb40-1"><a href="#cb40-1" tabindex="-1"></a>format.vctrs_rational <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb40-2"><a href="#cb40-2" tabindex="-1"></a> n <span class="ot"><-</span> <span class="fu">field</span>(x, <span class="st">"n"</span>)</span> <span id="cb40-3"><a href="#cb40-3" tabindex="-1"></a> d <span class="ot"><-</span> <span class="fu">field</span>(x, <span class="st">"d"</span>)</span> <span id="cb40-4"><a href="#cb40-4" tabindex="-1"></a></span> <span id="cb40-5"><a href="#cb40-5" tabindex="-1"></a> out <span class="ot"><-</span> <span class="fu">paste0</span>(n, <span class="st">"/"</span>, d)</span> <span id="cb40-6"><a href="#cb40-6" tabindex="-1"></a> out[<span class="fu">is.na</span>(n) <span class="sc">|</span> <span class="fu">is.na</span>(d)] <span class="ot"><-</span> <span class="cn">NA</span></span> <span id="cb40-7"><a href="#cb40-7" tabindex="-1"></a></span> <span id="cb40-8"><a href="#cb40-8" tabindex="-1"></a> out</span> <span id="cb40-9"><a href="#cb40-9" tabindex="-1"></a>}</span> <span id="cb40-10"><a href="#cb40-10" tabindex="-1"></a></span> <span id="cb40-11"><a href="#cb40-11" tabindex="-1"></a>vec_ptype_abbr.vctrs_rational <span class="ot"><-</span> <span class="cf">function</span>(x, ...) <span class="st">"rtnl"</span></span> <span id="cb40-12"><a href="#cb40-12" tabindex="-1"></a>vec_ptype_full.vctrs_rational <span class="ot"><-</span> <span class="cf">function</span>(x, ...) <span class="st">"rational"</span></span> <span id="cb40-13"><a href="#cb40-13" tabindex="-1"></a></span> <span id="cb40-14"><a href="#cb40-14" tabindex="-1"></a>x</span> <span id="cb40-15"><a href="#cb40-15" tabindex="-1"></a><span class="co">#> <rational[10]></span></span> <span id="cb40-16"><a href="#cb40-16" tabindex="-1"></a><span class="co">#> [1] 1/1 1/2 1/3 1/4 1/5 1/6 1/7 1/8 1/9 1/10</span></span></code></pre></div> <p>vctrs uses the <code>format()</code> method in <code>str()</code>, hiding the underlying implementation details from the user:</p> <div class="sourceCode" id="cb41"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb41-1"><a href="#cb41-1" tabindex="-1"></a><span class="fu">str</span>(x)</span> <span id="cb41-2"><a href="#cb41-2" tabindex="-1"></a><span class="co">#> rtnl [1:10] 1/1, 1/2, 1/3, 1/4, 1/5, 1/6, 1/7, 1/8, 1/9, 1/10</span></span></code></pre></div> <p>For <code>rational</code>, <code>vec_ptype2()</code> and <code>vec_cast()</code> follow the same pattern as <code>percent()</code>. We allow coercion from integer and to doubles.</p> <div class="sourceCode" id="cb42"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb42-1"><a href="#cb42-1" tabindex="-1"></a>vec_ptype2.vctrs_rational.vctrs_rational <span class="ot"><-</span> <span class="cf">function</span>(x, y, ...) <span class="fu">new_rational</span>()</span> <span id="cb42-2"><a href="#cb42-2" tabindex="-1"></a>vec_ptype2.vctrs_rational.integer <span class="ot"><-</span> <span class="cf">function</span>(x, y, ...) <span class="fu">new_rational</span>()</span> <span id="cb42-3"><a href="#cb42-3" tabindex="-1"></a>vec_ptype2.integer.vctrs_rational <span class="ot"><-</span> <span class="cf">function</span>(x, y, ...) <span class="fu">new_rational</span>()</span> <span id="cb42-4"><a href="#cb42-4" tabindex="-1"></a></span> <span id="cb42-5"><a href="#cb42-5" tabindex="-1"></a>vec_cast.vctrs_rational.vctrs_rational <span class="ot"><-</span> <span class="cf">function</span>(x, to, ...) x</span> <span id="cb42-6"><a href="#cb42-6" tabindex="-1"></a>vec_cast.double.vctrs_rational <span class="ot"><-</span> <span class="cf">function</span>(x, to, ...) <span class="fu">field</span>(x, <span class="st">"n"</span>) <span class="sc">/</span> <span class="fu">field</span>(x, <span class="st">"d"</span>)</span> <span id="cb42-7"><a href="#cb42-7" tabindex="-1"></a>vec_cast.vctrs_rational.integer <span class="ot"><-</span> <span class="cf">function</span>(x, to, ...) <span class="fu">rational</span>(x, <span class="dv">1</span>)</span> <span id="cb42-8"><a href="#cb42-8" tabindex="-1"></a></span> <span id="cb42-9"><a href="#cb42-9" tabindex="-1"></a><span class="fu">vec_c</span>(<span class="fu">rational</span>(<span class="dv">1</span>, <span class="dv">2</span>), <span class="dv">1</span><span class="dt">L</span>, <span class="cn">NA</span>)</span> <span id="cb42-10"><a href="#cb42-10" tabindex="-1"></a><span class="co">#> <rational[3]></span></span> <span id="cb42-11"><a href="#cb42-11" tabindex="-1"></a><span class="co">#> [1] 1/2 1/1 <NA></span></span></code></pre></div> </div> <div id="decimal2-class" class="section level3"> <h3>Decimal2 class</h3> <p>The previous implementation of <code>decimal</code> was built on top of doubles. This is a bad idea because decimal vectors are typically used when you care about precise values (i.e., dollars and cents in a bank account), and double values suffer from floating point problems.</p> <p>A better implementation of a decimal class would be to use pair of integers, one for the value to the left of the decimal point, and the other for the value to the right (divided by a <code>scale</code>). The following code is a very quick sketch of how you might start creating such a class:</p> <div class="sourceCode" id="cb43"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb43-1"><a href="#cb43-1" tabindex="-1"></a>new_decimal2 <span class="ot"><-</span> <span class="cf">function</span>(l, r, <span class="at">scale =</span> <span class="dv">2</span><span class="dt">L</span>) {</span> <span id="cb43-2"><a href="#cb43-2" tabindex="-1"></a> <span class="cf">if</span> (<span class="sc">!</span><span class="fu">is_integer</span>(l)) {</span> <span id="cb43-3"><a href="#cb43-3" tabindex="-1"></a> <span class="fu">abort</span>(<span class="st">"`l` must be an integer vector."</span>)</span> <span id="cb43-4"><a href="#cb43-4" tabindex="-1"></a> }</span> <span id="cb43-5"><a href="#cb43-5" tabindex="-1"></a> <span class="cf">if</span> (<span class="sc">!</span><span class="fu">is_integer</span>(r)) {</span> <span id="cb43-6"><a href="#cb43-6" tabindex="-1"></a> <span class="fu">abort</span>(<span class="st">"`r` must be an integer vector."</span>)</span> <span id="cb43-7"><a href="#cb43-7" tabindex="-1"></a> }</span> <span id="cb43-8"><a href="#cb43-8" tabindex="-1"></a> <span class="cf">if</span> (<span class="sc">!</span><span class="fu">is_integer</span>(scale)) {</span> <span id="cb43-9"><a href="#cb43-9" tabindex="-1"></a> <span class="fu">abort</span>(<span class="st">"`scale` must be an integer vector."</span>)</span> <span id="cb43-10"><a href="#cb43-10" tabindex="-1"></a> }</span> <span id="cb43-11"><a href="#cb43-11" tabindex="-1"></a> <span class="fu">vec_check_size</span>(scale, <span class="at">size =</span> <span class="dv">1</span><span class="dt">L</span>)</span> <span id="cb43-12"><a href="#cb43-12" tabindex="-1"></a></span> <span id="cb43-13"><a href="#cb43-13" tabindex="-1"></a> <span class="fu">new_rcrd</span>(<span class="fu">list</span>(<span class="at">l =</span> l, <span class="at">r =</span> r), <span class="at">scale =</span> scale, <span class="at">class =</span> <span class="st">"vctrs_decimal2"</span>)</span> <span id="cb43-14"><a href="#cb43-14" tabindex="-1"></a>}</span> <span id="cb43-15"><a href="#cb43-15" tabindex="-1"></a></span> <span id="cb43-16"><a href="#cb43-16" tabindex="-1"></a>decimal2 <span class="ot"><-</span> <span class="cf">function</span>(l, r, <span class="at">scale =</span> <span class="dv">2</span><span class="dt">L</span>) {</span> <span id="cb43-17"><a href="#cb43-17" tabindex="-1"></a> l <span class="ot"><-</span> <span class="fu">vec_cast</span>(l, <span class="fu">integer</span>())</span> <span id="cb43-18"><a href="#cb43-18" tabindex="-1"></a> r <span class="ot"><-</span> <span class="fu">vec_cast</span>(r, <span class="fu">integer</span>())</span> <span id="cb43-19"><a href="#cb43-19" tabindex="-1"></a> <span class="fu">c</span>(l, r) <span class="sc">%<-%</span> <span class="fu">vec_recycle_common</span>(l, r)</span> <span id="cb43-20"><a href="#cb43-20" tabindex="-1"></a> scale <span class="ot"><-</span> <span class="fu">vec_cast</span>(scale, <span class="fu">integer</span>())</span> <span id="cb43-21"><a href="#cb43-21" tabindex="-1"></a></span> <span id="cb43-22"><a href="#cb43-22" tabindex="-1"></a> <span class="co"># should check that r < 10^scale</span></span> <span id="cb43-23"><a href="#cb43-23" tabindex="-1"></a> <span class="fu">new_decimal2</span>(<span class="at">l =</span> l, <span class="at">r =</span> r, <span class="at">scale =</span> scale)</span> <span id="cb43-24"><a href="#cb43-24" tabindex="-1"></a>}</span> <span id="cb43-25"><a href="#cb43-25" tabindex="-1"></a></span> <span id="cb43-26"><a href="#cb43-26" tabindex="-1"></a>format.vctrs_decimal2 <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb43-27"><a href="#cb43-27" tabindex="-1"></a> val <span class="ot"><-</span> <span class="fu">field</span>(x, <span class="st">"l"</span>) <span class="sc">+</span> <span class="fu">field</span>(x, <span class="st">"r"</span>) <span class="sc">/</span> <span class="dv">10</span><span class="sc">^</span><span class="fu">attr</span>(x, <span class="st">"scale"</span>)</span> <span id="cb43-28"><a href="#cb43-28" tabindex="-1"></a> <span class="fu">sprintf</span>(<span class="fu">paste0</span>(<span class="st">"%.0"</span>, <span class="fu">attr</span>(x, <span class="st">"scale"</span>), <span class="st">"f"</span>), val)</span> <span id="cb43-29"><a href="#cb43-29" tabindex="-1"></a>}</span> <span id="cb43-30"><a href="#cb43-30" tabindex="-1"></a></span> <span id="cb43-31"><a href="#cb43-31" tabindex="-1"></a><span class="fu">decimal2</span>(<span class="dv">10</span>, <span class="fu">c</span>(<span class="dv">0</span>, <span class="dv">5</span>, <span class="dv">99</span>))</span> <span id="cb43-32"><a href="#cb43-32" tabindex="-1"></a><span class="co">#> <vctrs_decimal2[3]></span></span> <span id="cb43-33"><a href="#cb43-33" tabindex="-1"></a><span class="co">#> [1] 10.00 10.05 10.99</span></span></code></pre></div> </div> </div> <div id="equality-and-comparison" class="section level2"> <h2>Equality and comparison</h2> <p>vctrs provides four “proxy” generics. Two of these let you control how your class determines equality and comparison:</p> <ul> <li><p><code>vec_proxy_equal()</code> returns a data vector suitable for comparison. It underpins <code>==</code>, <code>!=</code>, <code>unique()</code>, <code>anyDuplicated()</code>, and <code>is.na()</code>.</p></li> <li><p><code>vec_proxy_compare()</code> specifies how to compare the elements of your vector. This proxy is used in <code><</code>, <code><=</code>, <code>>=</code>, <code>></code>, <code>min()</code>, <code>max()</code>, <code>median()</code>, and <code>quantile()</code>.</p></li> </ul> <p>Two other proxy generic are used for sorting for unordered data types and for accessing the raw data for exotic storage formats:</p> <ul> <li><p><code>vec_proxy_order()</code> specifies how to sort the elements of your vector. It is used in <code>xtfrm()</code>, which in turn is called by the <code>order()</code> and <code>sort()</code> functions.</p> <p>This proxy was added to implement the behaviour of lists, which are sortable (their order proxy sorts by first occurrence) but not comparable (comparison operators cause an error). Its default implementation for other classes calls <code>vec_proxy_compare()</code> and you normally don’t need to implement this proxy.</p></li> <li><p><code>vec_proxy()</code> returns the actual data of a vector. This is useful when you store the data in a field of your class. Most of the time, you shouldn’t need to implement <code>vec_proxy()</code>.</p></li> </ul> <p>The default behavior is as follows:</p> <ul> <li><code>vec_proxy_equal()</code> calls <code>vec_proxy()</code></li> <li><code>vec_proxy_compare()</code> calls <code>vec_proxy_equal()</code></li> <li><code>vec_proxy_order()</code> calls <code>vec_proxy_compare()</code></li> </ul> <p>You should only implement these proxies when some preprocessing on the data is needed to make elements comparable. In that case, defining these methods will get you a lot of behaviour for relatively little work.</p> <p>These proxy functions should always return a simple object (either a bare vector or a data frame) that possesses the same properties as your class. This permits efficient implementation of the vctrs internals because it allows dispatch to happen once in R, and then efficient computations can be written in C.</p> <div id="rational-class-1" class="section level3"> <h3>Rational class</h3> <p>Let’s explore these ideas by with the rational class we started on above. By default, <code>vec_proxy()</code> converts a record to a data frame, and the default comparison works column by column:</p> <div class="sourceCode" id="cb44"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb44-1"><a href="#cb44-1" tabindex="-1"></a>x <span class="ot"><-</span> <span class="fu">rational</span>(<span class="fu">c</span>(<span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">1</span>, <span class="dv">2</span>), <span class="fu">c</span>(<span class="dv">1</span>, <span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">2</span>))</span> <span id="cb44-2"><a href="#cb44-2" tabindex="-1"></a>x</span> <span id="cb44-3"><a href="#cb44-3" tabindex="-1"></a><span class="co">#> <rational[4]></span></span> <span id="cb44-4"><a href="#cb44-4" tabindex="-1"></a><span class="co">#> [1] 1/1 2/1 1/2 2/2</span></span> <span id="cb44-5"><a href="#cb44-5" tabindex="-1"></a></span> <span id="cb44-6"><a href="#cb44-6" tabindex="-1"></a><span class="fu">vec_proxy</span>(x)</span> <span id="cb44-7"><a href="#cb44-7" tabindex="-1"></a><span class="co">#> n d</span></span> <span id="cb44-8"><a href="#cb44-8" tabindex="-1"></a><span class="co">#> 1 1 1</span></span> <span id="cb44-9"><a href="#cb44-9" tabindex="-1"></a><span class="co">#> 2 2 1</span></span> <span id="cb44-10"><a href="#cb44-10" tabindex="-1"></a><span class="co">#> 3 1 2</span></span> <span id="cb44-11"><a href="#cb44-11" tabindex="-1"></a><span class="co">#> 4 2 2</span></span> <span id="cb44-12"><a href="#cb44-12" tabindex="-1"></a></span> <span id="cb44-13"><a href="#cb44-13" tabindex="-1"></a>x <span class="sc">==</span> <span class="fu">rational</span>(<span class="dv">1</span>, <span class="dv">1</span>)</span> <span id="cb44-14"><a href="#cb44-14" tabindex="-1"></a><span class="co">#> [1] TRUE FALSE FALSE FALSE</span></span></code></pre></div> <p>This makes sense as a default but isn’t correct here because <code>rational(1, 1)</code> represents the same number as <code>rational(2, 2)</code>, so they should be equal. We can fix that by implementing a <code>vec_proxy_equal()</code> method that divides <code>n</code> and <code>d</code> by their greatest common divisor:</p> <div class="sourceCode" id="cb45"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb45-1"><a href="#cb45-1" tabindex="-1"></a><span class="co"># Thanks to Matthew Lundberg: https://stackoverflow.com/a/21504113/16632</span></span> <span id="cb45-2"><a href="#cb45-2" tabindex="-1"></a>gcd <span class="ot"><-</span> <span class="cf">function</span>(x, y) {</span> <span id="cb45-3"><a href="#cb45-3" tabindex="-1"></a> r <span class="ot"><-</span> x <span class="sc">%%</span> y</span> <span id="cb45-4"><a href="#cb45-4" tabindex="-1"></a> <span class="fu">ifelse</span>(r, <span class="fu">gcd</span>(y, r), y)</span> <span id="cb45-5"><a href="#cb45-5" tabindex="-1"></a>}</span> <span id="cb45-6"><a href="#cb45-6" tabindex="-1"></a></span> <span id="cb45-7"><a href="#cb45-7" tabindex="-1"></a>vec_proxy_equal.vctrs_rational <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb45-8"><a href="#cb45-8" tabindex="-1"></a> n <span class="ot"><-</span> <span class="fu">field</span>(x, <span class="st">"n"</span>)</span> <span id="cb45-9"><a href="#cb45-9" tabindex="-1"></a> d <span class="ot"><-</span> <span class="fu">field</span>(x, <span class="st">"d"</span>)</span> <span id="cb45-10"><a href="#cb45-10" tabindex="-1"></a> gcd <span class="ot"><-</span> <span class="fu">gcd</span>(n, d)</span> <span id="cb45-11"><a href="#cb45-11" tabindex="-1"></a></span> <span id="cb45-12"><a href="#cb45-12" tabindex="-1"></a> <span class="fu">data.frame</span>(<span class="at">n =</span> n <span class="sc">/</span> gcd, <span class="at">d =</span> d <span class="sc">/</span> gcd)</span> <span id="cb45-13"><a href="#cb45-13" tabindex="-1"></a>}</span> <span id="cb45-14"><a href="#cb45-14" tabindex="-1"></a><span class="fu">vec_proxy_equal</span>(x)</span> <span id="cb45-15"><a href="#cb45-15" tabindex="-1"></a><span class="co">#> n d</span></span> <span id="cb45-16"><a href="#cb45-16" tabindex="-1"></a><span class="co">#> 1 1 1</span></span> <span id="cb45-17"><a href="#cb45-17" tabindex="-1"></a><span class="co">#> 2 2 1</span></span> <span id="cb45-18"><a href="#cb45-18" tabindex="-1"></a><span class="co">#> 3 1 2</span></span> <span id="cb45-19"><a href="#cb45-19" tabindex="-1"></a><span class="co">#> 4 1 1</span></span> <span id="cb45-20"><a href="#cb45-20" tabindex="-1"></a></span> <span id="cb45-21"><a href="#cb45-21" tabindex="-1"></a>x <span class="sc">==</span> <span class="fu">rational</span>(<span class="dv">1</span>, <span class="dv">1</span>)</span> <span id="cb45-22"><a href="#cb45-22" tabindex="-1"></a><span class="co">#> [1] TRUE FALSE FALSE TRUE</span></span></code></pre></div> <p><code>vec_proxy_equal()</code> is also used by <code>unique()</code>:</p> <div class="sourceCode" id="cb46"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb46-1"><a href="#cb46-1" tabindex="-1"></a><span class="fu">unique</span>(x)</span> <span id="cb46-2"><a href="#cb46-2" tabindex="-1"></a><span class="co">#> <rational[3]></span></span> <span id="cb46-3"><a href="#cb46-3" tabindex="-1"></a><span class="co">#> [1] 1/1 2/1 1/2</span></span></code></pre></div> <p>We now need to fix the comparison operations similarly, since comparison currently happens lexicographically by <code>n</code>, then by <code>d</code>:</p> <div class="sourceCode" id="cb47"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb47-1"><a href="#cb47-1" tabindex="-1"></a><span class="fu">rational</span>(<span class="dv">1</span>, <span class="dv">2</span>) <span class="sc"><</span> <span class="fu">rational</span>(<span class="dv">2</span>, <span class="dv">3</span>)</span> <span id="cb47-2"><a href="#cb47-2" tabindex="-1"></a><span class="co">#> [1] TRUE</span></span> <span id="cb47-3"><a href="#cb47-3" tabindex="-1"></a><span class="fu">rational</span>(<span class="dv">2</span>, <span class="dv">4</span>) <span class="sc"><</span> <span class="fu">rational</span>(<span class="dv">2</span>, <span class="dv">3</span>)</span> <span id="cb47-4"><a href="#cb47-4" tabindex="-1"></a><span class="co">#> [1] TRUE</span></span></code></pre></div> <p>The easiest fix is to convert the fraction to a floating point number and use this as a proxy:</p> <div class="sourceCode" id="cb48"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb48-1"><a href="#cb48-1" tabindex="-1"></a>vec_proxy_compare.vctrs_rational <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb48-2"><a href="#cb48-2" tabindex="-1"></a> <span class="fu">field</span>(x, <span class="st">"n"</span>) <span class="sc">/</span> <span class="fu">field</span>(x, <span class="st">"d"</span>)</span> <span id="cb48-3"><a href="#cb48-3" tabindex="-1"></a>}</span> <span id="cb48-4"><a href="#cb48-4" tabindex="-1"></a></span> <span id="cb48-5"><a href="#cb48-5" tabindex="-1"></a><span class="fu">rational</span>(<span class="dv">2</span>, <span class="dv">4</span>) <span class="sc"><</span> <span class="fu">rational</span>(<span class="dv">2</span>, <span class="dv">3</span>)</span> <span id="cb48-6"><a href="#cb48-6" tabindex="-1"></a><span class="co">#> [1] TRUE</span></span></code></pre></div> <p>This also fixes <code>sort()</code>, because the default implementation of <code>vec_proxy_order()</code> calls <code>vec_proxy_compare()</code>.</p> <div class="sourceCode" id="cb49"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb49-1"><a href="#cb49-1" tabindex="-1"></a><span class="fu">sort</span>(x)</span> <span id="cb49-2"><a href="#cb49-2" tabindex="-1"></a><span class="co">#> <rational[4]></span></span> <span id="cb49-3"><a href="#cb49-3" tabindex="-1"></a><span class="co">#> [1] 1/2 1/1 2/2 2/1</span></span></code></pre></div> <p>(We could have used the same approach in <code>vec_proxy_equal()</code>, but when working with floating point numbers it’s not necessarily true that <code>x == y</code> implies that <code>d * x == d * y</code>.)</p> </div> <div id="polynomial-class" class="section level3"> <h3>Polynomial class</h3> <p>A related problem occurs if we build our vector on top of a list. The following code defines a polynomial class that represents polynomials (like <code>1 + 3x - 2x^2</code>) using a list of integer vectors (like <code>c(1, 3, -2)</code>). Note the use of <code>new_list_of()</code> in the constructor.</p> <div class="sourceCode" id="cb50"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb50-1"><a href="#cb50-1" tabindex="-1"></a>poly <span class="ot"><-</span> <span class="cf">function</span>(...) {</span> <span id="cb50-2"><a href="#cb50-2" tabindex="-1"></a> x <span class="ot"><-</span> <span class="fu">vec_cast_common</span>(..., <span class="at">.to =</span> <span class="fu">integer</span>())</span> <span id="cb50-3"><a href="#cb50-3" tabindex="-1"></a> <span class="fu">new_poly</span>(x)</span> <span id="cb50-4"><a href="#cb50-4" tabindex="-1"></a>}</span> <span id="cb50-5"><a href="#cb50-5" tabindex="-1"></a>new_poly <span class="ot"><-</span> <span class="cf">function</span>(x) {</span> <span id="cb50-6"><a href="#cb50-6" tabindex="-1"></a> <span class="fu">new_list_of</span>(x, <span class="at">ptype =</span> <span class="fu">integer</span>(), <span class="at">class =</span> <span class="st">"vctrs_poly_list"</span>)</span> <span id="cb50-7"><a href="#cb50-7" tabindex="-1"></a>}</span> <span id="cb50-8"><a href="#cb50-8" tabindex="-1"></a></span> <span id="cb50-9"><a href="#cb50-9" tabindex="-1"></a>vec_ptype_full.vctrs_poly_list <span class="ot"><-</span> <span class="cf">function</span>(x, ...) <span class="st">"polynomial"</span></span> <span id="cb50-10"><a href="#cb50-10" tabindex="-1"></a>vec_ptype_abbr.vctrs_poly_list <span class="ot"><-</span> <span class="cf">function</span>(x, ...) <span class="st">"poly"</span></span> <span id="cb50-11"><a href="#cb50-11" tabindex="-1"></a></span> <span id="cb50-12"><a href="#cb50-12" tabindex="-1"></a>format.vctrs_poly_list <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb50-13"><a href="#cb50-13" tabindex="-1"></a> format_one <span class="ot"><-</span> <span class="cf">function</span>(x) {</span> <span id="cb50-14"><a href="#cb50-14" tabindex="-1"></a> <span class="cf">if</span> (<span class="fu">length</span>(x) <span class="sc">==</span> <span class="dv">0</span>) {</span> <span id="cb50-15"><a href="#cb50-15" tabindex="-1"></a> <span class="fu">return</span>(<span class="st">""</span>)</span> <span id="cb50-16"><a href="#cb50-16" tabindex="-1"></a> }</span> <span id="cb50-17"><a href="#cb50-17" tabindex="-1"></a></span> <span id="cb50-18"><a href="#cb50-18" tabindex="-1"></a> <span class="cf">if</span> (<span class="fu">length</span>(x) <span class="sc">==</span> <span class="dv">1</span>) {</span> <span id="cb50-19"><a href="#cb50-19" tabindex="-1"></a> <span class="fu">format</span>(x)</span> <span id="cb50-20"><a href="#cb50-20" tabindex="-1"></a> } <span class="cf">else</span> {</span> <span id="cb50-21"><a href="#cb50-21" tabindex="-1"></a> suffix <span class="ot"><-</span> <span class="fu">c</span>(<span class="fu">paste0</span>(<span class="st">"\u22C5x^"</span>, <span class="fu">seq</span>(<span class="fu">length</span>(x) <span class="sc">-</span> <span class="dv">1</span>, <span class="dv">1</span>)), <span class="st">""</span>)</span> <span id="cb50-22"><a href="#cb50-22" tabindex="-1"></a> out <span class="ot"><-</span> <span class="fu">paste0</span>(x, suffix)</span> <span id="cb50-23"><a href="#cb50-23" tabindex="-1"></a> out <span class="ot"><-</span> out[x <span class="sc">!=</span> <span class="dv">0</span><span class="dt">L</span>]</span> <span id="cb50-24"><a href="#cb50-24" tabindex="-1"></a> <span class="fu">paste0</span>(out, <span class="at">collapse =</span> <span class="st">" + "</span>)</span> <span id="cb50-25"><a href="#cb50-25" tabindex="-1"></a> }</span> <span id="cb50-26"><a href="#cb50-26" tabindex="-1"></a> }</span> <span id="cb50-27"><a href="#cb50-27" tabindex="-1"></a></span> <span id="cb50-28"><a href="#cb50-28" tabindex="-1"></a> <span class="fu">vapply</span>(x, format_one, <span class="fu">character</span>(<span class="dv">1</span>))</span> <span id="cb50-29"><a href="#cb50-29" tabindex="-1"></a>}</span> <span id="cb50-30"><a href="#cb50-30" tabindex="-1"></a></span> <span id="cb50-31"><a href="#cb50-31" tabindex="-1"></a>obj_print_data.vctrs_poly_list <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb50-32"><a href="#cb50-32" tabindex="-1"></a> <span class="cf">if</span> (<span class="fu">length</span>(x) <span class="sc">!=</span> <span class="dv">0</span>) {</span> <span id="cb50-33"><a href="#cb50-33" tabindex="-1"></a> <span class="fu">print</span>(<span class="fu">format</span>(x), <span class="at">quote =</span> <span class="cn">FALSE</span>)</span> <span id="cb50-34"><a href="#cb50-34" tabindex="-1"></a> }</span> <span id="cb50-35"><a href="#cb50-35" tabindex="-1"></a>}</span> <span id="cb50-36"><a href="#cb50-36" tabindex="-1"></a></span> <span id="cb50-37"><a href="#cb50-37" tabindex="-1"></a>p <span class="ot"><-</span> <span class="fu">poly</span>(<span class="dv">1</span>, <span class="fu">c</span>(<span class="dv">1</span>, <span class="dv">0</span>, <span class="dv">0</span>, <span class="dv">0</span>, <span class="dv">2</span>), <span class="fu">c</span>(<span class="dv">1</span>, <span class="dv">0</span>, <span class="dv">1</span>))</span> <span id="cb50-38"><a href="#cb50-38" tabindex="-1"></a>p</span> <span id="cb50-39"><a href="#cb50-39" tabindex="-1"></a><span class="co">#> <polynomial[3]></span></span> <span id="cb50-40"><a href="#cb50-40" tabindex="-1"></a><span class="co">#> [1] 1 1⋅x^4 + 2 1⋅x^2 + 1</span></span></code></pre></div> <p>The resulting objects will inherit from the <code>vctrs_list_of</code> class, which provides tailored methods for <code>$</code>, <code>[[</code>, the corresponding assignment operators, and other methods.</p> <div class="sourceCode" id="cb51"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb51-1"><a href="#cb51-1" tabindex="-1"></a><span class="fu">class</span>(p)</span> <span id="cb51-2"><a href="#cb51-2" tabindex="-1"></a><span class="co">#> [1] "vctrs_poly_list" "vctrs_list_of" "vctrs_vctr" "list"</span></span> <span id="cb51-3"><a href="#cb51-3" tabindex="-1"></a>p[<span class="dv">2</span>]</span> <span id="cb51-4"><a href="#cb51-4" tabindex="-1"></a><span class="co">#> <polynomial[1]></span></span> <span id="cb51-5"><a href="#cb51-5" tabindex="-1"></a><span class="co">#> [1] 1⋅x^4 + 2</span></span> <span id="cb51-6"><a href="#cb51-6" tabindex="-1"></a>p[[<span class="dv">2</span>]]</span> <span id="cb51-7"><a href="#cb51-7" tabindex="-1"></a><span class="co">#> [1] 1 0 0 0 2</span></span></code></pre></div> <p>The class implements the list interface:</p> <div class="sourceCode" id="cb52"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb52-1"><a href="#cb52-1" tabindex="-1"></a><span class="fu">obj_is_list</span>(p)</span> <span id="cb52-2"><a href="#cb52-2" tabindex="-1"></a><span class="co">#> [1] TRUE</span></span></code></pre></div> <p>This is fine for the internal implementation of this class but it would be more appropriate if it behaved like an atomic vector rather than a list.</p> <div id="make-an-atomic-polynomial-vector" class="section level4"> <h4>Make an atomic polynomial vector</h4> <p>An atomic vector is a vector like integer or character for which <code>[[</code> returns the same type. Unlike lists, you can’t reach inside an atomic vector.</p> <p>To make the polynomial class an atomic vector, we’ll wrap the internal <code>list_of()</code> class within a record vector. Usually records are used because they can store several fields of data for each observation. Here we have only one, but we use the class anyway to inherit its atomicity.</p> <div class="sourceCode" id="cb53"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb53-1"><a href="#cb53-1" tabindex="-1"></a>poly <span class="ot"><-</span> <span class="cf">function</span>(...) {</span> <span id="cb53-2"><a href="#cb53-2" tabindex="-1"></a> x <span class="ot"><-</span> <span class="fu">vec_cast_common</span>(..., <span class="at">.to =</span> <span class="fu">integer</span>())</span> <span id="cb53-3"><a href="#cb53-3" tabindex="-1"></a> x <span class="ot"><-</span> <span class="fu">new_poly</span>(x)</span> <span id="cb53-4"><a href="#cb53-4" tabindex="-1"></a> <span class="fu">new_rcrd</span>(<span class="fu">list</span>(<span class="at">data =</span> x), <span class="at">class =</span> <span class="st">"vctrs_poly"</span>)</span> <span id="cb53-5"><a href="#cb53-5" tabindex="-1"></a>}</span> <span id="cb53-6"><a href="#cb53-6" tabindex="-1"></a>format.vctrs_poly <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb53-7"><a href="#cb53-7" tabindex="-1"></a> <span class="fu">format</span>(<span class="fu">field</span>(x, <span class="st">"data"</span>))</span> <span id="cb53-8"><a href="#cb53-8" tabindex="-1"></a>}</span></code></pre></div> <p>The new <code>format()</code> method delegates to the one we wrote for the internal list. The vector looks just like before:</p> <div class="sourceCode" id="cb54"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb54-1"><a href="#cb54-1" tabindex="-1"></a>p <span class="ot"><-</span> <span class="fu">poly</span>(<span class="dv">1</span>, <span class="fu">c</span>(<span class="dv">1</span>, <span class="dv">0</span>, <span class="dv">0</span>, <span class="dv">0</span>, <span class="dv">2</span>), <span class="fu">c</span>(<span class="dv">1</span>, <span class="dv">0</span>, <span class="dv">1</span>))</span> <span id="cb54-2"><a href="#cb54-2" tabindex="-1"></a>p</span> <span id="cb54-3"><a href="#cb54-3" tabindex="-1"></a><span class="co">#> <vctrs_poly[3]></span></span> <span id="cb54-4"><a href="#cb54-4" tabindex="-1"></a><span class="co">#> [1] 1 1⋅x^4 + 2 1⋅x^2 + 1</span></span></code></pre></div> <p>Making the class atomic means that <code>obj_is_list()</code> now returns <code>FALSE</code>. This prevents recursive algorithms that traverse lists from reaching too far inside the polynomial internals.</p> <div class="sourceCode" id="cb55"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb55-1"><a href="#cb55-1" tabindex="-1"></a><span class="fu">obj_is_list</span>(p)</span> <span id="cb55-2"><a href="#cb55-2" tabindex="-1"></a><span class="co">#> [1] FALSE</span></span></code></pre></div> <p>Most importantly, it prevents users from reaching into the internals with <code>[[</code>:</p> <div class="sourceCode" id="cb56"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb56-1"><a href="#cb56-1" tabindex="-1"></a>p[[<span class="dv">2</span>]]</span> <span id="cb56-2"><a href="#cb56-2" tabindex="-1"></a><span class="co">#> <vctrs_poly[1]></span></span> <span id="cb56-3"><a href="#cb56-3" tabindex="-1"></a><span class="co">#> [1] 1⋅x^4 + 2</span></span></code></pre></div> </div> <div id="implementing-equality-and-comparison" class="section level4"> <h4>Implementing equality and comparison</h4> <p>Equality works out of the box because we can tell if two integer vectors are equal:</p> <div class="sourceCode" id="cb57"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb57-1"><a href="#cb57-1" tabindex="-1"></a>p <span class="sc">==</span> <span class="fu">poly</span>(<span class="fu">c</span>(<span class="dv">1</span>, <span class="dv">0</span>, <span class="dv">1</span>))</span> <span id="cb57-2"><a href="#cb57-2" tabindex="-1"></a><span class="co">#> [1] FALSE FALSE TRUE</span></span></code></pre></div> <p>We can’t compare individual elements, because the data is stored in a list and by default lists are not comparable:</p> <div class="sourceCode" id="cb58"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb58-1"><a href="#cb58-1" tabindex="-1"></a>p <span class="sc"><</span> p[<span class="dv">2</span>]</span> <span id="cb58-2"><a href="#cb58-2" tabindex="-1"></a><span class="co">#> Error in `vec_proxy_compare()`:</span></span> <span id="cb58-3"><a href="#cb58-3" tabindex="-1"></a><span class="co">#> ! `vec_proxy_compare.vctrs_poly_list()` not supported.</span></span></code></pre></div> <p>To enable comparison, we implement a <code>vec_proxy_compare()</code> method:</p> <div class="sourceCode" id="cb59"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb59-1"><a href="#cb59-1" tabindex="-1"></a>vec_proxy_compare.vctrs_poly <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb59-2"><a href="#cb59-2" tabindex="-1"></a> <span class="co"># Get the list inside the record vector</span></span> <span id="cb59-3"><a href="#cb59-3" tabindex="-1"></a> x_raw <span class="ot"><-</span> <span class="fu">vec_data</span>(<span class="fu">field</span>(x, <span class="st">"data"</span>))</span> <span id="cb59-4"><a href="#cb59-4" tabindex="-1"></a></span> <span id="cb59-5"><a href="#cb59-5" tabindex="-1"></a> <span class="co"># First figure out the maximum length</span></span> <span id="cb59-6"><a href="#cb59-6" tabindex="-1"></a> n <span class="ot"><-</span> <span class="fu">max</span>(<span class="fu">vapply</span>(x_raw, length, <span class="fu">integer</span>(<span class="dv">1</span>)))</span> <span id="cb59-7"><a href="#cb59-7" tabindex="-1"></a></span> <span id="cb59-8"><a href="#cb59-8" tabindex="-1"></a> <span class="co"># Then expand all vectors to this length by filling in with zeros</span></span> <span id="cb59-9"><a href="#cb59-9" tabindex="-1"></a> full <span class="ot"><-</span> <span class="fu">lapply</span>(x_raw, <span class="cf">function</span>(x) <span class="fu">c</span>(<span class="fu">rep</span>(<span class="dv">0</span><span class="dt">L</span>, n <span class="sc">-</span> <span class="fu">length</span>(x)), x))</span> <span id="cb59-10"><a href="#cb59-10" tabindex="-1"></a></span> <span id="cb59-11"><a href="#cb59-11" tabindex="-1"></a> <span class="co"># Then turn into a data frame</span></span> <span id="cb59-12"><a href="#cb59-12" tabindex="-1"></a> <span class="fu">as.data.frame</span>(<span class="fu">do.call</span>(rbind, full))</span> <span id="cb59-13"><a href="#cb59-13" tabindex="-1"></a>}</span> <span id="cb59-14"><a href="#cb59-14" tabindex="-1"></a></span> <span id="cb59-15"><a href="#cb59-15" tabindex="-1"></a>p <span class="sc"><</span> p[<span class="dv">2</span>]</span> <span id="cb59-16"><a href="#cb59-16" tabindex="-1"></a><span class="co">#> [1] TRUE FALSE TRUE</span></span></code></pre></div> <p>Often, this is sufficient to also implement <code>sort()</code>. However, for lists, there is already a default <code>vec_proxy_order()</code> method that sorts by first occurrence:</p> <div class="sourceCode" id="cb60"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb60-1"><a href="#cb60-1" tabindex="-1"></a><span class="fu">sort</span>(p)</span> <span id="cb60-2"><a href="#cb60-2" tabindex="-1"></a><span class="co">#> <vctrs_poly[3]></span></span> <span id="cb60-3"><a href="#cb60-3" tabindex="-1"></a><span class="co">#> [1] 1 1⋅x^2 + 1 1⋅x^4 + 2</span></span> <span id="cb60-4"><a href="#cb60-4" tabindex="-1"></a><span class="fu">sort</span>(p[<span class="fu">c</span>(<span class="dv">1</span><span class="sc">:</span><span class="dv">3</span>, <span class="dv">1</span><span class="sc">:</span><span class="dv">2</span>)])</span> <span id="cb60-5"><a href="#cb60-5" tabindex="-1"></a><span class="co">#> <vctrs_poly[5]></span></span> <span id="cb60-6"><a href="#cb60-6" tabindex="-1"></a><span class="co">#> [1] 1 1 1⋅x^2 + 1 1⋅x^4 + 2 1⋅x^4 + 2</span></span></code></pre></div> <p>To ensure consistency between ordering and comparison, we forward <code>vec_proxy_order()</code> to <code>vec_proxy_compare()</code>:</p> <div class="sourceCode" id="cb61"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb61-1"><a href="#cb61-1" tabindex="-1"></a>vec_proxy_order.vctrs_poly <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb61-2"><a href="#cb61-2" tabindex="-1"></a> <span class="fu">vec_proxy_compare</span>(x, ...)</span> <span id="cb61-3"><a href="#cb61-3" tabindex="-1"></a>}</span> <span id="cb61-4"><a href="#cb61-4" tabindex="-1"></a></span> <span id="cb61-5"><a href="#cb61-5" tabindex="-1"></a><span class="fu">sort</span>(p)</span> <span id="cb61-6"><a href="#cb61-6" tabindex="-1"></a><span class="co">#> <vctrs_poly[3]></span></span> <span id="cb61-7"><a href="#cb61-7" tabindex="-1"></a><span class="co">#> [1] 1 1⋅x^2 + 1 1⋅x^4 + 2</span></span></code></pre></div> </div> </div> </div> <div id="arithmetic" class="section level2"> <h2>Arithmetic</h2> <p>vctrs also provides two mathematical generics that allow you to define a broad swath of mathematical behaviour at once:</p> <ul> <li><p><code>vec_math(fn, x, ...)</code> specifies the behaviour of mathematical functions like <code>abs()</code>, <code>sum()</code>, and <code>mean()</code>. (Note that <code>var()</code> and <code>sd()</code> can’t be overridden, see <code>?vec_math()</code> for the complete list supported by <code>vec_math()</code>.)</p></li> <li><p><code>vec_arith(op, x, y)</code> specifies the behaviour of the arithmetic operations like <code>+</code>, <code>-</code>, and <code>%%</code>. (See <code>?vec_arith()</code> for the complete list.)</p></li> </ul> <p>Both generics define the behaviour for multiple functions because <code>sum.vctrs_vctr(x)</code> calls <code>vec_math.vctrs_vctr("sum", x)</code>, and <code>x + y</code> calls <code>vec_math.x_class.y_class("+", x, y)</code>. They’re accompanied by <code>vec_math_base()</code> and <code>vec_arith_base()</code> which make it easy to call the underlying base R functions.</p> <p><code>vec_arith()</code> uses double dispatch and needs the following standard boilerplate:</p> <div class="sourceCode" id="cb62"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb62-1"><a href="#cb62-1" tabindex="-1"></a>vec_arith.MYCLASS <span class="ot"><-</span> <span class="cf">function</span>(op, x, y, ...) {</span> <span id="cb62-2"><a href="#cb62-2" tabindex="-1"></a> <span class="fu">UseMethod</span>(<span class="st">"vec_arith.MYCLASS"</span>, y)</span> <span id="cb62-3"><a href="#cb62-3" tabindex="-1"></a>}</span> <span id="cb62-4"><a href="#cb62-4" tabindex="-1"></a>vec_arith.MYCLASS.default <span class="ot"><-</span> <span class="cf">function</span>(op, x, y, ...) {</span> <span id="cb62-5"><a href="#cb62-5" tabindex="-1"></a> <span class="fu">stop_incompatible_op</span>(op, x, y)</span> <span id="cb62-6"><a href="#cb62-6" tabindex="-1"></a>}</span></code></pre></div> <p>Correctly exporting <code>vec_arith()</code> methods from a package is currently a little awkward. See the instructions in the Arithmetic section of the “Implementing a vctrs S3 class in a package” section below.</p> <div id="cached-sum-class" class="section level3"> <h3>Cached sum class</h3> <p>I showed an example of <code>vec_math()</code> to define <code>sum()</code> and <code>mean()</code> methods for <code>cached_sum</code>. Now let’s talk about exactly how it works. Most <code>vec_math()</code> functions will have a similar form. You use a switch statement to handle the methods that you care about and fall back to <code>vec_math_base()</code> for those that you don’t care about.</p> <div class="sourceCode" id="cb63"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb63-1"><a href="#cb63-1" tabindex="-1"></a>vec_math.vctrs_cached_sum <span class="ot"><-</span> <span class="cf">function</span>(.fn, .x, ...) {</span> <span id="cb63-2"><a href="#cb63-2" tabindex="-1"></a> <span class="cf">switch</span>(.fn,</span> <span id="cb63-3"><a href="#cb63-3" tabindex="-1"></a> <span class="at">sum =</span> <span class="fu">attr</span>(.x, <span class="st">"sum"</span>),</span> <span id="cb63-4"><a href="#cb63-4" tabindex="-1"></a> <span class="at">mean =</span> <span class="fu">attr</span>(.x, <span class="st">"sum"</span>) <span class="sc">/</span> <span class="fu">length</span>(.x),</span> <span id="cb63-5"><a href="#cb63-5" tabindex="-1"></a> <span class="fu">vec_math_base</span>(.fn, .x, ...)</span> <span id="cb63-6"><a href="#cb63-6" tabindex="-1"></a> )</span> <span id="cb63-7"><a href="#cb63-7" tabindex="-1"></a>}</span></code></pre></div> </div> <div id="meter-class" class="section level3"> <h3>Meter class</h3> <p>To explore the infix arithmetic operators exposed by <code>vec_arith()</code> I’ll create a new class that represents a measurement in <code>meter</code>s:</p> <div class="sourceCode" id="cb64"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb64-1"><a href="#cb64-1" tabindex="-1"></a>new_meter <span class="ot"><-</span> <span class="cf">function</span>(x) {</span> <span id="cb64-2"><a href="#cb64-2" tabindex="-1"></a> <span class="fu">stopifnot</span>(<span class="fu">is.double</span>(x))</span> <span id="cb64-3"><a href="#cb64-3" tabindex="-1"></a> <span class="fu">new_vctr</span>(x, <span class="at">class =</span> <span class="st">"vctrs_meter"</span>)</span> <span id="cb64-4"><a href="#cb64-4" tabindex="-1"></a>}</span> <span id="cb64-5"><a href="#cb64-5" tabindex="-1"></a></span> <span id="cb64-6"><a href="#cb64-6" tabindex="-1"></a>format.vctrs_meter <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb64-7"><a href="#cb64-7" tabindex="-1"></a> <span class="fu">paste0</span>(<span class="fu">format</span>(<span class="fu">vec_data</span>(x)), <span class="st">" m"</span>)</span> <span id="cb64-8"><a href="#cb64-8" tabindex="-1"></a>}</span> <span id="cb64-9"><a href="#cb64-9" tabindex="-1"></a></span> <span id="cb64-10"><a href="#cb64-10" tabindex="-1"></a>meter <span class="ot"><-</span> <span class="cf">function</span>(x) {</span> <span id="cb64-11"><a href="#cb64-11" tabindex="-1"></a> x <span class="ot"><-</span> <span class="fu">vec_cast</span>(x, <span class="fu">double</span>())</span> <span id="cb64-12"><a href="#cb64-12" tabindex="-1"></a> <span class="fu">new_meter</span>(x)</span> <span id="cb64-13"><a href="#cb64-13" tabindex="-1"></a>}</span> <span id="cb64-14"><a href="#cb64-14" tabindex="-1"></a></span> <span id="cb64-15"><a href="#cb64-15" tabindex="-1"></a>x <span class="ot"><-</span> <span class="fu">meter</span>(<span class="dv">1</span><span class="sc">:</span><span class="dv">10</span>)</span> <span id="cb64-16"><a href="#cb64-16" tabindex="-1"></a>x</span> <span id="cb64-17"><a href="#cb64-17" tabindex="-1"></a><span class="co">#> <vctrs_meter[10]></span></span> <span id="cb64-18"><a href="#cb64-18" tabindex="-1"></a><span class="co">#> [1] 1 m 2 m 3 m 4 m 5 m 6 m 7 m 8 m 9 m 10 m</span></span></code></pre></div> <p>Because <code>meter</code> is built on top of a double vector, basic mathematic operations work:</p> <div class="sourceCode" id="cb65"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb65-1"><a href="#cb65-1" tabindex="-1"></a><span class="fu">sum</span>(x)</span> <span id="cb65-2"><a href="#cb65-2" tabindex="-1"></a><span class="co">#> <vctrs_meter[1]></span></span> <span id="cb65-3"><a href="#cb65-3" tabindex="-1"></a><span class="co">#> [1] 55 m</span></span> <span id="cb65-4"><a href="#cb65-4" tabindex="-1"></a><span class="fu">mean</span>(x)</span> <span id="cb65-5"><a href="#cb65-5" tabindex="-1"></a><span class="co">#> <vctrs_meter[1]></span></span> <span id="cb65-6"><a href="#cb65-6" tabindex="-1"></a><span class="co">#> [1] 5.5 m</span></span></code></pre></div> <p>But we can’t do arithmetic:</p> <div class="sourceCode" id="cb66"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb66-1"><a href="#cb66-1" tabindex="-1"></a>x <span class="sc">+</span> <span class="dv">1</span></span> <span id="cb66-2"><a href="#cb66-2" tabindex="-1"></a><span class="co">#> Error in `vec_arith()`:</span></span> <span id="cb66-3"><a href="#cb66-3" tabindex="-1"></a><span class="co">#> ! <vctrs_meter> + <double> is not permitted</span></span> <span id="cb66-4"><a href="#cb66-4" tabindex="-1"></a><span class="fu">meter</span>(<span class="dv">10</span>) <span class="sc">+</span> <span class="fu">meter</span>(<span class="dv">1</span>)</span> <span id="cb66-5"><a href="#cb66-5" tabindex="-1"></a><span class="co">#> Error in `vec_arith()`:</span></span> <span id="cb66-6"><a href="#cb66-6" tabindex="-1"></a><span class="co">#> ! <vctrs_meter> + <vctrs_meter> is not permitted</span></span> <span id="cb66-7"><a href="#cb66-7" tabindex="-1"></a><span class="fu">meter</span>(<span class="dv">10</span>) <span class="sc">*</span> <span class="dv">3</span></span> <span id="cb66-8"><a href="#cb66-8" tabindex="-1"></a><span class="co">#> Error in `vec_arith()`:</span></span> <span id="cb66-9"><a href="#cb66-9" tabindex="-1"></a><span class="co">#> ! <vctrs_meter> * <double> is not permitted</span></span></code></pre></div> <p>To allow these infix functions to work, we’ll need to provide <code>vec_arith()</code> generic. But before we do that, let’s think about what combinations of inputs we should support:</p> <ul> <li><p>It makes sense to add and subtract meters: that yields another meter. We can divide a meter by another meter (yielding a unitless number), but we can’t multiply meters (because that would yield an area).</p></li> <li><p>For a combination of meter and number multiplication and division by a number are acceptable. Addition and subtraction don’t make much sense as we, strictly speaking, are dealing with objects of different nature.</p></li> </ul> <p><code>vec_arith()</code> is another function that uses double dispatch, so as usual we start with a template.</p> <div class="sourceCode" id="cb67"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb67-1"><a href="#cb67-1" tabindex="-1"></a>vec_arith.vctrs_meter <span class="ot"><-</span> <span class="cf">function</span>(op, x, y, ...) {</span> <span id="cb67-2"><a href="#cb67-2" tabindex="-1"></a> <span class="fu">UseMethod</span>(<span class="st">"vec_arith.vctrs_meter"</span>, y)</span> <span id="cb67-3"><a href="#cb67-3" tabindex="-1"></a>}</span> <span id="cb67-4"><a href="#cb67-4" tabindex="-1"></a>vec_arith.vctrs_meter.default <span class="ot"><-</span> <span class="cf">function</span>(op, x, y, ...) {</span> <span id="cb67-5"><a href="#cb67-5" tabindex="-1"></a> <span class="fu">stop_incompatible_op</span>(op, x, y)</span> <span id="cb67-6"><a href="#cb67-6" tabindex="-1"></a>}</span></code></pre></div> <p>Then write the method for two meter objects. We use a switch statement to cover the cases we care about and <code>stop_incompatible_op()</code> to throw an informative error message for everything else.</p> <div class="sourceCode" id="cb68"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb68-1"><a href="#cb68-1" tabindex="-1"></a>vec_arith.vctrs_meter.vctrs_meter <span class="ot"><-</span> <span class="cf">function</span>(op, x, y, ...) {</span> <span id="cb68-2"><a href="#cb68-2" tabindex="-1"></a> <span class="cf">switch</span>(</span> <span id="cb68-3"><a href="#cb68-3" tabindex="-1"></a> op,</span> <span id="cb68-4"><a href="#cb68-4" tabindex="-1"></a> <span class="st">"+"</span> <span class="ot">=</span> ,</span> <span id="cb68-5"><a href="#cb68-5" tabindex="-1"></a> <span class="st">"-"</span> <span class="ot">=</span> <span class="fu">new_meter</span>(<span class="fu">vec_arith_base</span>(op, x, y)),</span> <span id="cb68-6"><a href="#cb68-6" tabindex="-1"></a> <span class="st">"/"</span> <span class="ot">=</span> <span class="fu">vec_arith_base</span>(op, x, y),</span> <span id="cb68-7"><a href="#cb68-7" tabindex="-1"></a> <span class="fu">stop_incompatible_op</span>(op, x, y)</span> <span id="cb68-8"><a href="#cb68-8" tabindex="-1"></a> )</span> <span id="cb68-9"><a href="#cb68-9" tabindex="-1"></a>}</span> <span id="cb68-10"><a href="#cb68-10" tabindex="-1"></a></span> <span id="cb68-11"><a href="#cb68-11" tabindex="-1"></a><span class="fu">meter</span>(<span class="dv">10</span>) <span class="sc">+</span> <span class="fu">meter</span>(<span class="dv">1</span>)</span> <span id="cb68-12"><a href="#cb68-12" tabindex="-1"></a><span class="co">#> <vctrs_meter[1]></span></span> <span id="cb68-13"><a href="#cb68-13" tabindex="-1"></a><span class="co">#> [1] 11 m</span></span> <span id="cb68-14"><a href="#cb68-14" tabindex="-1"></a><span class="fu">meter</span>(<span class="dv">10</span>) <span class="sc">-</span> <span class="fu">meter</span>(<span class="dv">1</span>)</span> <span id="cb68-15"><a href="#cb68-15" tabindex="-1"></a><span class="co">#> <vctrs_meter[1]></span></span> <span id="cb68-16"><a href="#cb68-16" tabindex="-1"></a><span class="co">#> [1] 9 m</span></span> <span id="cb68-17"><a href="#cb68-17" tabindex="-1"></a><span class="fu">meter</span>(<span class="dv">10</span>) <span class="sc">/</span> <span class="fu">meter</span>(<span class="dv">1</span>)</span> <span id="cb68-18"><a href="#cb68-18" tabindex="-1"></a><span class="co">#> [1] 10</span></span> <span id="cb68-19"><a href="#cb68-19" tabindex="-1"></a><span class="fu">meter</span>(<span class="dv">10</span>) <span class="sc">*</span> <span class="fu">meter</span>(<span class="dv">1</span>)</span> <span id="cb68-20"><a href="#cb68-20" tabindex="-1"></a><span class="co">#> Error in `vec_arith()`:</span></span> <span id="cb68-21"><a href="#cb68-21" tabindex="-1"></a><span class="co">#> ! <vctrs_meter> * <vctrs_meter> is not permitted</span></span></code></pre></div> <p>Next we write the pair of methods for arithmetic with a meter and a number. These are almost identical, but while <code>meter(10) / 2</code> makes sense, <code>2 / meter(10)</code> does not (and neither do addition and subtraction). To support both doubles and integers as operands, we dispatch over <code>numeric</code> here instead of <code>double</code>.</p> <div class="sourceCode" id="cb69"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb69-1"><a href="#cb69-1" tabindex="-1"></a>vec_arith.vctrs_meter.numeric <span class="ot"><-</span> <span class="cf">function</span>(op, x, y, ...) {</span> <span id="cb69-2"><a href="#cb69-2" tabindex="-1"></a> <span class="cf">switch</span>(</span> <span id="cb69-3"><a href="#cb69-3" tabindex="-1"></a> op,</span> <span id="cb69-4"><a href="#cb69-4" tabindex="-1"></a> <span class="st">"/"</span> <span class="ot">=</span> ,</span> <span id="cb69-5"><a href="#cb69-5" tabindex="-1"></a> <span class="st">"*"</span> <span class="ot">=</span> <span class="fu">new_meter</span>(<span class="fu">vec_arith_base</span>(op, x, y)),</span> <span id="cb69-6"><a href="#cb69-6" tabindex="-1"></a> <span class="fu">stop_incompatible_op</span>(op, x, y)</span> <span id="cb69-7"><a href="#cb69-7" tabindex="-1"></a> )</span> <span id="cb69-8"><a href="#cb69-8" tabindex="-1"></a>}</span> <span id="cb69-9"><a href="#cb69-9" tabindex="-1"></a>vec_arith.numeric.vctrs_meter <span class="ot"><-</span> <span class="cf">function</span>(op, x, y, ...) {</span> <span id="cb69-10"><a href="#cb69-10" tabindex="-1"></a> <span class="cf">switch</span>(</span> <span id="cb69-11"><a href="#cb69-11" tabindex="-1"></a> op,</span> <span id="cb69-12"><a href="#cb69-12" tabindex="-1"></a> <span class="st">"*"</span> <span class="ot">=</span> <span class="fu">new_meter</span>(<span class="fu">vec_arith_base</span>(op, x, y)),</span> <span id="cb69-13"><a href="#cb69-13" tabindex="-1"></a> <span class="fu">stop_incompatible_op</span>(op, x, y)</span> <span id="cb69-14"><a href="#cb69-14" tabindex="-1"></a> )</span> <span id="cb69-15"><a href="#cb69-15" tabindex="-1"></a>}</span> <span id="cb69-16"><a href="#cb69-16" tabindex="-1"></a></span> <span id="cb69-17"><a href="#cb69-17" tabindex="-1"></a><span class="fu">meter</span>(<span class="dv">2</span>) <span class="sc">*</span> <span class="dv">10</span></span> <span id="cb69-18"><a href="#cb69-18" tabindex="-1"></a><span class="co">#> <vctrs_meter[1]></span></span> <span id="cb69-19"><a href="#cb69-19" tabindex="-1"></a><span class="co">#> [1] 20 m</span></span> <span id="cb69-20"><a href="#cb69-20" tabindex="-1"></a><span class="fu">meter</span>(<span class="dv">2</span>) <span class="sc">*</span> <span class="fu">as.integer</span>(<span class="dv">10</span>)</span> <span id="cb69-21"><a href="#cb69-21" tabindex="-1"></a><span class="co">#> <vctrs_meter[1]></span></span> <span id="cb69-22"><a href="#cb69-22" tabindex="-1"></a><span class="co">#> [1] 20 m</span></span> <span id="cb69-23"><a href="#cb69-23" tabindex="-1"></a><span class="dv">10</span> <span class="sc">*</span> <span class="fu">meter</span>(<span class="dv">2</span>)</span> <span id="cb69-24"><a href="#cb69-24" tabindex="-1"></a><span class="co">#> <vctrs_meter[1]></span></span> <span id="cb69-25"><a href="#cb69-25" tabindex="-1"></a><span class="co">#> [1] 20 m</span></span> <span id="cb69-26"><a href="#cb69-26" tabindex="-1"></a><span class="fu">meter</span>(<span class="dv">20</span>) <span class="sc">/</span> <span class="dv">10</span></span> <span id="cb69-27"><a href="#cb69-27" tabindex="-1"></a><span class="co">#> <vctrs_meter[1]></span></span> <span id="cb69-28"><a href="#cb69-28" tabindex="-1"></a><span class="co">#> [1] 2 m</span></span> <span id="cb69-29"><a href="#cb69-29" tabindex="-1"></a><span class="dv">10</span> <span class="sc">/</span> <span class="fu">meter</span>(<span class="dv">20</span>)</span> <span id="cb69-30"><a href="#cb69-30" tabindex="-1"></a><span class="co">#> Error in `vec_arith()`:</span></span> <span id="cb69-31"><a href="#cb69-31" tabindex="-1"></a><span class="co">#> ! <double> / <vctrs_meter> is not permitted</span></span> <span id="cb69-32"><a href="#cb69-32" tabindex="-1"></a><span class="fu">meter</span>(<span class="dv">20</span>) <span class="sc">+</span> <span class="dv">10</span></span> <span id="cb69-33"><a href="#cb69-33" tabindex="-1"></a><span class="co">#> Error in `vec_arith()`:</span></span> <span id="cb69-34"><a href="#cb69-34" tabindex="-1"></a><span class="co">#> ! <vctrs_meter> + <double> is not permitted</span></span></code></pre></div> <p>For completeness, we also need <code>vec_arith.vctrs_meter.MISSING</code> for the unary <code>+</code> and <code>-</code> operators:</p> <div class="sourceCode" id="cb70"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb70-1"><a href="#cb70-1" tabindex="-1"></a>vec_arith.vctrs_meter.MISSING <span class="ot"><-</span> <span class="cf">function</span>(op, x, y, ...) {</span> <span id="cb70-2"><a href="#cb70-2" tabindex="-1"></a> <span class="cf">switch</span>(op,</span> <span id="cb70-3"><a href="#cb70-3" tabindex="-1"></a> <span class="st">`</span><span class="at">-</span><span class="st">`</span> <span class="ot">=</span> x <span class="sc">*</span> <span class="sc">-</span><span class="dv">1</span>,</span> <span id="cb70-4"><a href="#cb70-4" tabindex="-1"></a> <span class="st">`</span><span class="at">+</span><span class="st">`</span> <span class="ot">=</span> x,</span> <span id="cb70-5"><a href="#cb70-5" tabindex="-1"></a> <span class="fu">stop_incompatible_op</span>(op, x, y)</span> <span id="cb70-6"><a href="#cb70-6" tabindex="-1"></a> )</span> <span id="cb70-7"><a href="#cb70-7" tabindex="-1"></a>}</span> <span id="cb70-8"><a href="#cb70-8" tabindex="-1"></a><span class="sc">-</span><span class="fu">meter</span>(<span class="dv">1</span>)</span> <span id="cb70-9"><a href="#cb70-9" tabindex="-1"></a><span class="co">#> <vctrs_meter[1]></span></span> <span id="cb70-10"><a href="#cb70-10" tabindex="-1"></a><span class="co">#> [1] -1 m</span></span> <span id="cb70-11"><a href="#cb70-11" tabindex="-1"></a><span class="sc">+</span><span class="fu">meter</span>(<span class="dv">1</span>)</span> <span id="cb70-12"><a href="#cb70-12" tabindex="-1"></a><span class="co">#> <vctrs_meter[1]></span></span> <span id="cb70-13"><a href="#cb70-13" tabindex="-1"></a><span class="co">#> [1] 1 m</span></span></code></pre></div> </div> </div> <div id="implementing-a-vctrs-s3-class-in-a-package" class="section level2"> <h2>Implementing a vctrs S3 class in a package</h2> <p>Defining S3 methods interactively is fine for iteration and exploration, but if your class lives in a package, you need to do a few more things:</p> <ul> <li><p>Register the S3 methods by listing them in the <code>NAMESPACE</code> file.</p></li> <li><p>Create documentation around your methods, for the sake of your user and to satisfy <code>R CMD check</code>.</p></li> </ul> <p>Let’s assume that the <code>percent</code> class is implemented in the pizza package in the file <code>R/percent.R</code>. Here we walk through the major sections of this hypothetical file. You’ve seen all of this code before, but now it’s augmented by the roxygen2 directives that produce the correct <code>NAMESPACE</code> entries and help topics.</p> <div id="getting-started" class="section level3"> <h3>Getting started</h3> <p>First, the pizza package needs to include vctrs in the <code>Imports</code> section of its <code>DESCRIPTION</code> (perhaps by calling <code>usethis::use_package("vctrs")</code>. While vctrs is under very active development, it probably makes sense to state a minimum version.</p> <pre><code>Imports: a_package, another_package, ... vctrs (>= x.y.z), ...</code></pre> <p>Then we make all vctrs functions available within the pizza package by including the directive <code>#' @import vctrs</code> somewhere. Usually, it’s not good practice to <code>@import</code> the entire namespace of a package, but vctrs is deliberately designed with this use case in mind.</p> <p>Where should we put <code>#' @import vctrs</code>? There are two natural locations:</p> <ul> <li><p>With package-level docs in <code>R/pizza-doc.R</code>. You can use <code>usethis::use_package_doc()</code> to initiate this package-level documentation.</p></li> <li><p>In <code>R/percent.R</code>. This makes the most sense when the vctrs S3 class is a modest and self-contained part of the overall package.</p></li> </ul> <p>We also must use one of these locations to dump some internal documentation that’s needed to avoid <code>R CMD check</code> complaints. We don’t expect any human to ever read this documentation. Here’s how this dummy documentation should look, combined with the <code>#' @import vctrs</code> directive described above.</p> <div class="sourceCode" id="cb72"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb72-1"><a href="#cb72-1" tabindex="-1"></a><span class="co">#' Internal vctrs methods</span></span> <span id="cb72-2"><a href="#cb72-2" tabindex="-1"></a><span class="co">#'</span></span> <span id="cb72-3"><a href="#cb72-3" tabindex="-1"></a><span class="co">#' @import vctrs</span></span> <span id="cb72-4"><a href="#cb72-4" tabindex="-1"></a><span class="co">#' @keywords internal</span></span> <span id="cb72-5"><a href="#cb72-5" tabindex="-1"></a><span class="co">#' @name pizza-vctrs</span></span> <span id="cb72-6"><a href="#cb72-6" tabindex="-1"></a><span class="cn">NULL</span></span></code></pre></div> <p>This should appear in <code>R/pizza-doc.R</code> (package-level docs) or in <code>R/percent.R</code> (class-focused file).</p> <p>Remember to call <code>devtools::document()</code> regularly, as you develop, to regenerate <code>NAMESPACE</code> and the <code>.Rd</code> files.</p> <p>From this point on, the code shown is expected to appear in <code>R/percent.R</code>.</p> </div> <div id="low-level-and-user-friendly-constructors" class="section level3"> <h3>Low-level and user-friendly constructors</h3> <p>Next we add our constructor:</p> <div class="sourceCode" id="cb73"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb73-1"><a href="#cb73-1" tabindex="-1"></a>new_percent <span class="ot"><-</span> <span class="cf">function</span>(<span class="at">x =</span> <span class="fu">double</span>()) {</span> <span id="cb73-2"><a href="#cb73-2" tabindex="-1"></a> <span class="cf">if</span> (<span class="sc">!</span><span class="fu">is_double</span>(x)) {</span> <span id="cb73-3"><a href="#cb73-3" tabindex="-1"></a> <span class="fu">abort</span>(<span class="st">"`x` must be a double vector."</span>)</span> <span id="cb73-4"><a href="#cb73-4" tabindex="-1"></a> }</span> <span id="cb73-5"><a href="#cb73-5" tabindex="-1"></a> <span class="fu">new_vctr</span>(x, <span class="at">class =</span> <span class="st">"pizza_percent"</span>)</span> <span id="cb73-6"><a href="#cb73-6" tabindex="-1"></a>}</span></code></pre></div> <p>Note that the name of the package must be included in the class name (<code>pizza_percent</code>), but it does not need to be included in the constructor name. You do not need to export the constructor, unless you want people to extend your class.</p> <p>We can also add a call to <code>setOldClass()</code> for compatibility with S4:</p> <div class="sourceCode" id="cb74"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb74-1"><a href="#cb74-1" tabindex="-1"></a><span class="co"># for compatibility with the S4 system</span></span> <span id="cb74-2"><a href="#cb74-2" tabindex="-1"></a>methods<span class="sc">::</span><span class="fu">setOldClass</span>(<span class="fu">c</span>(<span class="st">"pizza_percent"</span>, <span class="st">"vctrs_vctr"</span>))</span></code></pre></div> <p>Because we’ve used a function from the methods package, you’ll also need to add methods to <code>Imports</code>, with (e.g.) <code>usethis::use_package("methods")</code>. This is a “free” dependency because methods is bundled with every R install.</p> <p>Next we implement, export, and document a user-friendly helper: <code>percent()</code>.</p> <div class="sourceCode" id="cb75"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb75-1"><a href="#cb75-1" tabindex="-1"></a><span class="co">#' `percent` vector</span></span> <span id="cb75-2"><a href="#cb75-2" tabindex="-1"></a><span class="co">#'</span></span> <span id="cb75-3"><a href="#cb75-3" tabindex="-1"></a><span class="co">#' This creates a double vector that represents percentages so when it is</span></span> <span id="cb75-4"><a href="#cb75-4" tabindex="-1"></a><span class="co">#' printed, it is multiplied by 100 and suffixed with `%`.</span></span> <span id="cb75-5"><a href="#cb75-5" tabindex="-1"></a><span class="co">#'</span></span> <span id="cb75-6"><a href="#cb75-6" tabindex="-1"></a><span class="co">#' @param x A numeric vector</span></span> <span id="cb75-7"><a href="#cb75-7" tabindex="-1"></a><span class="co">#' @return An S3 vector of class `pizza_percent`.</span></span> <span id="cb75-8"><a href="#cb75-8" tabindex="-1"></a><span class="co">#' @export</span></span> <span id="cb75-9"><a href="#cb75-9" tabindex="-1"></a><span class="co">#' @examples</span></span> <span id="cb75-10"><a href="#cb75-10" tabindex="-1"></a><span class="co">#' percent(c(0.25, 0.5, 0.75))</span></span> <span id="cb75-11"><a href="#cb75-11" tabindex="-1"></a>percent <span class="ot"><-</span> <span class="cf">function</span>(<span class="at">x =</span> <span class="fu">double</span>()) {</span> <span id="cb75-12"><a href="#cb75-12" tabindex="-1"></a> x <span class="ot"><-</span> <span class="fu">vec_cast</span>(x, <span class="fu">double</span>())</span> <span id="cb75-13"><a href="#cb75-13" tabindex="-1"></a> <span class="fu">new_percent</span>(x)</span> <span id="cb75-14"><a href="#cb75-14" tabindex="-1"></a>}</span></code></pre></div> <p>(Again note that the package name will appear in the class, but does not need to occur in the function, because we can already do <code>pizza::percent()</code>; it would be redundant to have <code>pizza::pizza_percent()</code>.)</p> </div> <div id="other-helpers" class="section level3"> <h3>Other helpers</h3> <p>It’s a good idea to provide a function that tests if an object is of this class. If you do so, it makes sense to document it with the user-friendly constructor <code>percent()</code>:</p> <div class="sourceCode" id="cb76"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb76-1"><a href="#cb76-1" tabindex="-1"></a><span class="co">#' @export</span></span> <span id="cb76-2"><a href="#cb76-2" tabindex="-1"></a><span class="co">#' @rdname percent</span></span> <span id="cb76-3"><a href="#cb76-3" tabindex="-1"></a>is_percent <span class="ot"><-</span> <span class="cf">function</span>(x) {</span> <span id="cb76-4"><a href="#cb76-4" tabindex="-1"></a> <span class="fu">inherits</span>(x, <span class="st">"pizza_percent"</span>)</span> <span id="cb76-5"><a href="#cb76-5" tabindex="-1"></a>}</span></code></pre></div> <p>You’ll also need to update the <code>percent()</code> documentation to reflect that <code>x</code> now means two different things:</p> <div class="sourceCode" id="cb77"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb77-1"><a href="#cb77-1" tabindex="-1"></a><span class="co">#' @param x</span></span> <span id="cb77-2"><a href="#cb77-2" tabindex="-1"></a><span class="co">#' * For `percent()`: A numeric vector</span></span> <span id="cb77-3"><a href="#cb77-3" tabindex="-1"></a><span class="co">#' * For `is_percent()`: An object to test.</span></span></code></pre></div> <p>Next we provide the key methods to make printing work. These are S3 methods, so they don’t need to be documented, but they do need to be exported.</p> <div class="sourceCode" id="cb78"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb78-1"><a href="#cb78-1" tabindex="-1"></a><span class="co">#' @export</span></span> <span id="cb78-2"><a href="#cb78-2" tabindex="-1"></a>format.pizza_percent <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb78-3"><a href="#cb78-3" tabindex="-1"></a> out <span class="ot"><-</span> <span class="fu">formatC</span>(<span class="fu">signif</span>(<span class="fu">vec_data</span>(x) <span class="sc">*</span> <span class="dv">100</span>, <span class="dv">3</span>))</span> <span id="cb78-4"><a href="#cb78-4" tabindex="-1"></a> out[<span class="fu">is.na</span>(x)] <span class="ot"><-</span> <span class="cn">NA</span></span> <span id="cb78-5"><a href="#cb78-5" tabindex="-1"></a> out[<span class="sc">!</span><span class="fu">is.na</span>(x)] <span class="ot"><-</span> <span class="fu">paste0</span>(out[<span class="sc">!</span><span class="fu">is.na</span>(x)], <span class="st">"%"</span>)</span> <span id="cb78-6"><a href="#cb78-6" tabindex="-1"></a> out</span> <span id="cb78-7"><a href="#cb78-7" tabindex="-1"></a>}</span> <span id="cb78-8"><a href="#cb78-8" tabindex="-1"></a></span> <span id="cb78-9"><a href="#cb78-9" tabindex="-1"></a><span class="co">#' @export</span></span> <span id="cb78-10"><a href="#cb78-10" tabindex="-1"></a>vec_ptype_abbr.pizza_percent <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb78-11"><a href="#cb78-11" tabindex="-1"></a> <span class="st">"prcnt"</span></span> <span id="cb78-12"><a href="#cb78-12" tabindex="-1"></a>}</span></code></pre></div> <p>Finally, we implement methods for <code>vec_ptype2()</code> and <code>vec_cast()</code>.</p> <div class="sourceCode" id="cb79"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb79-1"><a href="#cb79-1" tabindex="-1"></a><span class="co">#' @export</span></span> <span id="cb79-2"><a href="#cb79-2" tabindex="-1"></a>vec_ptype2.vctrs_percent.vctrs_percent <span class="ot"><-</span> <span class="cf">function</span>(x, y, ...) <span class="fu">new_percent</span>()</span> <span id="cb79-3"><a href="#cb79-3" tabindex="-1"></a><span class="co">#' @export</span></span> <span id="cb79-4"><a href="#cb79-4" tabindex="-1"></a>vec_ptype2.double.vctrs_percent <span class="ot"><-</span> <span class="cf">function</span>(x, y, ...) <span class="fu">double</span>()</span> <span id="cb79-5"><a href="#cb79-5" tabindex="-1"></a></span> <span id="cb79-6"><a href="#cb79-6" tabindex="-1"></a><span class="co">#' @export</span></span> <span id="cb79-7"><a href="#cb79-7" tabindex="-1"></a>vec_cast.pizza_percent.pizza_percent <span class="ot"><-</span> <span class="cf">function</span>(x, to, ...) x</span> <span id="cb79-8"><a href="#cb79-8" tabindex="-1"></a><span class="co">#' @export</span></span> <span id="cb79-9"><a href="#cb79-9" tabindex="-1"></a>vec_cast.pizza_percent.double <span class="ot"><-</span> <span class="cf">function</span>(x, to, ...) <span class="fu">percent</span>(x)</span> <span id="cb79-10"><a href="#cb79-10" tabindex="-1"></a><span class="co">#' @export</span></span> <span id="cb79-11"><a href="#cb79-11" tabindex="-1"></a>vec_cast.double.pizza_percent <span class="ot"><-</span> <span class="cf">function</span>(x, to, ...) <span class="fu">vec_data</span>(x)</span></code></pre></div> </div> <div id="arithmetic-1" class="section level3"> <h3>Arithmetic</h3> <p>Writing double dispatch methods for <code>vec_arith()</code> is currently more awkward than writing them for <code>vec_ptype2()</code> or <code>vec_cast()</code>. We plan to improve this in the future. For now, you can use the following instructions.</p> <p>If you define a new type and want to write <code>vec_arith()</code> methods for it, you’ll need to provide a new single dispatch S3 generic for it of the following form:</p> <div class="sourceCode" id="cb80"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb80-1"><a href="#cb80-1" tabindex="-1"></a><span class="co">#' @export</span></span> <span id="cb80-2"><a href="#cb80-2" tabindex="-1"></a><span class="co">#' @method vec_arith my_type</span></span> <span id="cb80-3"><a href="#cb80-3" tabindex="-1"></a>vec_arith.my_type <span class="ot"><-</span> <span class="cf">function</span>(op, x, y, ...) {</span> <span id="cb80-4"><a href="#cb80-4" tabindex="-1"></a> <span class="fu">UseMethod</span>(<span class="st">"vec_arith.my_type"</span>, y)</span> <span id="cb80-5"><a href="#cb80-5" tabindex="-1"></a>}</span></code></pre></div> <p>Note that this actually functions as both an S3 method for <code>vec_arith()</code> and an S3 generic called <code>vec_arith.my_type()</code> that dispatches off <code>y</code>. roxygen2 only recognizes it as an S3 generic, so you have to register the S3 method part of this with an explicit <code>@method</code> call.</p> <p>After that, you can define double dispatch methods, but you still need an explicit <code>@method</code> tag to ensure it is registered with the correct generic:</p> <div class="sourceCode" id="cb81"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb81-1"><a href="#cb81-1" tabindex="-1"></a><span class="co">#' @export</span></span> <span id="cb81-2"><a href="#cb81-2" tabindex="-1"></a><span class="co">#' @method vec_arith.my_type my_type</span></span> <span id="cb81-3"><a href="#cb81-3" tabindex="-1"></a>vec_arith.my_type.my_type <span class="ot"><-</span> <span class="cf">function</span>(op, x, y, ...) {</span> <span id="cb81-4"><a href="#cb81-4" tabindex="-1"></a> <span class="co"># implementation here</span></span> <span id="cb81-5"><a href="#cb81-5" tabindex="-1"></a>}</span> <span id="cb81-6"><a href="#cb81-6" tabindex="-1"></a></span> <span id="cb81-7"><a href="#cb81-7" tabindex="-1"></a><span class="co">#' @export</span></span> <span id="cb81-8"><a href="#cb81-8" tabindex="-1"></a><span class="co">#' @method vec_arith.my_type integer</span></span> <span id="cb81-9"><a href="#cb81-9" tabindex="-1"></a>vec_arith.my_type.integer <span class="ot"><-</span> <span class="cf">function</span>(op, x, y, ...) {</span> <span id="cb81-10"><a href="#cb81-10" tabindex="-1"></a> <span class="co"># implementation here</span></span> <span id="cb81-11"><a href="#cb81-11" tabindex="-1"></a>}</span> <span id="cb81-12"><a href="#cb81-12" tabindex="-1"></a></span> <span id="cb81-13"><a href="#cb81-13" tabindex="-1"></a><span class="co">#' @export</span></span> <span id="cb81-14"><a href="#cb81-14" tabindex="-1"></a><span class="co">#' @method vec_arith.integer my_type</span></span> <span id="cb81-15"><a href="#cb81-15" tabindex="-1"></a>vec_arith.integer.my_type <span class="ot"><-</span> <span class="cf">function</span>(op, x, y, ...) {</span> <span id="cb81-16"><a href="#cb81-16" tabindex="-1"></a> <span class="co"># implementation here</span></span> <span id="cb81-17"><a href="#cb81-17" tabindex="-1"></a>}</span></code></pre></div> <p>vctrs provides the hybrid S3 generics/methods for most of the base R types, like <code>vec_arith.integer()</code>. If you don’t fully import vctrs with <code>@import vctrs</code>, then you will need to explicitly import the generic you are registering double dispatch methods for with <code>@importFrom vctrs vec_arith.integer</code>.</p> </div> <div id="testing" class="section level3"> <h3>Testing</h3> <p>It’s good practice to test your new class. Specific recommendations:</p> <ul> <li><p><code>R/percent.R</code> is the type of file where you really do want 100% test coverage. You can use <code>devtools::test_coverage_file()</code> to check this.</p></li> <li><p>Make sure to test behaviour with zero-length inputs and missing values.</p></li> <li><p>Use <code>testthat::verify_output()</code> to test your format method. Customised printing is often a primary motivation for creating your own S3 class in the first place, so this will alert you to unexpected changes in your printed output. Read more about <code>verify_output()</code> in the <a href="https://www.tidyverse.org/blog/2019/11/testthat-2-3-0/">testthat v2.3.0 blog post</a>; it’s an example of a so-called <a href="https://ro-che.info/articles/2017-12-04-golden-tests">golden test</a>.</p></li> <li><p>Check for method symmetry; use <code>expect_s3_class()</code>, probably with <code>exact = TRUE</code>, to ensure that <code>vec_c(x, y)</code> and <code>vec_c(y, x)</code> return the same type of output for the important <code>x</code>s and <code>y</code>s in your domain.</p></li> <li><p>Use <code>testthat::expect_error()</code> to check that inputs that can’t be combined fail with an error. Here, you should be generally checking the class of the error, not its message. Relevant classes include <code>vctrs_error_assert_ptype</code>, <code>vctrs_error_assert_size</code>, and <code>vctrs_error_incompatible_type</code>.</p> <div class="sourceCode" id="cb82"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb82-1"><a href="#cb82-1" tabindex="-1"></a><span class="fu">expect_error</span>(<span class="fu">vec_c</span>(<span class="dv">1</span>, <span class="st">"a"</span>), <span class="at">class =</span> <span class="st">"vctrs_error_incompatible_type"</span>)</span></code></pre></div></li> </ul> <p>If your tests pass when run by <code>devtools::test()</code>, but fail when run in <code>R CMD check</code>, it is very likely to reflect a problem with S3 method registration. Carefully check your roxygen2 comments and the generated <code>NAMESPACE</code>.</p> </div> <div id="existing-classes" class="section level3"> <h3>Existing classes</h3> <p>Before you build your own class, you might want to consider using, or subclassing existing classes. You can check <a href="https://github.com/krlmlr/awesome-vctrs">awesome-vctrs</a> for a curated list of R vector classes, some of which are built with vctrs.</p> <p>If you’ve built or extended a class, consider adding it to that list so other people can use it.</p> </div> </div> <!-- code folding --> <!-- dynamically load mathjax for compatibility with self-contained --> <script> (function () { var script = document.createElement("script"); script.type = "text/javascript"; script.src = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"; document.getElementsByTagName("head")[0].appendChild(script); })(); </script> </body> </html>