R-Language CPP extension Support Rcpp module introduction

Overview

The Rcpp package provides C + + classes to facilitate the C or C + + code to interact with the R package, using the calling interface provided in R .Call() . Rcpp provides access to the C + + class for the underlying data type in R. The package author can maintain the data structure of r without constant conversion to C + +. At the same time, these data structures provide C + + level of access. Data types can be mapped in two directions. You can assign data to C + + from R, and return data from C + + to r is exactly the same. The supported data types are listed below.

Transfer from R to C + +, and from C + + to R

The R data type (SEXP) is consistent with C + + objects, based on the derivation of the class. All r types are supported (vectors, functions, environment, etc ...) and each pair corresponds to a class object to C + +. For example, numeric vectors represents an instance of class Rcpp::numericvector, environments represents rcpp::environment, functions represents rcpp::function, and so on ... The corresponding C + + library provides the Rcpp::wrap function, which is a template function responsible for converting data to sexp.

This makes it straightforward to implement C + + logic in terms of the standard C + + types such as STL containers and then wrap T Hem when they need to being 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::vectorwhere T is wrappable, STL maps (e.g std::map ) where T is wrappable, and arbitrary types, implicit conversi On to Sexp. The reverse conversion (from R to C + +) is performed by the Rcpp::as function template offering a similar degree of flexi Bility.

New Features

Starting with release 0.7.1, a namespace rcpp is provided. It contains a main class Robject as well as other classes this derive from Robject to deal with environments (ENVSXP), "L Anguage "for Calls (LANGSXP) and the template xptr for external pointers. Releases 0.7.2 and later extend this to a number of additional R types along with a number of facilities for automatic con Version 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-modulesvignette have more details. Release 0.8.3 addsSugar: expression templates, allow compact vectorised expression just like in R but at compiled speed; See the Rcpp-sugarvignette. Release 0.8.6 adds special functions cherished for Statistics:d/p/q/r-style for most relevant distribution, in a form tha T is very close to the what we ' d use in R. Release 0.8.7 adds support for referenceclasses in R 2.12.0; This is brings s4-based referenceclasses in the oo-style of Java or C + + to the R language. Release 0.9.0 splits support for the legacyClassic APIinto it own package rcppclassic. Release 0.10.0 bringsRcpp Attributes, enhanced modules support and more. Release 0.11.0 brings simplified builds for packages using rcpp which no longer need to link against it.

Inline use

As of version 0.7.0, Rcpp also contains a modified function ' cfunction ' taken from the excellent ' inline ' package by Oleg Sklyar. This allows the user to define the body of a C + + function as a standard R character vector--which are passed to ' cfunctio N ' along with a few and other parameters. The function then builds a complete C + + source file containing a function with the given body---and then compiles, links and loads it for us. Together with the Rcpp interface classes This makes for very easy use of C + + from R---as everything can is done from the R prompt without any need for makefiles, configuration settings etc pp.

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 has them linked as well.

Several examples of this is included with the packages; One has also been posted on MyBlog.

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.

With version 0.10.0, this have been complemented by Rcpp attributeswhich are even easier and more powerful than INL INE---See the correspondingrcpp attributesvignette for details.

Unit Testing

As of version 0.11.5, about 928 unit tests called from over 470 unit test functions is included in the package to ensure That no regressions is introduced in terms of API compatibility. The unit tests also serve as a (arguably somewhat raw) form of examples for usage. A Vignette is auto-generated with the results of the unit tests.

Usage for package Building

Rcpp provides a main header file and Rcpp.h a library inside the installed package in the directory lib . From within R, you can compute the directory location via system.file("lib", "Rcpp.h", package="Rcpp") --but Both is provided for your use via the functions Rcpp::RcppCxxFlags() and Rcpp::RcppLdFlags() functions. So we can just with the following as a file src/Makevars (or on src/Makevars.win Windows)

pkg_cxxflags= ' ${r_home}/bin/rscript-e ' rcpp:::cxxflags () "' pkg_libs= ' ${r_home}/bin/rscript-e" Rcpp:::LdFlags () "'

See the "Help" page for for Rcpp-package details. Also Note that starting with version 0.8.0, the ' linkingto ' argument can Also is employed in packages using Rcpp. This would let R determine the location of the header files and users only need to use Rcpp::RcppLdFlags() (as detailed above) to point T o The actual library, and this is clearly therecommended approach. Moreover, we added an entire vignette the "on" and "use" rcpp in the Your package with a detailed discussion. Also note, the vignette forrcpp attributesdetail another approach.

Rcpp Book

The book seamless R and C + + integration with Rcpp (Springer, $) provides a thorough and complete documentation For Rcpp, along with many examples. More information ISIS available here. The book can is ordereddirectly from Springeras well as Fromamazonand and other book sellers.

Rcpp Gallery

The Rcpp Gallery regroups over fifty contributed articles and examples for rcpp. It is an open for user contributions.

Demo Package

The Rcppexamples package (on CRAN) provides a simple illustration of "use Rcpp" and can also be used as a framework for deploying Rcpp. This are however somewhat incomplete in terms of example, so please see below for examples provides by several doze n Packages using Rcpp.

Class Documentation

We are now having doxygen-generated documentation of all the classes Inbrowseable and searchable Htmland as apdf file. We no longer include the doxygen-generated documentation in the source tarball as it simply too big. But we have zip archives of Thehtml,latex, Andman documentation.

Other documentation

Besides the doxygen-generated reference manual We also have these eight vignettes:

• The Rcpp-introduction vignette provides a short overview of Rcpp and an introduction (and have also been published as Volume, Issue 8 of thejournal of statistical software),

• 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 a idea borrowed from Boost: :P Ython,

• The rcpp-extending vignette details the steps needed to extend Rcpp with user-provided or Third-party classes,

• The Rcpp-sugar vignette provides an introduction to the rcpp sugar features inspired by vectorised R code,

• The Rcpp-attributes vignette introduces the attributes features for getting C + + into R with ease,

• The Rcpp-quickref vignette provides a quick reference cheat sheet (but is still mostly incomplete),

• The Rcpp-attributes vignette details the high-level syntax for declaring C + + functions as callable from R and shows How to automatically generate the code required to invoke them, and

• The rcpp-unittests vignette contains a summary of the (by now-over-both hundred) units tests for rcpp.

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

Google Tech Talk

In late October, the R intergrouplet at Google is kind enough to invite us for a talk on Rcpp. The resulting talk were recorded and is nowavailable on YouTube

Example usage

A long and growing list of packages using Rcpp is provideon a separate page.

History

Rcpp was initially written by Dominick Samperi to ease contributions to Therquantlibproject, and then released as a PROJEC T in it own right. During 2006, Dominick made several releases under the Rcpp name (versions 1.0 to 1.4) before he changed the name to Rcppte Mplate and made more releases (1.5 to 5.2). His project saw No. public releases for the thirty-five months period from November 2006 to November 2009. As a user of Rcpp, I (Dirk) chose to adopt Rcpp during, made a first release 0.6.0 in November and has made a n Umber of new releases since-see the ChangeLog for details. Rcpp is open for contributions and patches some of which has already been integrated. Romain francoisjoined The effort just before the 0.7.0 release and brought along a lot of energy and new ideas. We now have amailing listfor discussions around Rcpp. If you had ideas or suggested changes, send an email there.

Download

A Local archive is availablehere and Atcran; SVN access is provided atr-forge.

License

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

R-Language CPP extension Support Rcpp module introduction