Overview

RcppExamples provides concrete examaples of how to use Rcpp, both the older ("classic") API and the newer one added more recently. It 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.

An Example

A simple example (using the newer API) may illustrate this:
#include <RcppClassic.h>
#include <cmath>

RcppExport SEXP newRcppVectorExample(SEXP vector) {
BEGIN_RCPP

    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);

    return Rcpp::List::create(Rcpp::Named( "result" ) = vec,
                              Rcpp::Named( "original" ) = orig) ;

END_RCPP
}

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.

Status

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 seven-hundred unit tests in Rcpp.

NEWS

The NEWS from the most recent release:
0.1.2   2010-12-20

    o   Updated src/Makevars
    
    o   Now depends also on RcppClassic so that we can keep continue to show
        examples using the classic API
    
    o   Added examples for Rcpp::Date, Rcpp::Datetime and Rcpp::List

0.1.1   2010-07-29

    o   Minor update, no new examples or documentation added yet

0.1.0   2010-03-10

    o   Initial release as a package, carved out of Rcpp 0.7.7

Where do I get it>

RcppExamples is now a CRAN package, lives otherwise in its own habitat on R-Forge within Rcpp and can also be downloaded from the local Rcpp archive.

Authors

RcppExamples is being written by Dirk Eddelbuettel and Romain Francois using Rcpp.

License

RcppExamples is licensed under the GNU GPL version 2 or later.

Last modified: Mon Mar 14 09:38:59 CDT 2011