Rcpp-FAQ.Rmd

---
title: \pkg{Rcpp} FAQ

# Use letters for affiliations
author:
  - name: Dirk Eddelbuettel
    affiliation: a
  - name: Romain François
    affiliation: b

address:
  - code: a
    address: \url{http://dirk.eddelbuettel.com}
  - code: b
    address: \url{https://romain.rbind.io/}

# For footer text
lead_author_surname: Eddelbuettel and François

# Place DOI URL or CRAN Package URL here
doi: "https://cran.r-project.org/package=Rcpp"

# Abstract
abstract: |
  This document attempts to answer the most Frequently Asked
  Questions (FAQ) regarding the \pkg{Rcpp}
  \citep{CRAN:Rcpp,JSS:Rcpp,Eddelbuettel:2013:Rcpp} package.

# Optional: Acknowledgements
# acknowledgements: |

# Optional: One or more keywords
keywords:
  - Rcpp
  - FAQ
  - R
  - C++

# Font size of the document, values of 9pt (default), 10pt, 11pt and 12pt
fontsize: 9pt

# Optional: Force one-column layout, default is two-column
#one_column: true

# Optional: Enables lineo mode, but only if one_column mode is also true
#lineno: true

# Optional: Enable one-sided layout, default is two-sided
#one_sided: true

# Optional: Enable section numbering, default is unnumbered
numbersections: true

# Optional: Specify the depth of section number, default is 5
secnumdepth: 5

# Optional: Bibliography
bibliography: Rcpp

# Optional: Enable a 'Draft' watermark on the document
#watermark: false

# Customize footer, eg by referencing the vignette
footer_contents: "Rcpp FAQ Vignette"

# Omit \pnasbreak at end
skip_final_break: true

# Produce a pinp document
output:
    pinp::pinp:
        collapse: true

header-includes: >
  \newcommand{\proglang}[1]{\textsf{#1}}
  \newcommand{\pkg}[1]{\textbf{#1}}
  \newcommand{\faq}[1]{FAQ~\ref{#1}}
  \newcommand{\rdoc}[2]{\href{http://www.rdocumentation.org/packages/#1/functions/#2}{\code{#2}}}

vignette: >
  %\VignetteIndexEntry{Rcpp-FAQ}
  %\VignetteKeywords{Rcpp, FAQ, R, Cpp}
  %\VignettePackage{Rcpp}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

\tableofcontents

```{r setup, include=FALSE}
knitr::opts_chunk$set(cache=FALSE)
library(Rcpp)
library(inline)
options("width"=50, digits=5)
```

# Getting started

## How do I get started

If you have \pkg{Rcpp} installed, please execute the following command
in \proglang{R} to access the introductory vignette (which is a
variant of the \citet{JSS:Rcpp} and \citet{PeerJ:Rcpp,TAS:Rcpp} papers) for a
detailed introduction, ideally followed by at least the Rcpp
Attributes \citep{CRAN:Rcpp:Attributes} vignette:

```{r, eval=FALSE}
vignette("Rcpp-jss-2011")
vignette("Rcpp-introduction")
vignette("Rcpp-attributes")
```

If you do not have \pkg{Rcpp} installed, these documents should also be available
whereever you found this document, \textsl{i.e.,} on every mirror site of CRAN.

## What do I need

Obviously, \proglang{R} must be installed. \pkg{Rcpp} provides a
\proglang{C++} API as an extension to the \proglang{R} system.  As such, it
is bound by the choices made by \proglang{R} and is also influenced by how
\proglang{R} is configured.

In general, the standard environment for building a CRAN package from source
(particularly when it contains \proglang{C} or \proglang{C++} code) is required. This
means one needs:

- a development environment with a suitable compiler (see
  below), header files and required libraries;
- \proglang{R} should be built in a way that permits linking and possibly
  embedding of \proglang{R}; this is typically ensured by the
  `--enable-shared-lib` option;
- standard development tools such as `make` etc.

Also see the [RStudio documentation](http://www.rstudio.com/ide/docs/packages/prerequisites)
on pre-requisites for R package development.

## What compiler can I use {#q:what-compiler}

On almost all platforms, the GNU Compiler Collection (or `gcc`, which is also
the name of its \proglang{C} language compiler) can be used along with the
corresponding `g++` compiler for the \proglang{C++} language. Depending on
which C++ compilation standard one wishes to use, a suitably recent variant
of the compiler may be needed. But these days the minimum standard of C++11
is generally available, and the default compilers on all the common platforms
are now suitable.

Specific per-platform notes:

\begin{description}
  \item[Windows] users need the \texttt{Rtools} package from the site maintained by
    Tomas Kalibera which contains all the required tools in a single package;
    complete instructions specific to Windows are in the "R Administration"
    manual \citep[Appendix D]{R:Administration}.
  \item[macOS] users, as noted in the "R Administration" manual \citep[Appendix
    C.4]{R:Administration}, need to install the Apple Developer Tools
    (\textsl{e.g.}, \href{https://developer.apple.com/library/ios/technotes/tn2339/_index.html}{Xcode Command Line Tools}  (as well as \texttt{gfortran} if \proglang{R} or
    Fortran-using packages are to be built); also see \faq{q:OSX} and
    \faq{q:OSXArma} below. This is frustratingly moving target; consult
    the \code{r-sig-mac} list (and its archives) for (current) details.
  \item[Linux] user need to install the standard developement packages. Some
    distributions provide helper packages which pull in all the required
    packages; the \texttt{r-base-dev} package on Debian and Ubuntu is an example.
\end{description}

The `clang` and `clang++` compilers from the LLVM project can
also be used. On Linux, they are inter-operable with `gcc` et al. On
macOS, they are unfortunately not ABI compatible.

In general, any compiler supported by R itself can be used.

## What other packages are useful

Additional packages that we have found useful are \pkg{inline} if one wants
to create compiled functions _without_ the help of \pkg{Rcpp} as well as the different benchmarking
and unit testing packages. A short list follows, it is not meant to be
exhaustive as CRAN by now has \textsl{many} helpful packages:

\begin{description}
\item[\pkg{inline}] which is invaluable for direct compilation, linking and loading
  of short code snippets---but now effectively superseded by the Rcpp
  Attributes (see \faq{using-attributes} and
  \faq{prototype-using-attributes}) feature provided by \pkg{Rcpp};
  \item[\pkg{RUnit}, \pkg{tinytest}, \pkg{testthat}] can be used for unit
  testing; \pkg{Rcpp} uses \pkg{tinytest} as it is ligthweight and installs the
  tests along with the package by default but note that no testing package is
  \textsl{required}: all are optional;
\item[\pkg{rbenchmark}, \pkg{microbenchmark}] to run simple timing
  comparisons and benchmarks; they are also  recommended but not required.
\end{description}

## What licenses can I choose for my code

The \pkg{Rcpp} package is licensed under the terms of the
[GNU GPL 2 or later](http://www.gnu.org/licenses/gpl-2.0.html), just like
\proglang{R} itself. A key goal of the \pkg{Rcpp} package is to make
extending \proglang{R} more seamless.  But by \textsl{linking} your code against
\proglang{R} (as well as \pkg{Rcpp}), the combination is bound by the GPL as
well.  This is very clearly
stated at the
[FSF website](https://www.gnu.org/licenses/gpl-faq.html#GPLStaticVsDynamic):

> Linking a GPL covered work statically or dynamically with other modules is
> making a combined work based on the GPL covered work. Thus, the terms and
> conditions of the GNU General Public License cover the whole combination.

So you are free to license your work under whichever terms you find suitable
(provided they are GPL-compatible, see the
[FSF site for details](http://www.gnu.org/licenses/licenses.html)). However,
the combined work will remain under the terms and conditions of the GNU General
Public License.  This restriction comes from both \proglang{R} which is GPL-licensed
as well as from \pkg{Rcpp} and whichever other GPL-licensed components you may
be linking against.


# Compiling and Linking

## How do I use \pkg{Rcpp} in my package {#make-package}

\pkg{Rcpp} has been specifically designed to be used by other packages.
Making a package that uses \pkg{Rcpp} depends on the same mechanics that are
involved in making any \proglang{R} package that use compiled code --- so
reading the \textsl{Writing R Extensions} manual \citep{R:Extensions} is a required
first step.

Further steps, specific to \pkg{Rcpp}, are described in a separate vignette.

```{r, eval=FALSE}
vignette("Rcpp-package")
```

## How do I quickly prototype my code

There are two toolchains which can help with this:

- The older one is provided by the \pkg{inline} package and described in
  Section~\ref{using-inline}.
- Starting with \pkg{Rcpp} 0.10.0, the Rcpp Attributes feature (described
  in Section~\ref{using-attributes}) offered an even easier alternative via
  the function \rdoc{Rcpp}{evalCpp}, \rdoc{Rcpp}{cppFunction} and
  \rdoc{Rcpp}{sourceCpp}.

The next two subsections show an example each.

### Using inline

The \pkg{inline} package \citep{CRAN:inline} provides the functions
\rdoc{inline}{cfunction} and \rdoc{inline}{cxxfunction}. Below is a simple
function that uses `accumulate` from the (\proglang{C++}) Standard
Template Library to sum the elements of a numeric vector.

```{r}
fx <- cxxfunction(signature(x = "numeric"),
  'NumericVector xx(x);
   return wrap(std::accumulate(xx.begin(),
                               xx.end(), 0.0));',
   plugin = "Rcpp")
res <- fx(seq(1, 10, by=0.5))
res
```

One might want to use code that lives in a \proglang{C++} file instead of writing
the code in a character string in R. This is easily achieved by using
\rdoc{base}{readLines}:

```{r, eval=FALSE}
fx <- cxxfunction(signature(),
                  paste(readLines("myfile.cpp"),
                        collapse="\n"),
                  plugin = "Rcpp")
```

The `verbose` argument of \rdoc{inline}{cxxfunction} is very
useful as it shows how \pkg{inline} runs the show.

### Using Rcpp Attributes {#using-attributes}

Rcpp Attributes \citep{CRAN:Rcpp:Attributes}, and also discussed in
\faq{prototype-using-attributes} below, permits an even easier
route to integrating R and C++.  It provides three key functions.
First, \rdoc{Rcpp}{evalCpp} provide a means to evaluate simple C++
expression which is often useful for small tests, or to simply check
if the toolchain is set up correctly. Second, \rdoc{Rcpp}{cppFunction}
can be used to create C++ functions for R use on the fly.  Third,
`Rcpp::sourceCpp` can integrate entire files in order to define
multiple functions.

The example above can now be rewritten as:

```{r}
cppFunction('double accu(NumericVector x) {
  return(std::accumulate(x.begin(), x.end(), 0.0));
}')
res <- accu(seq(1, 10, by=0.5))
res
```

The \rdoc{Rcpp}{cppFunction} parses the supplied text, extracts the desired
function names, creates the required scaffolding, compiles, links and loads
the supplied code and makes it available under the selected identifier.

Similarly, \rdoc{Rcpp}{sourceCpp} can read in a file and compile, link and load
the code therein.

## How do I convert my prototyped code to a package {#from-inline-to-package}

Since release 0.3.5 of \pkg{inline}, one can combine \faq{using-inline} and
\faq{make-package}. See `help("package.skeleton-methods")` once
\pkg{inline} is loaded and use the skeleton-generating functionality to
transform a prototyped function into the minimal structure of a package.
After that you can proceed with working on the package in the spirit of
\faq{make-package}.

Rcpp Attributes \citep{CRAN:Rcpp:Attributes} also offers a means to convert
functions written using Rcpp Attributes into a function via the
\rdoc{Rdoc}{compileAttributes} function; see the vignette for details.

## How do I quickly prototype my code in a package {#using-a-package}

The simplest way may be to work directly with a package.  Changes to both the
\proglang{R} and \proglang{C++} code can be compiled and tested from the
command line via:

```{bash, eval = FALSE}
$ R CMD INSTALL mypkg && \
     Rscript --default-packages=mypkg -e \
         'someFunctionToTickle(3.14)'
```

This first installs the packages, and then uses the command-line tool
\rdoc{utils}{Rscript} (which ships with `R`) to load the package, and execute
the \proglang{R} expression following the `-e` switch. Such an
expression can contain multiple statements separated by semicolons.
\rdoc{utils}{Rscript} is available on all three core operating systems.

On Linux, one can also use `r` from the `littler` package
\citep{CRAN:littler} which is an alternative front end to \proglang{R}
designed for both `#!` (hashbang) scripting and command-line use. It has
slightly faster start-up times than \rdoc{utils}{Rscript}; and both give a
guaranteed clean slate as a new session is created.

The example then becomes

```{bash, eval = FALSE}
$ R CMD INSTALL mypkg && \
     r -l mypkg -e 'someFunctionToTickle(3.14)'
```

The `-l` option calls 'suppressMessages(library(mypkg))' before executing the
\proglang{R} expression. Several packages can be listed, separated by a comma.

More choices are provided by other packages and IDEs. See their respective
documentation for details.

## But I want to compile my code with R CMD SHLIB {#using-r-cmd-shlib}

The recommended way is to create a package and follow \faq{make-package}. The
alternate recommendation is to use \pkg{inline} and follow \faq{using-inline}
because it takes care of all the details.

However, some people have shown that they prefer not to follow recommended
guidelines and compile their code using the traditional `R CMD SHLIB`. To
do so, we need to help `SHLIB` and let it know about the header files
that \pkg{Rcpp} provides and the \proglang{C++} library the code must link
against.

On the Linux command-line, you can do the following:

```{bash, eval = FALSE}
$ export PKG_CXXFLAGS=\
              `Rscript -e "Rcpp:::CxxFlags()"`
$ R CMD SHLIB myfile.cpp
```

which first defines and exports two relevant environment variables which
`R CMD SHLIB` then relies on.  On other operating systems, appropriate
settings may have to be used to define the environment variables.

This approach corresponds to the very earliest ways of building programs and
can still be found in some deprecated documents (as _e.g._ some of
Dirk's older 'Intro to HPC with R' tutorial slides).  It is still not
recommended as there are tools and automation mechanisms that can do the work
for you.

Note that we always need to set `PKG_CXXFLAGS` (or equally `PKG_CPPFLAGS`) to tell R
where the \pkg{Rcpp} headers files are located.

Once `R CMD SHLIB` has created the dyanmically-loadable file (with
extension `.so` on Linux, `.dylib` on macOS or `.dll` on
Windows), it can be loaded in an R session via \rdoc{base}{dyn.load}, and the
function can be executed via \rdoc{base}{.Call}.  Needless to say, we
\emph{strongly} recommend using a package, or at least Rcpp Attributes as
either approach takes care of a lot of these tedious and error-prone manual
steps.


## But R CMD SHLIB still does not work

We have had reports in the past where build failures occurred when users had
non-standard code in their `~/.Rprofile` or `Rprofile.site` (or
equivalent) files.

If such code emits text on `stdout`, the frequent and implicit
invocation of `Rscript -e "..."` (as in \faq{using-r-cmd-shlib}
above) to retrieve settings directly from \pkg{Rcpp} will fail.

You may need to uncomment such non-standard code, or protect it by wrapping
it inside `if (interactive())`, or possibly try to use
`Rscript --vanilla` instead of plain `Rscript`.

## What about `LinkingTo `

\proglang{R} has only limited support for cross-package linkage.

We now employ the `LinkingTo` field of the `DESCRIPTION` file
of packages using \pkg{Rcpp}. But this only helps in having \proglang{R}
compute the location of the header files for us.

The actual library location and argument still needs to be provided by the
user. This topic can get complicated real quickly, and there is an entire
vignette devoted to it, so see \citet{CRAN:Rcpp:Libraries}.

Also note that an important change arrived with \pkg{Rcpp} release 0.11.0 and
concerns the automatic registration of functions; see
Section \ref{function-registration} below.


## Does \pkg{Rcpp} work on windows

Yes of course. See the Windows binaries provided by CRAN.

## Can I use \pkg{Rcpp} with Visual Studio

Not a chance.

And that is not because we are meanies but because \proglang{R} and Visual
Studio simply do not get along. As \pkg{Rcpp} is all about extending
\proglang{R} with \proglang{C++} interfaces, we are bound by the available
toolchain.  And \proglang{R} simply does not compile with Visual Studio. Go
complain to its vendor if you are still upset.

(These days the 'Code' editor derived from it is popular and can of course be
used with \proglang{R} and \pkg{Rcpp}; see its documentation for the required
plugins. Such use still falls back to the default compilers \proglang{R} is
used with on the given system so see \faq{q:what-compiler} above.)

## I am having problems building Rcpp on macOS, any help  {#q:OSX}

There are three known issues regarding Rcpp build problems on macOS.  If you are
building packages with RcppArmadillo, there is yet another issue that is
addressed separately in \faq{q:OSXArma} below.

### Lack of a Compiler

By default, macOS does not ship with an active compiler. Depending on the
\proglang{R} version being used, there are different development environment
setup procedures. For the current \proglang{R} version, we recommend observing
the official procedure used in
[Section 6.3.2 macOS](https://cran.r-project.org/doc/manuals/r-release/R-admin.html#macOS-packages)
and [Section C.3 macOS](https://cran.r-project.org/doc/manuals/r-release/R-admin.html#macOS)
of the [R Installation and Administration](https://cran.r-project.org/doc/manuals/r-release/R-admin.html)
manual.

### Differing macOS R Versions Leading to Binary Failures

There are _three_ (or more) distinct versions of R for macOS.
The first version is a legacy version meant for macOS 10.6 (Snow Leopard) -
10.8 (Mountain Lion). The second version is for more recent system
macOS 10.9 (Mavericks) and 10.10 (Yosemite). Finally, the third and most
up-to-date version supports macOS 10.11 (El Capitan), 10.12 (Sierra), and 10.13 (High Sierra).
The distinction comes as a result of a change in the compilers shipped with the
operating system as highlighted previously. As a result, avoid sending
\textbf{package binaries} to collaborators if they are working on older
operating systems as the \proglang{R} binaries for these versions will not be
able to mix. In such cases, it is better to provide collaborators with the
\textbf{package source} and allow them to build the package locally.

### OpenMP Support

By default, the macOS operating environment lacks the ability to parallelize
sections of code using the [\proglang{OpenMP}
standard](http://openmp.org/wp/).  Within \proglang{R} 3.4.*, the default
developer environment was _changed_ to allow for \proglang{OpenMP} to be used
on macOS by using a non-default toolchain provided by R Core Team maintainers
for macOS.  Having said this, it is still important to protect any reference
to \proglang{OpenMP} as some users may not yet have the ability to use
\proglang{OpenMP}.

To setup the appropriate protection for using \proglang{OpenMP}, the process
is two-fold. First, protect the inclusion of headers with:

```cpp
#ifdef _OPENMP
  #include <omp.h>
#endif
```

Second, when parallelizing portions of code use:

```cpp
#ifdef _OPENMP
    // multithreaded OpenMP version of code
#else
    // single-threaded version of code
#endif
```

Under this approach, the code will be _safely_ parallelized when
support exists for \proglang{OpenMP} on Windows, macOS, and Linux.

### Additional Information and Help

Below are additional resources that provide information regarding compiling Rcpp code on macOS.

1. A helpful post was provided by Brian Ripley regarding the use of
   compiling R code with macOS in April 2014
   [on the `r-sig-mac` list](https://stat.ethz.ch/pipermail/r-sig-mac/2014-April/010835.html),
   which is generally recommended for macOS-specific questions and further consultation.
2. Another helpful write-up for installation / compilation on macOS Mavericks is provided
   [by the BioConductor project](http://www.bioconductor.org/developers/how-to/mavericks-howto/).
3. Lastly, another resource that exists for installation / compilation
   help is provided at
   <http://thecoatlessprofessor.com/programming/r-compiler-tools-for-rcpp-on-os-x/>.

\textbf{Note:} If you are running into trouble compiling code with \pkg{RcppArmadillo}, please also see \faq{q:OSXArma} listed below.

<!--
At the time of writing this paragraph (in the spring of 2011), \pkg{Rcpp}
(just like CRAN) supports all OS X releases greater or equal to 10.5.
However, building \pkg{Rcpp} from source (or building packages using
\pkg{Rcpp}) also requires a recent-enough version of Xcode. For the
\textsl{Leopard} release of OS X, the current version is 3.1.4 which can be
downloaded free of charge from the Apple Developer site. Users may have to
manually select `g++-4.2` via the symbolic link `/usr/bin/g++`.
The \textsl{Snow Leopard} release already comes with Xcode 3.2.x and work as
is.
-->

## Does \pkg{Rcpp} work on solaris/suncc

Yes, it generally does.  But as we do not have access to such systems, some
issues persist on the CRAN test systems. And now that more time has passed
since the question was written, CRAN no longer tests on these platforms.

## Does \pkg{Rcpp} work with REvolution R

We have not tested it yet. \pkg{Rcpp} might need a few tweaks to work
with the compilers used by Revolution R (if those differ from the defaults).
By now REvolution R is defunct too.

## Is it related to Rho (formerly CXXR)

Rho, previously known as CXXR, is an ambitious project that aims to
totally refactor the \proglang{R} interpreter in \proglang{C++}. There
are a few similaritites with \pkg{Rcpp} but the projects are
unrelated.

Rho / CXXR and \pkg{Rcpp} both want \proglang{R} to make more use of \proglang{C++}
but they do it in very different ways.
By now, Rho is long defunct too.

## How do I quickly prototype my code using Attributes {#prototype-using-attributes}

\pkg{Rcpp} version 0.10.0 and later offer a new feature 'Rcpp Attributes'
which is described in detail in its own vignette
\citep{CRAN:Rcpp:Attributes}.  In short, it offers functions \rdoc{Rcpp}{evalCpp},
\rdoc{Rcpp}{cppFunction} and \rdoc{Rcpp}{sourceCpp} which extend the functionality of the
\rdoc{Rcpp}{cxxfunction} function.


## What about the 'no-linking' feature {#function-registration}

Starting with \pkg{Rcpp} 0.11.0, functionality provided by \pkg{Rcpp} and
used by packages built with \pkg{Rcpp} accessed via the registration facility
offered by R (and which is used by \pkg{lme4} and \pkg{Matrix}, as well as by
\pkg{xts} and \pkg{zoo}).  This requires no effort from the user /
programmer, and even frees us from explicit linking instruction. In most
cases, the files `src/Makevars` and `src/Makevars.win` can now be
removed. Exceptions are the use of \pkg{RcppArmadillo} (which needs an entry
`PKG_LIBS=$(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)`) and packages linking
to external libraries they use.

But for most packages using \pkg{Rcpp}, only two things are required:

- an entry in `DESCRIPTION` such as `Imports: Rcpp` (which may
  be versioned as in `Imports: Rcpp (>= 0.11.0)`), and
- an entry in `NAMESPACE` to ensure \pkg{Rcpp} is correctly
  instantiated, for example `importFrom(Rcpp, evalCpp)`.

The name of the symbol does not really matter; once one symbol is imported all
symbols should be available.

## I am having problems building RcppArmadillo on macOS, any help  {#q:OSXArma}

Odds are your build failures are due to the absence of `gfortran`
and its associated libraries. The errors that you may receive are related to either
`-lgfortran` or `-lquadmath`.

To rectify the root of these errors, there are two options available. The first
option is to download and use a fixed set of `gfortran` binaries that are
used to compile R for macOS (e.g. given by the maintainers of the macOS build).
The second option is to either use pre-existing `gfortran` binaries on
your machine or download the latest. These options are described in-depth
in [Section C.3 macOS](https://cran.r-project.org/doc/manuals/r-release/R-admin.html#macOS)
of the [R Installation and Administration](https://cran.r-project.org/doc/manuals/r-release/R-admin.html)
manual. Please consult this manual for up-to-date information regarding `gfortran`
binaries on macOS. We have also documented _other_ common macOS compile
issues in Section \faq{q:OSX}.

# Examples

The following questions were asked on the
[Rcpp-devel](https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/rcpp-devel)
mailing list, which is our preferred place to ask questions as it guarantees
exposure to a number of advanced Rcpp users.  The
[StackOverflow tag for rcpp](http://stackoverflow.com/questions/tagged/rcpp)
is an alternative; that site is also easily searchable.

Several dozen fully documented examples are provided at the
[Rcpp Gallery](http://gallery.rcpp.org) -- which is also open for new contributions.


## Can I use templates with \pkg{Rcpp}

> I'm curious whether one can provide a class definition inline in an R
> script and then initialize an instance of the class and call a method on
> the class, all inline in R.

\noindent This question was initially about using templates with \pkg{inline}, and we
show that (older) answer first. It is also easy with Rcpp Attributes which is
what we show below.


### Using inline with Templated Code

Most certainly, consider this simple example of a templated class
which squares its argument:

```{r}
inc <- 'template <typename T>
        class square :
          public std::function<T(T)> {
            public:
              T operator()( T t) const {
                return t*t;
              }
        };
       '

src <- '
       double x = Rcpp::as<double>(xs);
       int i = Rcpp::as<int>(is);
       square<double> sqdbl;
       square<int> sqint;
       return Rcpp::DataFrame::create(
                    Rcpp::Named("x", sqdbl(x)),
                    Rcpp::Named("i", sqint(i)));
       '
fun <- cxxfunction(signature(xs="numeric",
                             is="integer"),
                   body=src, include=inc,
                   plugin="Rcpp")

fun(2.2, 3L)
```

### Using Rcpp Attributes with Templated Code

We can also use 'Rcpp Attributes' \citep{CRAN:Rcpp:Attributes}---as described
in \faq{using-attributes} and \faq{prototype-using-attributes} above. Simply
place the following code into a file and use \rdoc{Rcpp}{sourceCpp} on it. It
will even run the R part at the end.

```cpp
#include <Rcpp.h>

template <typename T> class square :
    public std::function<T(T)> {
      public:
      T operator()( T t) const {
        return t*t ;
      }
};

// [[Rcpp::export]]
Rcpp::DataFrame fun(double x, int i) {
       square<double> sqdbl;
       square<int> sqint;
       return Rcpp::DataFrame::create(
           Rcpp::Named("x", sqdbl(x)),
           Rcpp::Named("i", sqint(i)));
}

/*** R
fun(2.2, 3L)
*/
```

## Can I do matrix algebra with Rcpp {#matrix-algebra}


> \pkg{Rcpp} allows element-wise operations on vector and matrices through
> operator overloading and STL interface, but what if I want to multiply a
> matrix by a vector, etc ...

\noindent Currently, \pkg{Rcpp} does not provide binary operators to allow operations
involving entire objects. Adding operators to \pkg{Rcpp} would be a major
project (if done right) involving advanced techniques such as expression
templates. We currently do not plan to go in this direction, but we would
welcome external help. Please send us a design document.

However, we have developed the \pkg{RcppArmadillo} package
\citep{CRAN:RcppArmadillo,Eddelbuettel+Sanderson:2014:RcppArmadillo} that
provides a bridge between \pkg{Rcpp} and \pkg{Armadillo}
\citep{Sanderson:2010:Armadillo}. \pkg{Armadillo}
supports binary operators on its types in a way that takes full advantage of
expression templates to remove temporaries and allow chaining of
operations. That is a mouthful of words meaning that it makes the code go
faster by using fiendishly clever ways available via the so-called template
meta programming, an advanced \proglang{C++} technique.
Also, the \pkg{RcppEigen} package \citep{JSS:RcppEigen} provides an alternative using the
[Eigen](http://eigen.tuxfamily.org) template library.

### Using inline with RcppArmadillo {#using-inline-armadillo}

The following example is adapted from the examples available at the project
page of Armadillo. It calculates $x' \times Y^{-1} \times z$

```{r, eval = FALSE}
lines = '// copy the data to armadillo structures
arma::colvec x = Rcpp::as<arma::colvec> (x_);
arma::mat Y = Rcpp::as<arma::mat>(Y_) ;
arma::colvec z = Rcpp::as<arma::colvec>(z_) ;

// calculate the result
double result = arma::as_scalar(
    arma::trans(x) * arma::inv(Y) * z);

// return it to R
return Rcpp::wrap(result);'

writeLines(a, file = "myfile.cpp")
```

If stored in a file `myfile.cpp`, we can use it via \pkg{inline}:

```{r, eval = FALSE}
fx <- cxxfunction(signature(x_="numeric",
                            Y_="matrix",
                            z_="numeric" ),
                  paste(readLines("myfile.cpp"),
                        collapse="\n"),
                  plugin="RcppArmadillo" )
fx(1:4, diag(4), 1:4)
```

The focus is on the code `arma::trans(x) * arma::inv(Y) * z`, which
performs the same operation as the R code `t(x) %*% solve(Y) %*% z`,
although Armadillo turns it into only one operation, which makes it quite fast.
Armadillo benchmarks against other \proglang{C++} matrix algebra libraries
are provided on [the Armadillo website](http://arma.sourceforge.net/speed.html).

It should be noted that code below depends on the version `0.3.5` of
\pkg{inline} and the version `0.2.2` of \pkg{RcppArmadillo}.

### Using Rcpp Attributes with RcppArmadillo

We can also write the same example for use with Rcpp Attributes:

```cpp
#include <RcppArmadillo.h>

// [[Rcpp::depends(RcppArmadillo)]]

// [[Rcpp::export]]
double fx(arma::colvec x, arma::mat Y,
          arma::colvec z) {
    // calculate the result
    double result = arma::as_scalar(
        arma::trans(x) * arma::inv(Y) * z
    );
    return result;
}

/*** R
fx(1:4, diag(4), 1:4)
*/
```

Here, the additional `Rcpp::depends(RcppArmadillo)` ensures that code
can be compiled against the \pkg{RcppArmadillo} header, and that the correct
libraries are linked to the function built from the supplied code example.

Note how we do not have to concern ourselves with conversion; R object
automatically become (Rcpp)Armadillo objects and we can focus on the single
computing a (scalar) result.

## Can I use code from the Rmath header and library with \pkg{Rcpp}

> Can I call functions defined in the Rmath header file and the
> standalone math library for R--as for example the random number generators?

\noindent Yes, of course. This math library exports a subset of R, but \pkg{Rcpp} has
access to much more.  Here is another simple example. Note how we have to use
and instance of the `RNGScope` class to set and re-set the
random-number generator. This also illustrates Rcpp sugar as we are using a
vectorised call to `rnorm`. Moreover, because the RNG is reset, the
two calls result in the same random draws. If we wanted to control the draws,
we could explicitly set the seed after the `RNGScope` object has been
instantiated.

```{r}
fx <- cxxfunction(signature(),
                  'RNGScope();
                   return rnorm(5, 0, 100);',
                  plugin="Rcpp")
set.seed(42)
fx()
fx()
```

Newer versions of Rcpp also provide the actual Rmath function in the `R`
namespace, \textsl{i.e.} as `R::rnorm(m,s)` to obtain a scalar
random variable distributed as $N(m,s)$.

Using Rcpp Attributes, this can be as simple as

```{r}
cppFunction('Rcpp::NumericVector ff(int n) {
              return rnorm(n, 0, 100);  }')
set.seed(42)
ff(5)
ff(5)
set.seed(42)
rnorm(5, 0, 100)
rnorm(5, 0, 100)
```

This illustrates the Rcpp Attributes adds the required `RNGScope` object
for us. It also shows how setting the seed from R affects draws done via C++
as well as R, and that identical random number draws are obtained.

## Can I use `NA` and `Inf` with \pkg{Rcpp}

> R knows about `NA` and `Inf`. How do I use them from C++?

\noindent Yes, see the following example:

```{r}
src <- 'Rcpp::NumericVector v(4);
        v[0] = R_NegInf; // -Inf
        v[1] = NA_REAL;  // NA
        v[2] = R_PosInf; // Inf
        v[3] = 42;       // c.f. Hitchhiker Guide
        return Rcpp::wrap(v);'
fun <- cxxfunction(signature(), src, plugin="Rcpp")
fun()
```

Similarly, for Rcpp Attributes:

```cpp
#include <Rcpp.h>

// [[Rcpp::export]]
Rcpp::NumericVector fun(void) {
    Rcpp::NumericVector v(4);
    v[0] = R_NegInf; // -Inf
    v[1] = NA_REAL;  // NA
    v[2] = R_PosInf; // Inf
    v[3] = 42;       // c.f. Hitchhiker Guide
    return v;
}
```

## Can I easily multiply matrices

> Can I multiply matrices easily?

\noindent Yes, via the \pkg{RcppArmadillo} package which builds upon \pkg{Rcpp} and the
wonderful Armadillo library described above in \faq{matrix-algebra}:

```{r, eval = FALSE}
txt <- 'arma::mat Am = Rcpp::as< arma::mat >(A);
        arma::mat Bm = Rcpp::as< arma::mat >(B);
        return Rcpp::wrap( Am * Bm );'
mmult <- cxxfunction(signature(A="numeric",
                               B="numeric"),
                     body=txt,
                     plugin="RcppArmadillo")
A <- matrix(1:9, 3, 3)
B <- matrix(9:1, 3, 3)
C <- mmult(A, B)
C
```

Armadillo supports a full range of common linear algebra operations.

The \pkg{RcppEigen} package provides an alternative using the
[Eigen](http://eigen.tuxfamily.org) template library.

Rcpp Attributes, once again, makes this even easier:

```cpp

#include <RcppArmadillo.h>

// [[Rcpp::depends(RcppArmadillo)]]

// [[Rcpp::export]]
arma::mat mult(arma::mat A, arma::mat B) {
    return A*B;
}

/*** R
A <- matrix(1:9, 3, 3)
B <- matrix(9:1, 3, 3)
mult(A,B)
*/
```

which can be built, and run, from R via a simple \rdoc{Rcpp}{sourceCpp}
call---and will also run the small R example at the end.

## How do I write a plugin for \pkg{inline} and/or Rcpp Attributes

> How can I create my own plugin for use by the \pkg{inline} package?

\noindent Here is an example which shows how to it using GSL libraries as an
example. This is merely for demonstration, it is also not perfectly general
as we do not detect locations first---but it serves as an example:

```{r, eval = FALSE}
# simple example of seeding RNG and
# drawing one random number
gslrng <- '
int seed = Rcpp::as<int>(par) ;
gsl_rng_env_setup();
gsl_rng *r = gsl_rng_alloc (gsl_rng_default);
gsl_rng_set (r, (unsigned long) seed);
double v = gsl_rng_get (r);
gsl_rng_free(r);
return Rcpp::wrap(v);'

plug <- Rcpp::Rcpp.plugin.maker(
    include.before = "#include <gsl/gsl_rng.h>",
    libs = paste(
"-L/usr/local/lib/R/site-library/Rcpp/lib -lRcpp",
"-Wl,-rpath,/usr/local/lib/R/site-library/Rcpp/lib",
"-L/usr/lib -lgsl -lgslcblas -lm")
)
registerPlugin("gslDemo", plug )
fun <- cxxfunction(signature(par="numeric"),
                   gslrng, plugin="gslDemo")
fun(0)
```

Here the \pkg{Rcpp} function `Rcpp.plugin.maker` is used to create a
plugin 'plug' which is then registered, and subsequently used by \pkg{inline}.

The same plugins can be used by Rcpp Attributes as well.

## How can I pass one additional flag to the compiler

> How can I pass another flag to the `g++` compiler without writing a new plugin?

\noindent The quickest way is to modify the return value from an existing plugin. Here
we use the default one from \pkg{Rcpp} itself in order to pass the flag
`-std=c++11`. As it does not set the `PKG_CXXFLAGS` variable, we
simply assign this. For other plugins, one may need to append to the existing
values instead. An older example follow (but note that C++11 or newer is the
default now with more recent R releases)

```{r, eval=FALSE}
myplugin <- getPlugin("Rcpp")
myplugin$env$PKG_CXXFLAGS <- "-std=c++11"
f <- cxxfunction(signature(),
                 settings = myplugin, body = '
    std::vector<double> x = { 1.0, 2.0, 3.0 };
    return Rcpp::wrap(x);
')
f()
```

For Rcpp Attributes, the attributes `Rcpp::plugin()` can be
used. Currently supported plugins are for C++11 (which is now a standard for
compilation with R, but used to be an opt-in), other compilation standards
C++14, C++17, C++20, C++23, as well as for OpenMP.

## How can I set matrix row and column names

> Ok, I can create a matrix, but how do I set its row and columns names?

\noindent Pretty much the same way as in \proglang{R} itself: We define a list with two
character vectors, one each for row and column names, and assign this to the
`dimnames` attribute:

```{r, eval = FALSE}
src <- '
  Rcpp::NumericMatrix x(2,2);
  x.fill(42);           // or another value
  Rcpp::List dimnms =   // list with 2 vecs
    Rcpp::List::create( // with static names
      Rcpp::CharacterVector::create("cc", "dd"),
      Rcpp::CharacterVector::create("ee", "ff")
    );
  // and assign it
  x.attr("dimnames") = dimnms;
  return(x);
'
fun <- cxxfunction(signature(),
                   body=src, plugin="Rcpp")
fun()
```

The same logic, but used with Rcpp Attributes:

```cpp
#include <Rcpp.h>

// [[Rcpp::export]]
Rcpp::List fun(void) {
    Rcpp::NumericMatrix x(2,2);
    x.fill(42);           // or another value
    Rcpp::List dimnms =   // list with 2 vecs
      Rcpp::List::create( // with static names
        Rcpp::CharacterVector::create("cc", "dd"),
        Rcpp::CharacterVector::create("ee", "ff"));
    // and assign it
    x.attr("dimnames") = dimnms;
    return(x);
}
```

## Why can long long types not be cast correctly

\noindent That is a good and open question. We rely on the basic \proglang{R} types,
notably `integer` and `numeric`.  These can be cast to and from
\proglang{C++} types without problems.  But there are corner cases.  The
following example, contributed by a user, shows that we cannot reliably cast
`long` types (on a 64-bit machines).

```{r, eval = FALSE}
BigInts <- cxxfunction(signature(),
  'std::vector<long> bigints;
   bigints.push_back(12345678901234567LL);
   bigints.push_back(12345678901234568LL);
   Rprintf("Difference of %ld\\n",
       12345678901234568LL - 12345678901234567LL);
   return wrap(bigints);',
  plugin="Rcpp", includes="#include <vector>")

retval <- BigInts()

# Unique 64-bit integers were cast to identical
# lower precision numerics behind my back with
# no warnings or errors whatsoever.  Error.

stopifnot(length(unique(retval)) == 2)
```

While the difference of one is evident at the \proglang{C++} level, it is no
longer present once cast to \proglang{R}. The 64-bit integer values get cast
to a floating point types with a 53-bit mantissa. We do not have a good
suggestion or fix for casting 64-bit integer values: 32-bit integer values
fit into `integer` types, up to 53 bit precision fits into
`numeric` and beyond that truly large integers may have to converted
(rather crudely) to text and re-parsed. Using a different representation as
for example from the [GNU Multiple Precision Arithmetic Library](http://gmplib.org/)
may be an alternative.

However, with care, and via the package \pkg{bit64}, \proglang{R} can use
`integer64` as a type (but storing the 64 bits in a `double`), and
\pkg{RcppInt64} \citep{CRAN:RcppInt64} can help with conversion back and
forth.

## What LaTeX packages do I need to typeset the vignettes

> I would like to typeset the vignettes. What do I need?

\noindent The [TeXLive](https://www.tug.org/texlive/) distribution seems to get
bigger and bigger.  What you need to install may depend on your operating
system.

Specific per-platform notes:

- **Windows** users probably want the [MiKTeX](http://miktex.org/).
  Suggestions for a more detailed walk through would be appreciated.
- **macOS** users seem to fall into camps which like or do not like brew /
  homebrew. One suggestion was to install
  [MacTeX](https://tug.org/mactex/mactex-download.html) but at
  approximately 2.5gb (as of January 2016) this is not lightweight.
- **Linux** users probably want the full
  [TeXLive](https://www.tug.org/texlive/) set from their distribution. On
  [Debian](http://www.debian.org) these packages are installed to build
  the R package itself: `texlive-base, texlive-latex-base,
    texlive-generic-recommended, texlive-fonts-recommended,
    texlive-fonts-extra, texlive-extra-utils, texlive-latex-recommended,
    texlive-latex-extra`.  Using `texlive-full` may be a shortcut.
  Fedora and other distributions should have similar packages.

## Why is there a limit of 20 on some constructors

> Ok, I would like to pass $N$ object but you only allow 20. How come?

\noindent In essence, and in order to be able to compile it with the largest number of
compilers, \pkg{Rcpp} is constrained by the older C++ standards which do not
support variadic function arguments.  So we actually use macros and code
generator scripts to explicitly enumerate arguments, and that number has to stop
at some limit. We chose 20.

A good discussion is available at
[this StackOverflow question](http://stackoverflow.com/questions/27371543)
concering data.frame creation with \pkg{Rcpp}. One solution offers a custom
`ListBuilder` class to circumvent the limit; another suggests to simply
nest lists.

## Can I use default function parameters with \pkg{Rcpp}

\noindent Yes, you can use default parameters with _some_ limitations.
The limitations are mainly related to string literals and empty vectors.
This is what is currently supported:

- String literals delimited by quotes (e.g. `"foo"`)
- Integer and Decimal numeric values (e.g. `10` or `4.5`)
- Pre-defined constants including:
    - Booleans: `true` and `false`
    - Null Values: `R_NilValue`, `NA_STRING`, `NA_INTEGER`, `NA_REAL`, and `NA_LOGICAL`.
- Selected vector types can be instantiated using the empty form of the
  `::create` static member function.
    - `CharacterVector`, `IntegerVector`, and `NumericVector`
- Matrix types instantiated using the rows, cols constructor
  `Rcpp::<Type>Matrix n(rows,cols)`
    - `CharacterMatrix`, `IntegerMatrix`, and `NumericMatrix`

To illustrate, please consider the following example that provides a short
how-to:

```cpp
#include <Rcpp.h>

// [[Rcpp::export]]
void sample_defaults(
        NumericVector x =
        NumericVector::create(), // Size 0 vector
        bool bias = true,        // Set to true
        std::string method =
            "rcpp rules!") {     // Set string

    Rcpp::Rcout << "x size: " << x.size() << ", ";
    Rcpp::Rcout << "bias value: " << bias << ", ";
    Rcpp::Rcout << "method value: " << ".";

}

/*** R
sample_defaults()                 # all defaults
sample_defaults(1:5)              # supply x values

sample_defaults(bias = FALSE,     # supply bool
                method = "Rlang") # and string
*/
```

Note: In `cpp`, the default `bool` values are `true` and
`false` whereas in R the valid types are `TRUE` or `FALSE`.

## Can I use C++11, C++14, C++17, ... with \pkg{Rcpp}

But of course.  In a nutshell, this boils down to \emph{what your compiler
  supports}, and also \emph{what R supports}.  We expanded a little on this in
[Rcpp Gallery article](http://gallery.rcpp.org/articles/rcpp-and-c++11-c++14-c++17/) providing more detail.  What follows in an abridged summary.

You can always \emph{locally} set appropriate `PKG_CXXFLAGS` as an
environment variable, or via `~/.R/Makevars`. You can also plugins and/or R
support from `src/Makevars`:

- _C++11_: has been supported since early 2013 via a plugin selecting
  the language standard which is useful for `sourceCpp()` etc. For
  packages, R has supported it since R 3.1.0 which added the option to select
  the language standard via `CXX_STD = CXX11`. As of early 2017, over 120
  packages on CRAN use this. As of R 4.0.0, this is the minimum standard and
  no longer needed.
- _C++14_: has been supported since early 2016 via a plugin selecting
  the language standard which is useful for `sourceCpp()` etc. For
  packages, R supports it since R 3.4.0 adding the option to select the language
  standard via `CXX_STD = CXX14`. It became the default with R 4.1.0.
- _C++17_: it has been supported (with an appropriate compiler)  via plugin starting with
  Rcpp 0.12.10, or use via `sourceCpp()`, or via `PKG_CXXFLAGS` or
  other means to set compiler options. It became the default with R 4.3.0,
  but compiler support may not be widespread.
- _C++20_: It is also supported (given a suitable compiler) since Rcpp 1.0.11.

## How do I use it within (Python's) Conda setup?

In a comment to [issue ticket #770](https://github.com/RcppCore/Rcpp/issues/770#issuecomment-346716808) it is stated that running

```sh
conda install gxx_linux-64
```

helps within this environment as it installs the corresponding
`x86_64-conda_cos6-linux-gnu-c++` compiler. Documentation for this and other
systems is provided
[at this page](https://conda.io/docs/user-guide/tasks/build-packages/compiler-tools.html).

## Can I speed up compilation?

Somewhat. One option is to cache as much as possible via
[ccache](https://ccache.dev/) by adding it to `~/.R/Makevars`.

Depending on what parts of Rcpp are being used, compilation speed can be
increased by turning use of Modules off.  Starting with version 1.0.3, the
`RCPP_NO_MODULES` define can be used. It can be set in `src/Makevars` as
an argument to `PKG_CXXFLAGS` (or one of the other C++ dialect options) as
`-DRCPP_NO_MODULES`. This has the advantage of affecting _all_ files in the
package, including the auto-generated `RcppExports.cpp` where it might be
trickier to set it manually.

Beyond modules, RTTI support can also be turned off. this implies turning
Modules support off as well so. To select this approach, use the
`RCPP_NO_RTTI` define.

Starting with version 1.0.8 of \pkg{Rcpp}, new headers \code{Rcpp/Light},
\code{Rcpp/Lighter}, \code{Rcpp/Lightest} make this much easier as they
exclude these different (layered) bits of functionality.

# Support

## Is the API documented

You bet. We use \proglang{doxygen} to generate html, latex and man page
documentation from the source. The html documentation is available for
[browsing](http://dirk.eddelbuettel.com/code/rcpp/html/index.html), as a
[very large pdf file](http://dirk.eddelbuettel.com/code/rcpp/Rcpp_refman.pdf),
and all three formats are also available a zip-archives:
[html](http://dirk.eddelbuettel.com/code/rcpp/rcpp-doc-html.zip),
[latex](http://dirk.eddelbuettel.com/code/rcpp/rcpp-doc-latex.zip), and
[man](http://dirk.eddelbuettel.com/code/rcpp/rcpp-doc-man.zip).

## Does it really work

We take quality seriously and have developped an extensive unit test suite to
cover many possible uses of the \pkg{Rcpp} API.

We are always on the look for more coverage in our testing. Please let us know
if something has not been tested enough.

## Where can I ask further questions

The
[Rcpp-devel](https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/rcpp-devel)
mailing list hosted at R-forge is by far the best place.  You may also want
to look at the list archives to see if your question has been asked before.

You can also use [StackOverflow via its 'rcpp' tag](http://stackoverflow.com/questions/tagged/rcpp).

## Where can I read old questions and answers

The normal [Rcpp-devel](https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/rcpp-devel)
mailing list hosting at R-forge contains an archive, which can be
[searched via swish](http://lists.r-forge.r-project.org/mailman/swish.cgi?query=listname=rcpp-devel).

Alternatively, one can also use
[Mail-Archive on Rcpp-devel](http://www.mail-archive.com/rcpp-devel@lists.r-forge.r-project.org/info.html)
which offers web-based interfaces, including searching.

## I like it. How can I help {#helping}

We maintain a list of
[open issues in the Github repository](https://github.com/RcppCore/Rcpp/issues?state=open).
We welcome pull requests and suggest that code submissions
come corresponding unit tests and, if applicable, documentation.

If you are willing to donate time and have skills in C++, let us know. If you are
willing to donate money to sponsor improvements, let us know too.

You can also spread the word about \pkg{Rcpp}. There are many packages on CRAN
that use \proglang{C++}, yet are not using \pkg{Rcpp}. You could blog about
it, or get the word out otherwise.

Last but not least the [Rcpp Gallery](http://gallery.rcpp.org) is open
for user contributions.

## I don't like it. How can I help {#dont-like-help}

It is very generous of you to still want to help. Perhaps you can tell us
what it is that you dislike. We are very open to \emph{constructive} criticism.

## Can I have commercial support for \pkg{Rcpp}

Sure you can. Just send us an email, and we will be happy to discuss the
request.

## I want to learn quickly. Do you provide training courses

Yes. Just send us an email.

## Where is the code repository

From late 2008 to late 2013, we used the
[Subversion repository at R-Forge](https://r-forge.r-project.org/scm/?group_id=155)
which contained \pkg{Rcpp} and a number of related packages. It still has the full
history as well as number of support files.

We have since switched to a [Git repository at Github](http://github.com/RcppCore/Rcpp)
for \pkg{Rcpp} (as well as for \pkg{RcppArmadillo} and \pkg{RcppEigen}).

# Known Issues

Contained within this section is a list of known issues regarding \pkg{Rcpp}.
The issues listed here are either not able to be fixed due to breaking
application binary interface (ABI), would impact the ability to reproduce
pre-existing results, or require significant work. Generally speaking, these
issues come to light only when pushing the edge capabilities of \pkg{Rcpp}.

## \pkg{Rcpp} changed the (const) object I passed by value

\pkg{Rcpp} objects are wrappers around the underlying \proglang{R} objects' `SEXP`,
or S-expression. The `SEXP` is a pointer variable that holds the location
of where the \proglang{R} object data has been stored \citep[][Section 1.1]{R:Internals}.
That is to say, the `SEXP` does _not_ hold the actual data of the
\proglang{R} object but merely a reference to where the data resides. When creating a new
\pkg{Rcpp} object for an \proglang{R} object to enter \proglang{C++}, this object will
use the same `SEXP` that powers the original \proglang{R} object if the types match
otherwise a new `SEXP` must be created to be type safe. In essence, the
underlying `SEXP` objects are passed by reference without explicit copies
being made into \proglang{C++}. We refer to this arrangement as a
_proxy model_.

As for the actual implementation, there are a few consequences of the proxy
model. The foremost consequence within this paradigm is that pass by value is
really a pass by reference. In essence, the distinction between the following
two functions is only visual sugar:

```cpp
void implicit_ref(NumericVector X);
void explicit_ref(NumericVector& X);
```

In particular, when one is passing by value what occurs is the instantiation of
the new \pkg{Rcpp} object that uses the same `SEXP` for the \proglang{R} object.
As a result, the \pkg{Rcpp} object is ``linked'' to the original \proglang{R} object.
Thus, if an operation is performed on the \pkg{Rcpp} object, such as adding 1
to each element, the operation also updates the \proglang{R} object causing the change to be propagated to \proglang{R}'s interactive environment.

```{Rcpp}
#include<Rcpp.h>

// [[Rcpp::export]]
void implicit_ref(Rcpp::NumericVector X) {
   X = X + 1.0;
}

// [[Rcpp::export]]
void explicit_ref(Rcpp::NumericVector& X) {
   X = X + 1.0;
}
```

R use

```{r}
a <- 1.5:4.5
b <- 1.5:4.5
implicit_ref(a)
a
explicit_ref(b)
b
```

There are two exceptions to this rule. The first exception is that a deep copy
of the object can be made by explicit use of `Rcpp:clone()`. In this case,
the cloned object has no link to the original \proglang{R} object. However, there is a
time cost associated with this procedure as new memory must be allocated and
the previous values must be copied over.  The second exception, which was
previously foreshadowed, is encountered when \pkg{Rcpp} and \proglang{R} object types
do not match. One frequent example of this case is when the \proglang{R} object generated
from `seq()` or `a:b` reports a class of `"integer"` while the
\pkg{Rcpp} object is setup to receive the class of `"numeric"` as its
object is set to `NumericVector` or `NumericMatrix`.  In such cases,
this would lead to a new `SEXP` object being created behind the scenes
and, thus, there would _not_ be a link between the \pkg{Rcpp} object
and \proglang{R} object. So, any changes in \proglang{C++} would not be propagated to
\proglang{R} unless otherwise specified.

```{Rcpp}
#include<Rcpp.h>

// [[Rcpp::export]]
void int_vec_type(Rcpp::IntegerVector X) {
   X = X + 1.0;
}

// [[Rcpp::export]]
void num_vec_type(Rcpp::NumericVector X) {
   X = X + 1.0;
}
```

R use:

```{r}
a <- 1:5
b <- 1:5
class(a)
int_vec_type(a)
a # variable a changed as a side effect
num_vec_type(b)
b # b unchanged as copy was made for numeric
```

With this being said, there is one last area of contention with the proxy model:
the keyword `const`. The `const` declaration indicates that an object
is not allowed to be modified by any action. Due to the way the proxy
model paradigm works, there is a way to "override" the `const` designation.
Simply put, one can create a new \pkg{Rcpp} object without the `const`
declaration from a pre-existing one. As a result, the new \pkg{Rcpp} object
would be allowed to be modified by the compiler and, thus, modifying the initial
`SEXP` object. Therefore, the initially secure \proglang{R} object would be altered.
To illustrate this phenomenon, consider the following scenario:

```{Rcpp}
#include <Rcpp.h>

// [[Rcpp::export]]
Rcpp::IntegerVector const_override_ex(
        const Rcpp::IntegerVector& X) {

  Rcpp::IntegerVector Y(X); // Create object
                            // from SEXP

  Y = Y * 2;                // Modify new object

  return Y;                 // Return new object
}
```

R use:

```{r}
x <- 1:10    # an integer sequence
# returning an altered value
const_override_ex(x)
# but the original value is altered too!
x
```

So we see that with `SEXP` objects, the `const` declaration can be
circumvented as it is really a pointer to the underlying R object.


## Issues with implicit conversion from an \pkg{Rcpp} object to a scalar or other \pkg{Rcpp} object

Not all \pkg{Rcpp} expressions are directly compatible with
`operator=`.  Compability issues stem from many \pkg{Rcpp} objects and
functions returning an intermediary result which requires an explicit
conversion.  In such cases, the user may need to assist the compiler
with the conversion.

There are two ways to assist with the conversion. The first is to construct
storage variable for a result, calculate the result, and then store a value
into it. This is typically what is needed when working with
`Character<Type>` and `String` in \pkg{Rcpp} due to the
`Rcpp::internal::string_proxy` class. Within the following code snippet,
the aforementioned approach is emphasized:

```cpp
#include<Rcpp.h>

// [[Rcpp::export]]
std::string explicit_string_conv(
        Rcpp::CharacterVector X) {

    std::string s;  // define storage
    s = X[0];       // assign from CharacterVector

    return s;
}
```

If one were to use a direct allocation and assignment strategy,
e.g. `std::string s = X[0]`, this would result in the compiler triggering
a conversion error on _some_ platforms. The error would be similar to:

```{bash, eval = FALSE}
error: no viable conversion from 'Proxy'
(aka 'string_proxy<16>') to 'std::string'
(aka 'basic_string<char, char_traits<char>,
allocator<char> >')
```

The second way to help the compiler is to use an explicit \pkg{Rcpp} type conversion
function, if one were to exist. Examples of \pkg{Rcpp} type conversion functions
include `as<T>()`, `.get()` for `cumsum()`, `is_true()`
and `is_false()` for `any()` or `all()`.


## Using `operator=` with a scalar replaced the object instead of filling element-wise

Assignment using the `operator=` with either `Vector` and
`Matrix` classes will not elicit an element-wise fill. If you seek an
element-wise fill, then use the `.fill()` member method to propagate a
single value throughout the object. With this being said, the behavior of
`operator=` differs for the `Vector` and `Matrix` classes.

The implementation of the `operator=` for the `Vector` class will
replace the existing vector with the assigned value. This behavior is valid
even if the assigned value is a scalar value such as 3.14 or 25 as the object
is cast into the appropriate \pkg{Rcpp} object type. Therefore, if a
`Vector` is initialized to have a length of 10 and a scalar is assigned
via `operator=`, then the resulting `Vector` would have a length of
1. See the following code snippet for the aforementioned behavior.

```{Rcpp}
#include<Rcpp.h>

// [[Rcpp::export]]
void vec_scalar_assign(int n, double fill_val) {
  Rcpp::NumericVector X(n);
  Rcpp::Rcout << "Value of Vector " <<
      "on Creation: " <<
      std::endl << X << std::endl;

  X = fill_val;

  Rcpp::Rcout << "Value of Vector " <<
      "after Assignment: " <<
      std::endl << X << std::endl;
}
```

R use:

```{r}
vec_scalar_assign(5L, 3.14)
```


Now, the `Matrix` class does not define its own `operator=` but
instead uses the `Vector` class implementation. This leads to unexpected
results while attempting to use the assignment operator with a scalar. In
particular, the scalar will be coerced into a square `Matrix` and then
assigned. For an example of this behavior, consider the following code:

```{Rcpp}
#include<Rcpp.h>

// [[Rcpp::export]]
void mat_scalar_assign(int n, double fill_val) {
  Rcpp::NumericMatrix X(n, n);
  Rcpp::Rcout << "Value of Matrix " <<
      "on Creation: " <<
      std::endl << X << std::endl;

  X = fill_val;

  Rcpp::Rcout << "Value of Matrix " <<
      "after Assignment: " <<
      std::endl << X << std::endl;
}
```

R use:

```{r}
mat_scalar_assign(2L, 3.0)
```

## Long Vector support on Windows

Prior to \proglang{R}'s 3.0.0, the largest vector one could obtain was at most $2^{31} - 1$
elements. With the release of \proglang{R}'s 3.0.0, long vector support was added to
allow for largest vector possible to increase up to $2^{52}$ elements on x64 bit
operating systems (c.f. [Long Vectors help entry](https://stat.ethz.ch/R-manual/R-devel/library/base/html/LongVectors.html)).
Once this was established, support for long vectors within the \pkg{Rcpp} paradigm
was introduced with \pkg{Rcpp} version 0.12.0 (c.f [\pkg{Rcpp} 0.12.0 annoucement](http://dirk.eddelbuettel.com/blog/2015/07/25/)).

However, the requirement for using long vectors in \pkg{Rcpp} necessitates the
presence of compiler support for the `R_xlen_t`, which is platform
dependent on how `ptrdiff_t` is implemented. Unfortunately, this means
that on the Windows platform the definition of `R_xlen_t` is of type
`long` instead of `long long` when compiling under the
\proglang{C++98} specification. Therefore, to solve this issue one must compile
under the specification for \proglang{C++11} or later version.

There are three options to trigger compilation with  \proglang{C++11}.
The first -- and most likely option to use -- will be the plugin support offered
by \pkg{Rcpp} attributes. This can be engaged by adding
`// [[Rcpp::plugins(cpp11)]]` to the top of the \proglang{C++} script.
For diagnostic and illustrativative purposes, consider the following code
which checks to see if `R_xlen_t` is available on your platform:

```{Rcpp}
#include <Rcpp.h>
// Force compilation mode to C++11
// [[Rcpp::plugins(cpp11)]]

// [[Rcpp::export]]
bool test_long_vector_support() {
#ifdef RCPP_HAS_LONG_LONG_TYPES
  return true;
#else
  return false;
#endif
}
```

R use:

```{r}
test_long_vector_support()
```

The remaining two options are for users who have opted to embed \pkg{Rcpp} code
within an \proglang{R} package. In particular, the second option requires adding
`CXX_STD = CXX11` to a `Makevars` file found in the `/src`
directory. Finally, the third option is to add `SystemRequirements:C++11`
in the package's `DESCRIPTION` file.

Please note that the support for \proglang{C++11} prior to \proglang{R} v3.3.0 on Windows
is limited. Therefore, plan accordingly if the goal is to support older
versions of \proglang{R}.

## Sorting with STL on a `CharacterVector` produces problematic results

The Standard Template Library's (STL) `std::sort` algorithm performs
adequately for the majority of \pkg{Rcpp} data types. The notable exception
that makes what would otherwise be a universal quantifier into an existential
quantifier is the `CharacterVector` data type. Chiefly, the issue with
sorting strings is related to how the `CharacterVector` relies upon the
use of `Rcpp::internal::string_proxy`.
In particular, `Rcpp::internal::string_proxy` is _not_ MoveAssignable since the
left hand side of `operator=(const string_proxy \&rhs)` is _not_
viewed as equivalent to the right hand side before the
operation \citep[][p. 466, Table 22]{Cpp11}. This further complicates matters
when using `CharacterVector` with `std::swap`, `std::move`,
`std::copy` and their variants.

To avoid unwarranted pain with sorting, the preferred approach is to use the
`.sort()` member function of \pkg{Rcpp} objects. The member function
correctly applies the sorting procedure to \pkg{Rcpp} objects regardless of
type. Though, sorting is slightly problematic due to locale as explained in the
next entry. In the interim, the following code example illustrates the preferred
approach alongside the problematic STL approach:

```{Rcpp}
#include <Rcpp.h>

// [[Rcpp::export]]
Rcpp::CharacterVector preferred_sort(
        Rcpp::CharacterVector x) {

  Rcpp::CharacterVector y = Rcpp::clone(x);
  y.sort();

  return y;
}

// [[Rcpp::export]]
Rcpp::CharacterVector stl_sort(
        Rcpp::CharacterVector x) {

  Rcpp::CharacterVector y = Rcpp::clone(x);
  std::sort(y.begin(), y.end());

  return y;
}
```

R use:

```{r}
set.seed(123)
(X <- sample(c(LETTERS[1:5], letters[1:6]), 11))
preferred_sort(X)
stl_sort(X)
```

In closing, the results of using the STL approach do change depending on
whether `libc++` or `libstdc++` standard library is used to compile
the code. When debugging, this does make the issue particularly complex to
sort out. Principally, compilation with `libc++` and STL has been shown
to yield the correct results. However, it is not wise to rely upon this library
as a majority of code is compiled against `libstdc++` as it more complete.

## Lexicographic order of string sorting differs due to capitalization

Comparing strings within \proglang{R} hinges on the ability to process the locale or
native-language environment of the string. In \proglang{R}, there is a function called
`Scollate` that performs the comparison on locale. Unfortunately, this
function has not been made publicly available and, thus, \pkg{Rcpp} does
_not_ have access to it within its implementation of `StrCmp`.
As a result, strings that are sorted under the `.sort()` member function
are ordered improperly. Specifically, if capitalization is present, then
capitalized words are sorted together followed by the sorting of lowercase
words instead of a mixture of capitalized and lowercase words. The issue is
illustrated by the following code example:

```{Rcpp}
#include <Rcpp.h>

// [[Rcpp::export]]
Rcpp::CharacterVector rcpp_sort(
        Rcpp::CharacterVector X) {
  X.sort();
  return X;
}
```

R use:

```{r}
x <- c("B", "b", "c", "A", "a")
sort(x)
rcpp_sort(x)
```

## Package building fails with 'symbols not found'

R 3.4.0 and later strongly encourage registering dynamically loadable
symbols. In the stronger form (where `.registration=TRUE` is added to the
`useDynLib()` statement in `NAMESPACE`), only registered symbols can be
loaded. This is fully supported by Rcpp 0.12.12 and later, and the required code
is added to `src/RcppExports.cpp`.

However, the transition from the previously generated file `src/RcppExports.cpp`
to the new one may require running `compileAttributes()` twice (which does not
happen when, _e.g._, devtools is used). When `Rcpp::compileAttributes()` is
called, it also calls `tools::package_native_routine_registration_skeleton()`,
which crawls through usages of `.Call()` in the `R/` source files of the package to
figure out what routines need to be registered. If an older `RcppExports.R` file
is discovered, its out-of-date symbol names get picked up, and registration
rules for those symbols get written as well. This will register more symbols for
the package than are actually defined, leading to an error. This point has been
discussed at some length both in the GitHub issue tickes, on StackOverflow and
elsewhere.

So if your autogenerated file fails, and a `symbols not found` error is reported
by the linker, consider running `compileAttributes()` twice. Deleting
`R/RcppExports.R` and `src/RcppExports.cpp` may also work.

## Can we use exceptions and stop() across shared libraries?

Within limits, yes. Code that is generated via Rcpp Attributes (see
\citet{CRAN:Rcpp:Attributes} and Section~\ref{using-attributes}) generally
handles this correctly and gracefully via the `try-catch` layer it adds
shielding the exception from propagating to another, separate dynamic
library.

However, this mechanism relies on dynamic linking with the (system library)
`libgcc` providing the C++ standard library (as well as on using the same C++
standard library across all compiled components). But this library is linked
statically on Windows putting a limitation on the use of `stop()` from within
Rcpp Modules \citep{CRAN:Rcpp:Modules}.  Some more background on the linking
requirement is [in this SO
question](https://stackoverflow.com/questions/2424836/exceptions-are-not-caught-in-gcc-program).

## My package errors with "'dataptr' not provided by Rcpp"

If you see tests of your package fail with an error '... not provided by
Rcpp', frequently pointing at either `dataptr` or `enterRNGScope`, then the
\pkg{Rcpp} package may not have been initialized correctly.  For your
package, it is generally recommended to have both `Imports: Rcpp` and
`LinkingTo: Rcpp` in the file `DESCRIPTION` combined with an explicit
`importFrom("Rcpp", "evalCpp")` in the file `NAMESPACE`.  Doing so ensures
that this symbol is registered when your package is loaded by R, and as a
side-effect certain other \pkg{Rcpp} function identifiers will also be
resolved properly.

## On macOS, 'no matching function for call to `R_lsInternal`'

In issue [#1148](https://github.com/RcppCore/Rcpp/issues/1148) an error due
to overeager includes was reported. Including `Rinternals.h` along with the
(macOS-only) `mach/boolean.h` lead to linker error as `mach/boolean`
redefines `TRUE` leading to bad interactions with the `Rboolean` enum type. A
very simple solution is to be more careful and conservative with `#include`
files and a) have `#include <mach/boolean.h>` appear first and b) skip
the `#include <Rinternals.h>` as it is included by `Rcpp.h` anyway.

## Can we grow Rcpp vectors like STL vectors via 'push*'

No. Use actual STL vectors instead. This has been stated clearly many times going
back to the [original announcement in Feb 2010](https://lists.r-forge.r-project.org/pipermail/rcpp-devel/2010-February/000410.html),
StackOverflow answers in [Dec 2011](https://stackoverflow.com/a/8631853/143305)
and in [Dec 2012](https://stackoverflow.com/a/13783044/143305),
the rcpp-devel list in [Jun 2013](https://lists.r-forge.r-project.org/pipermail/rcpp-devel/2013-June/006078.html),
another StackOverflow answer in [Nov 2013](https://stackoverflow.com/a/19829440/143305),
an early Rcpp Gallery post in [Dec 2013](https://gallery.rcpp.org/articles/plyr-c-to-rcpp/),
again on StackOverflow [Dec 2014](https://stackoverflow.com/a/27585789/143305), as well as in
the 'Advanced R' [first](http://adv-r.had.co.nz/Rcpp.html#stl) and
[second](https://adv-r.hadley.nz/rcpp.html#stl) editions.
For emphasis, here is a quote from the [rcpp-devel post](https://lists.r-forge.r-project.org/pipermail/rcpp-devel/2013-June/006078.html):

> Those are somehow cosmetic additions. The usual suggestion is not to
> use push_front and push_back on Rcpp types.
>
> We use R's memory, and in R, resizing a vector means moving the data.
> So if you push_back 3 times, you're moving the data 3 times.
>
> Using R own memory is the best ever decision we made in Rcpp. You can
> always use your own data structures to accumulate data, perhaps using
> stl types and then convert back to R types, which is something we make
> easy to do.

Many code examples and packages show exactly that approach (as _e.g._ discussed
in the [Rcpp Gallery post](https://gallery.rcpp.org/articles/plyr-c-to-rcpp/)).
Anybody who claims otherwise is (possibly intentionally) misleading.

## Converting a large number of Date objects seems slow

The `Date` and `Datetime` classes, and their vector variants, go back a very
long time to the very beginning of \pkg{Rcpp} and use in \pkg{RQuantLib}
\citep{CRAN:RQuantLib} interfacing \pkg{QuantLib} \citep{QuantLib}. Their intent was,
essentially, to hold (single) start and end values delineating an interval.  The
design is far from optimal, but the interface is now established. We have
rewritten them once, and do not plan to rewrite them in the near future.  Those
looking to _parse and convert_ many dates at once could look at \pkg{anytime}
\citep{CRAN:anytime} where we use the Boost parser, or similar approaches using
the C++ headers-only libraries in packages \pkg{RcppCCTZ} \citep{CRAN:RcppCCTZ}
and \pkg{RcppDate} \citep{CRAN:RcppDate}. We are not likely to carry this over to
the \pkg{Rcpp} package as there are advantages in remaining dependency-free.