RcppExamples: Simple Examples for Rcpp

Build Status License CRAN Dependencies Downloads Last Commit

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 DESCRIPTION for current R CMD check standards

  • The Rcpp package is now imported rather than depended upon.

  • Added README.md as 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.Rd from top-level directory to correct location inst/ per CRAN maintainer suggestion

Changes in RcppExamples version 0.1.5 (2012-12-27)

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.

Initially created: Thu Mar 11 11:14:31 CST 2010
Last modified: Fri Jul 31 16:17:53 CDT 2020