As mentioned in the post about release 0.7.8 of Rcpp, Romain and I carved this out of Rcpp itself to provide a cleaner separation of code that implements our R / C++ interfaces (which remain in Rcpp) and code that illustrates how to use it --- which is now in RcppExamples. This also provides an easier template for people wanting to use Rcpp in their packages as it will be easier to wrap one's head around the much smaller RcppExamples package.
A simple example (using the newer API) may illustrate this:
#include <Rcpp.h> RcppExport SEXP newRcppVectorExample(SEXP vector) { Rcpp::NumericVector orig(vector); // keep a copy (as the classic version does) Rcpp::NumericVector vec(orig.size()); // create a target vector of the same size // we could query size via // int n = vec.size(); // and loop over the vector, but using the STL is so much nicer // so we use a STL transform() algorithm on each element std::transform(orig.begin(), orig.end(), vec.begin(), sqrt); Rcpp::Pairlist res(Rcpp::Named( "result", vec), Rcpp::Named( "original", orig)); return res; }
With essentially five lines of code, we provide a function that takes any numeric vector and returns both the original vector and a tranformed version---here by applying a square root operation. Even the looping along the vector is implicit thanks to the generic programming idioms of the Standard Template Library.
Nicer still, even on misuse, exceptions get caught cleanly and we get returned to the R prompt without any explicit coding on the part of the user:
R> library(RcppExamples) Loading required package: Rcpp R> print(RcppVectorExample( 1:5, "new" )) # select new API $result [1] 1.000 1.414 1.732 2.000 2.236 $original [1] 1 2 3 4 5 R> RcppVectorExample( c("foo", "bar"), "new" ) Error in RcppVectorExample(c("foo", "bar"), "new") : not compatible with INTSXP R>
There is also analogous code for the older API in the package, but it is about three times as long, has to loop over the vector and needs to set up the execption handling explicitly.
As of right now, RcppExamples does not document every class but it should already provide a fairly decent start for using Rcpp. And many more actual usage examples are ... in the over two-hundred unit tests in Rcpp.
Update: Now actually showing new rather than classic API.