<h3>TL;DR</h3>
<blockquote>
<ul>
<li>C++ templates and function overloading are incompatible with R’s C API, so<br>
polymorphism must be achieved via run-time dispatch, handled explicitly by<br>
the programmer.</li>
<li>The traditional technique for operating on <code>SEXP</code> objects in a generic<br>
manner entails a great deal of boilerplate code, which can be unsightly,<br>
unmaintainable, and error-prone.</li>
<li>The desire to provide polymorphic functions which operate on vectors<br>
and matrices is common enough that Rcpp provides the utility macros<br>
<code>RCPP_RETURN_VECTOR</code> and <code>RCPP_RETURN_MATRIX</code> to simplify the process.</li>
<li>Subsequently, these macros were extended to handle an (essentially)<br>
arbitrary number of arguments, provided that a C++11 compiler is used.</li>
</ul>
</blockquote>
<hr>
<h3>Background</h3>
<p>To motivate a discussion of polymorphic functions, imagine that we desire a<br>
function (<code>ends</code>) which, given an input vector <code>x</code> and an integer <code>n</code>, returns<br>
a vector containing the first and last <code>n</code> elements of <code>x</code> concatenated.<br>
Furthermore, we require <code>ends</code> to be a single interface which is capable of<br>
handling multiple types of input vectors (integers, floating point values,<br>
strings, etc.), rather than having a separate function for each case. How can<br>
this be achieved?</p>
<h4>R Implementation</h4>
<p>A naïve implementation in R might look something like this:</p>
<figure>
<pre><code data-lang="r"><span>ends</span><span> </span><span>&lt;-</span><span> </span><span>function</span><span>(</span><span>x</span><span>,</span><span> </span><span>n</span><span> </span><span>=</span><span> </span><span>6L</span><span>)</span><span> </span><span>{</span><span>
</span><span>n</span><span> </span><span>&lt;-</span><span> </span><span>min</span><span>(</span><span>n</span><span>,</span><span> </span><span>length</span><span>(</span><span>x</span><span>)</span><span> </span><span>%/%</span><span> </span><span>2</span><span>)</span><span>
</span><span>c</span><span>(</span><span>head</span><span>(</span><span>x</span><span>,</span><span> </span><span>n</span><span>),</span><span> </span><span>tail</span><span>(</span><span>x</span><span>,</span><span> </span><span>n</span><span>))</span><span>
</span><span>}</span><span>
</span><span>ends</span><span>(</span><span>1</span><span>:</span><span>9</span><span>)</span></code></pre>
</figure>
<pre>
[1] 1 2 3 4 6 7 8 9
</pre>
<figure>
<pre><code data-lang="r"><span>ends</span><span>(</span><span>letters</span><span>,</span><span> </span><span>3</span><span>)</span></code></pre>
</figure>
<pre>
[1] &quot;a&quot; &quot;b&quot; &quot;c&quot; &quot;x&quot; &quot;y&quot; &quot;z&quot;
</pre>
<figure>
<pre><code data-lang="r"><span>ends</span><span>(</span><span>rnorm</span><span>(</span><span>20</span><span>),</span><span> </span><span>2</span><span>)</span></code></pre>
</figure>
<pre>
[1] -0.560476 -0.230177  0.701356 -0.472791
</pre>
<p>The simple function above demonstates a key feature of many dynamically-typed<br>
programming languages, one which has undoubtably been a significant factor in their<br>
rise to popularity: the ability to write generic code with little-to-no<br>
additional effort on the part of the developer. Without getting into a discussion<br>
of the pros and cons of static vs. dynamic typing, it is evident that being able<br>
to dispatch a single function generically on multiple object types, as opposed to,<br>
e.g. having to manage separate impementations of <code>ends</code> for each vector type,<br>
helps us to write more concise, expressive code. Being an article about Rcpp,<br>
however, the story does not end here, and we consider how this problem might<br>
be approached in C++, which has a <em>much</em> more strict type system than R.</p>
<h4>C++ Implementation(s)</h4>
<p>For simplicity, we begin by considering solutions in the context of a “pure”<br>
(re: not called from R) C++ program. Eschewing more complicated tactics<br>
involving run-time dispatch (<code>virtual</code> functions, etc.), the C++ language<br>
provides us with two straightforward methods of achieving this at compile time:</p>
<ol>
<li>Function Overloading (<a rel="nofollow" href="https://en.wikipedia.org/wiki/Ad_hoc_polymorphism" target="_blank">ad hoc polymorphism</a>)</li>
<li>Templates (<a rel="nofollow" href="https://en.wikipedia.org/wiki/Parametric_polymorphism" target="_blank">parametric polymorphism</a>)</li>
</ol>
<p>The first case can be demonstrated as follows:</p>
<figure>
<pre><code data-lang="cpp"><span>#include </span></code></pre></figure>