Overview

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 structures 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

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 these data types: 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 into C++) is performed by the Rcpp::as function template offering a similar degree of flexibility.

New features

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.

Release 0.8.1 adds support for exposing code in C++ directly to R using modules. The corresponding Rcpp-modules vignette has more details.

Release 0.8.3 adds sugar: expression templates that allow compact vectorised expression just like in R but at compiled speed; see the Rcpp-sugar vignette.

Inline use

As of version 0.8.1, an extended function 'cxxfunction' is used (which requiers inline 0.3.5). This function makes it easier to use C++ code with Rcpp. In particular, it enforces use of the .Call interface, adds the Rcpp amespace, and sets up exception forwarding. It employs the macros BEGIN_RCPP and END_RCPP macros to enclose the user code

Moreover, with cfunction (and cxxfunction), 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

Usage for package building

PKG_CXXFLAGS=$(shell Rscript -e "Rcpp:::CxxFlags()")

PKG_LIBS=$(shell Rscript -e "Rcpp:::LdFlags()")

Starting with version 0.8.0, the 'LinkingTo' argument can also be employed in packages using Rcpp. This will let R determine the location of the header files and users only need to use Rcpp::RcppLdFlags() (as detailed above) to point to the actual library.

Demo package

Class documentation

Other documentation

• The Rcpp-introduction vignette provides a short overview of Rcpp and an introduction,
• the Rcpp-package vignette shows how to write your own package using Rcpp,
• the Rcpp-FAQ vignette addresses several frequently asked questions,
• Rcpp-modules vignette discusses how to expose C++ functions and modules with ease using an idea borrowed from Boost::Python,
• the Rcpp-extending vignette details the steps needed to extend Rcpp with user-provided or third-party classes, and
• the Rcpp-unitTests vignette contains a summary of the (by now over two hundred) units tests for Rcpp.

All vignettes are also installed with the package, and available at the CRAN page.

Example usage

• 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 which provides derivative-free optimization by quadratic approximation based on an interface to Fortran implementations by M. J. D. Powell.
• pcaMethods provides Bayesian PCA, Probabilistic PCA, Nipals PCA, Inverse Non-Linear PCA and the conventional SVD PCA.
• cxxPack builds on top of Rcpp to provide literate statistical programming.
• termstrc offers a wide range of functions for term structure estimation based on static and dynamic coupon bond and yield data.
• phylobase implements a base S4 class for comparison of phylogenetic structures and data..

History

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.

Download

License

Last modified: Mon Jul 26 15:50:02 CDT 2010