RcppExamples: Simple Examples for Rcpp
RcppExamples provides concrete examaples of how to use Rcpp. It also an easy template for people wanting to use Rcpp in their packages as it will be easier to wrap one’s head around a smaller package such as RcppExamples.
An Example
A simple example may illustrate this:
#include <Rcpp.h>
#include <cmath>
using namespace Rcpp;
// suncc needs help to disambiguate between sqrt( float ) and sqrt(double)
inline static double sqrt_double( double x ){ return ::sqrt( x ); }
// [[Rcpp::export]]
List NumericVectorExample(const NumericVector & orig) {
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_double);
return List::create(Named("result") = vec,
Named("original") = orig);
}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 (which really is a standard feature of Rcpp and the Rcpp Attributes interface mechanism used here):
R> library(RcppExamples)
R> RcppExamples::RcppNumericVectorExample(1:5)
$result
[1] 1.00000 1.41421 1.73205 2.00000 2.23607
$original
[1] 1 2 3 4 5
R> RcppNumericVectorExample(c("tic", "tac", "toe"))
Error: not compatible with requested type
R> Status
RcppExamples does not document every class but it should already provide a fairly decent start for using Rcpp. Many more actual usage examples are … in the over one thousand unit tests in Rcpp — and of course in by now almost one hundred examples of the Rcpp Gallery.
NEWS
The NEWS from all releases:
Changes in RcppExamples version 0.1.7 (2016-01-23)
All examples were updated to use Rcpp Attributes and (where possible) use
const &interfaces.Updated
DESCRIPTIONfor currentR CMD checkstandardsThe Rcpp package is now imported rather than depended upon.
Added
README.mdas well as.travis.yml.Also updated and refreshed all manual pages and R files.
Changes in RcppExamples version 0.1.6 (2013-01-15)
Moved
NEWS.Rdfrom top-level directory to correct locationinst/per CRAN maintainer suggestionChanges in RcppExamples version 0.1.5 (2012-12-27)
Moved all examples using RcppClassic to a new package RcppClassicExamples
Various minor small updates
Changes in RcppExamples version 0.1.4 (2012-08-09)
Added new example for Rcpp sugar and vectorised draws of RNGs
Minor updates to reflect newer CRAN Policy
Changes in RcppExamples version 0.1.3 (2011-12-28)
Added new example for Rcpp::DataFrame
Switched two examples from using std::cout (which ‘Writing R Extensions’ recommends agains) to the new Rcpp::Rcout device
Minor .Rd correction, suppressing one warning
Changes in RcppExamples version 0.1.2 (2010-12-20)
Updated src/Makevars
Now depends also on RcppClassic so that we can keep continue to show examples using the classic API
Added examples for Rcpp::Date, Rcpp::Datetime and Rcpp::List
Changes in RcppExamples version 0.1.1 (2010-07-29)
Minor update, no new examples or documentation added yet
Changes in RcppExamples version 0.1.0 (2010-03-10)
Initial release as a package, carved out of Rcpp 0.7.7
Where do I get it?
RcppExamples is now a CRAN package and lives otherwise in its own repo on GitHub.
Authors
RcppExamples is being written by Dirk Eddelbuettel and Romain Francois.
Licence
RcppExamples is licensed under the GNU GPL version 2 or later.