Code
rprotobuf
rinside
rcpp
changelog
rcppexamples
rcpparmadillo
rpostgresql
rdieharder
littler
random
digest
rquantlib
beancounter
smtm
yahooquote
octave-mt
octave-pg
Linux
Quantian
About
Blog
Overview
The Rcpp package provides C++ classes that greatly facilitate interfacing C or C++ code in R packages using the.Call() interface provided by R.
Rcpp provides matching C++ classes for a large number of basic R data types. Hence, a package author can keep his data in normal R data structure without having to worry about translation or transfering to C++. At the same time, the data structures can be accessed as easily at the C++ level, and used in the normal manner.
The mapping of data types works in both directions. It is as straightforward to pass data from R to C++, as it is it return data from C++ to R. The following two sections list supported data types.
Transfer from R to C++, and from C++ to R
R data types (SEXP) are matched to C++ objects in a class hierarchy. All R types are supported (vectors, functions, environment, etc ...) and each type is mapped to a dedicated class. For example, numeric vectors are represented as instances of the Rcpp::NumericVector class, environments are represented as instances of Rcpp::Environment, functions are represented as Rcpp::Function, etc ...
The underlying C++ library also offers the Rcpp::wrap function which is a
templated function that transforms an arbitrary object into a SEXP. This
makes it straightforward to implement C++ logic in terms of standard C++
types such as STL containers and then wrap them when they need to be
returned to R. Internally, wrap uses advanced template meta programming
techniques and currently supports : primitive types (bool, int, double,
size_t, Rbyte, Rcomplex, std::string), STL containers (e.g std::vector)
where T is wrappable, STL maps (e.g std::map) where T is
wrappable, and arbitrary types that support implicit conversion to SEXP.
The reverse conversion (from R to C++) is performed by the Rcpp::as function template offering a similar degree of flexibility.
New features
Starting with release 0.7.1, a namespace Rcpp is provided. It contains a main class RObject as well as other classes that derive from RObject to deal with environments (ENVSXP) , "Language" for calls (LANGSXP) and the template XPTr for external pointers.Releases 0.7.2 and later extend this to a number of additional R types along with a number of facilities for automatic conversion thanks to clever use of templates.
Inline use
As of version 0.7.0, Rcpp also contains a modified function 'cfunction' taken from the excellent 'inline' package by Oleg Sklyar. This allows the user to define the body of a C++ function as a standard R character vector -- which is passed to 'cfunction' along with a few other parameters. The function then builds a complete C++ source file containing a function with the given body --- and then compiles, links and loads it for us. Together with the Rcpp interface classes this makes for very easy use of C++ from R --- as everything can be done from the R prompt without any need for Makefiles, configuration settings etc pp.Moreover, we can even call external libraries and have them linked as well.
Several examples of this are included with the packages; one has also been posted on my blog.
This even works on Windows if you have the working 'R tools' installed along with R. See the R-on-Windows FAQ and additional documentation.
Unit testing
As of version 0.7.8, over 210 unit tests are included in the package to ensure that no regression are introduced in terms of API compatibility. The unit tests also server as a (arguably somewhat blunt) form of examples for usage. A vignette is auto-generated with the results of the unit tests.Usage for package building
Rcpp provides a main header file Rcpp.h and a library inside the installed package in the directorylib. From within R, you can compute
the directory location via
system.file("lib", "Rcpp.h", package="Rcpp")--but both are
provided for your use via the functions Rcpp::RcppCxxFlags()
and Rcpp::RcppLdFlags() functions. So we can just use the following as a
file src/Makevars (or src/Makevars.win on Windows)
PKG_CXXFLAGS=$(shell Rscript -e "Rcpp:::CxxFlags()") PKG_LIBS=$(shell Rscript -e "Rcpp:::LdFlags()")See the help page for
Rcpp-package for details.
Demo package
The RcppExample package provides a simple illustration of how to use Rcpp, and can be used as a framework for deploying Rcpp.Class documentation
We now have Doxygen-generated documentation of all the classes in browseable and searchable html and as a pdf file. We no longer include the Doxygen-generated documentation in the source tarball as it simply too big. But we have zip archives of the html, latex, and man documentation.
Other documentation
Besides the doxygen-generated reference manual we also have two vignettes:- The rcpp-introduction provides a short overview of Rcpp and an introduction, and
- The rcpp-unitTests summary the (by now over two hundred) units tests for Rcpp.
Both vignettes are also installed with the package, and available at the CRAN page.
Example usage
The following CRAN or R-Forge packages use Rcpp:- RQuantLib, an R interface to QuantLib quantitative finance libraries
- RInside, a set of C++ classes that make it easy to embed R in your C++ applications
- EarthMoveDist, an implementation of the Earth Move distance metric for R
- RProtoBuf, an interface from R to the Google ProtoBuf library
- mvabund, a set of tools for displaying, modeling and analysing multivariate abundance data in community ecology.
- sdcTable, a package for statistical disclosure control for tabular data.
- highlight, a syntax highlighting utility based on an R parser that can render to latex and html.
- bifactorial, a package for global and multiple inference for given bi- and tri-factorial clinical trial designs.
- RcppExamples, a example package illustrating use of Rcpp and providing concrete examples.
- RcppArmadillo, an interface from R to the Armadillo C++ linear algebra library using Rcpp.
- minqa (a sub-package of the optimizers project on R-Forge) which providesa derivative-free optimization by quadratic approximation based on an interface to Fortran implementations by M. J. D. Powell.
History
Rcpp was initially written by Dominick Samperi to ease contributions to the RQuantLib project, and then released as a project in its own right. During 2006, Dominick made several releases under the RCpp name (versions 1.0 to 1.4) before he changed the name to RCppTemplate and made more releases (1.5 to 5.2). His project saw no public releases for the thirty-five months period from November 2006 to November 2009.As a user of Rcpp, I chose to adopt Rcpp during 2008, made a first release 0.6.0 in November 2008 and have made a number of new releases since -- see the ChangeLog for details. Rcpp is open for contributions and patches some of which have already been integrated.
Romain Francois joined the effort just before the 0.7.0 release and brought along a lot of energy and new ideas. We now have a mailing list for discussions around Rcpp. If you have ideas or suggested changes, send an email there.
InFrequently Asked Questions
- What about using
LinkingToin the DESCRIPTION file?
Great question, but nobody has explained yet how to do that for C++. For C, we could do what lme4 and matrix do. But for C++? The 'name mangling' really gets in the way. Let us know if you know how to do this.