\tableofcontents
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} papers) for a detailed introduction, ideally followed by at least the Rcpp Attributes \citep{CRAN:Rcpp:Attributes} vignette:
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.
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:
--enable-shared-lib
option;make
etc.Also see the RStudio documentation on pre-requisites for R package development.
On almost all platforms, the GNU Compiler Collection (or gcc
, which
is also the name of its \proglang{C} language compiler) has to be used along
with the corresponding g++
compiler for the \proglang{C++} language.
A minimal suitable version is a final 4.2. release; earlier 4.2. were
lacking some \proglang{C++} features (and even 4.2.1, still used on OS X as the
last gcc release), has issues).
Generally speaking, the default compilers on all the common platforms are suitable.
Specific per-platform notes:
\begin{description}
\item[Windows] users need the \texttt{Rtools} package from the site maintained by
Duncan Murdoch 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}. As of August 2014, it still
installs the \texttt{gcc/g++} 4.6.* compiler which limits the ability to use
modern C++ standards so only \code{s-std=c++0x} is supported. R 3.1.0 and
above detect this and set appropriate flags.
\item[OS X] 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://itunes.apple.com/us/app/xcode/id497799835?mt=12}{Xcode} (OS X $\le 10.8$) or \href{https://developer.apple.com/library/ios/technotes/tn2339/_index.html}{Xcode Command Line Tools} (OS X $\ge 10.9$) (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. Depending on whether on OS X release before or after
Mavericks is used, different additional installation may be needed. 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
OS X, they are unfortunately not ABI compatible. The clang++
compiler is interesting as it emits much more comprehensible error messages
than g++
(though g++
4.8 and 4.9 have caught up).
The Intel icc
family has also been used successfully as its output
files can also be combined with those from gcc
.
Additional packages that we have found useful are:
\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}] is used for unit testing; the package is recommended and will be needed to re-run some of our tests but it is not strictly required during use of \pkg{Rcpp}; \item[\pkg{rbenchmark}] to run simple timing comparisons and benchmarks; it is also recommended but not required. \item[\pkg{microbenchmark}] is an alternative for benchmarking. \item[\pkg{devtools}] can help the process of building, compiling and testing a package but it too is entirely optional. \end{description}
The \pkg{Rcpp} package is licensed under the terms of the GNU GPL 2 or later, 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:
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). 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.
\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.
vignette("Rcpp-package")
There are two toolchains which can help with this:
The next two subsections show an example each.
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.
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
stopifnot(identical(res, sum(seq(1, 10, by=0.5))))
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}:
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.
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:
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.
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.
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 by Horner and Eddelbuettel 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 choice are provide by the \pkg{devtools} package, and by using RStudio. See the respective documentation for details.
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}
$ # if Rcpp older than 0.11.0
$ export PKG_LIBS=
Rscript -e "Rcpp:::LdFlags()"$ 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. \pkg{Rcpp} versions 0.11.0 or later can do with the definition of `PKG_LIBS` as a user-facing library is no longer needed (and hence no longer shipped with the package). One still needs to set `PKG_CXXFLAGS` 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 OS X 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. How to do so has been shown above, and we recommned you use either \faq{make-package} or \faq{using-inline} both which use the \pkg{Rcpp} function `Rcpp:::LdFlags()`. If and when `LinkingTo` changes and lives up to its name, we will be sure to adapt \pkg{Rcpp} as well. An important change arrive with \pkg{Rcpp} release 0.11.0 and concern 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. ## 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 currently _three_ 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](http://openmp.org/wp/)} standard. 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:
#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.
Below are additional resources that provide information regarding compiling Rcpp code on macOS.
r-sig-mac
list,
which is generally recommended for OS X-specific questions and further consultation.\textbf{Note:} If you are running into trouble compiling code with \pkg{RcppArmadillo}, please also see \faq{q:OSXArma} listed below.
Yes, it generally does. But as we do not have access to such systems, some issues persist on the CRAN test systems.
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).
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.
\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.
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:
DESCRIPTION
such as Imports: Rcpp
(which may
be versioned as in Imports: Rcpp (>= 0.11.0)
), andNAMESPACE
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.
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
of the R Installation and Administration
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}.
The following questions were asked on the 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 is an alternative; that site is also easily searchable.
Several dozen fully documented examples are provided at the Rcpp Gallery -- which is also open for new contributions.
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.
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.
Most certainly, consider this simple example of a templated class which squares its argument:
inc <- 'template <typename T> class square : public std::unary_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)
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.
#include <Rcpp.h> template <typename T> class square : public std::unary_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) */
\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 template library.
The following example is adapted from the examples available at the project page of Armadillo. It calculates $x' \times Y^{-1} \times z$
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}:
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.
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}.
We can also write the same example for use with Rcpp Attributes:
#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 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.
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
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.
NA
and Inf
with \pkg{Rcpp}R knows about
NA
andInf
. How do I use them from C++?
\noindent Yes, see the following example:
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:
#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 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}:
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)
Armadillo supports a full range of common linear algebra operations.
The \pkg{RcppEigen} package provides an alternative using the Eigen template library.
Rcpp Attributes, once again, makes this even easier:
#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 can I create my own plugin for use by the \pkg{inline} package?
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:
# 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 another flag to the
g++
compiler without writing a new plugin?
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 new flag
-std=c++0x
. 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.
myplugin <- getPlugin("Rcpp") myplugin$env$PKG_CXXFLAGS <- "-std=c++11" f <- cxxfunction(signature(), settings = myplugin, body = ' // fails without -std=c++0x 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 as well as for OpenMP.
Ok, I can create a matrix, but how do I set its row and columns names?
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:
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:
#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); }
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).
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
may be an alternative.
I would like to typeset the vignettes. What do I need?
The TeXLive distribution seems to get bigger and bigger. What you need to install may depend on your operating system.
Specific per-platform notes:
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.Ok, I would like to pass $N$ object but you only allow 20. How come?
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
concering data.frame creation with \pkg{Rcpp}. One solution offers a custom
ListBuilder
class to circumvent the limit; another suggests to simply
nest lists.
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:
"foo"
)10
or 4.5
)true
and false
R_NilValue
, NA_STRING
, NA_INTEGER
, NA_REAL
, and NA_LOGICAL
.::create
static member function.CharacterVector
, IntegerVector
, and NumericVector
Rcpp::<Type>Matrix n(rows,cols)
CharacterMatrix
, IntegerMatrix
, and NumericMatrix
To illustrate, please consider the following example that provides a short how-to:
#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
.
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 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
:
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.sourceCpp()
etc. For
packages, R supports it since R 3.4.0 adding the option to select the language
standard via CXX_STD = CXX14
.sourceCpp()
, or via PKG_CXXFLAGS
or
other means to set compiler options. R support may be available at a later
date.You bet. We use \proglang{doxygen} to generate html, latex and man page documentation from the source. The html documentation is available for browsing, as a very large pdf file, and all three formats are also available a zip-archives: html, latex, and man.
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.
The 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.
The normal Rcpp-devel mailing list hosting at R-forge contains an archive, which can be searched via swish.
Alternatively, one can also use Gmane on Rcpp-devel as well as Mail-Archive on Rcpp-devel both of which offer web-based interfaces, including searching.
We maintain a list of open issues in the Github repository. 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 is open for user contributions.
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.
Sure you can. Just send us an email, and we will be happy to discuss the request.
Yes. Just send us an email.
From late 2008 to late 2013, we used the Subversion repository at R-Forge 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 for \pkg{Rcpp} (as well as for \pkg{RcppArmadillo} and \pkg{RcppEigen}).
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} 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:
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.
#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:
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.
#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:
a <- 1:5 b <- 1:5 class(a) int_vec_type(a) a num_vec_type(b) b
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
constdesignation.
Simply put, one can create a new \pkg{Rcpp} object without the
constdeclaration 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:
#include <Rcpp.h> // [[Rcpp::export]] Rcpp::NumericVector const_override_ex( const Rcpp::NumericVector& X) { Rcpp::NumericVector Y(X); // Create object // from SEXP Y = Y * 2; // Modify new object return X; // Return old object }
R use:
x <- 1:10 const_override_ex(x) x
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:
#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
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. ```cpp #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:
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:
#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:
mat_scalar_assign(2L, 3.0)
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). 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).
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 is 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:
#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:
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}.
CharacterVector
produces problematic resultsThe 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:
#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:
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.
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:
#include <Rcpp.h> // [[Rcpp::export]] Rcpp::CharacterVector rcpp_sort( Rcpp::CharacterVector X) { X.sort(); return X; }
R use:
x <- c("B", "b", "c", "A", "a") sort(x) rcpp_sort(x)
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.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.