The package defines classes int64 and uint64 that represent signed and unsigned 64 bit integer vectors. The package also allows conversion of several types (integer, numeric, character, logical) to 64 bit integer vectors, arithmetic operations as well as other standard group generic functions, and reading 64 bit integer vectors as a data.frame column using int64 or uint64 as the colClasses argument.

The package has a vignette that details its features, several examples are given in the usual help files. Once again, I've used RUnit for quality insurance about the package code

int64 has been developped so that 64 bit integer vectors are represented using only R data structures, i.e data is not represented as external pointers to some C++ object. Instead, each 64 bit integer is represented as a couple of regular 32 bit integers, each of them carrying half the bits of the underlying 64 bit integer. This was a choice by design so that 64 bit integer vectors can be serialized and used as data frame columns.

The package contains C++ headers that third party packages can used (via LinkingTo: int64) to use the C++ internals. This allows creation and manipulation of the objects in C++. The internals will be documented in another vignette for package developpers who wish to use the internals. For the moment, the main entry point is the C++ template class LongVector.

I'm particularly proud that Google trusted me to sponsor the development of int64. The next versions of packages Rcpp and RProtoBuf take advantage of the facilities of int64, e.g. Rcpp gains wrapping of C++ containers of 64 bit integers as R objects of classes int64 and uint64 and RProtoBuf improves handling of 64 bit integers in protobuf messages. More on this later

We released the first version of our RcppGSL package. RcppGSL extends Rcpp to help programmers code with the GNU Scientific Library (GSL).

The package contains template classes in the RcppGSL namespace that act as smart pointers to the associated GSL data structure. For example, a RcppGSL::vector&lt:double> object acts a smart pointer to a gsl_vector*. Having the pointer shadowed by a smart pointer allows us to take advantage of C++ features such as operator overloading, etc ... which for example allows us to extract an element from the GSL vector simply using [] instead of GSL functions gsl_vector_get and gsl_vector_set

The package contains a 11 pages vignette that explains the features in details, with examples. The vignette also discusses how to actually use RcppGSL, either in another package (preferred) or directly from the R prompt through the inline package.

0.8.9 2010-11-28 (or even -27)
o Many improvements were made to in 'Rcpp modules':
- exposing multiple constructors
- overloaded methods
- self-documentation of classes, methods, constructors, fields and
functions.
- new R function "populate" to facilitate working with modules in
packages.
- formal argument specification of functions.
- updated support for Rcpp.package.skeleton.
- constructors can now take many more arguments.
o The 'Rcpp-modules' vignette was updated as well and describe many
of the new features
o New template class Rcpp::SubMatrix and support syntax in Matrix
to extract a submatrix:
NumericMatrix x = ... ;
// extract the first three columns
SubMatrix y = x( _ , Range(0,2) ) ;
// extract the first three rows
SubMatrix y = x( Range(0,2), _ ) ;
// extract the top 3x3 sub matrix
SubMatrix y = x( Range(0,2), Range(0,2) ) ;
o Reference Classes no longer require a default constructor for
subclasses of C++ classes
o Consistently revert to using backticks rather than shell expansion
to compute library file location when building packages against Rcpp
on the default platforms; this has been applied to internal test
packages as well as CRAN/BioC packages using Rcpp

Dirk uploaded Rcpp 0.8.4 to CRAN yesterday.
This release quickly follows the release of Rcpp 0.8.3, because there was some building problems (particularly on the ppc arch on OSX).

Rcpp sugar

Already available in Rcpp 0.8.3, the new sugar feature was extended in 0.8.4 to cover more functions, and we have now started to adapt sugar for matrices with functions such as outer, row, diag, etc ...

0.8.4 2010-07-09
o new sugar vector functions: rep, rep_len, rep_each, rev, head, tail, diag
o sugar has been extended to matrices: The Matrix class now extends the Matrix_Base template that implements CRTP. Currently sugar functions for matrices are: outer, col, row, lower_tri, upper_tri, diag
o The unit tests have been reorganised into fewer files with one call each to cxxfunction() (covering multiple tests) resulting in a significant speedup
o The Date class now uses the same mktime() replacement that R uses (based on original code from the timezone library by Arthur Olson) permitting wide dates ranges on all operating systems
o The FastLM/example has been updated, a new benchmark based on the historical Longley data set has been added
o RcppStringVector now uses std::vector<std::string> internally
o setting the .Data slot of S4 objects did not work properly

We released Rcpp 0.8.0 almost a month ago. It finalized our efforts in designing a better, faster and more natural API than any version of Rcpp ever before. The journey from Rcpp 0.7.0 to Rcpp 0.8.0 has mainly been a coding and testing effort for designing the API.

And now for something completely different

We have now started (with release 0.8.1 of Rcpp) a new development cycle towards the 0.9.0 version with two major goals in mind

We want to improve documentation. To that end Rcpp 0.8.1 includes 4 new vignettes. more on that later.

We want to cross the boundaries between R and C++. Rcpp 0.8.1 introduces Rcpp modules. Modules allows the programmer to expose C++ classes and functions at the R level, with great ease.

new vignettes

Rcpp-FAQ :Frequently Asked Questions about Rcpp collects some of the frequently asked questions from the mailing list and from private exchanges with many people.

Rcpp-extending: Extending Rcpp shows how to extend Rcpp converters Rcpp::wrap and Rcpp::as to user defined types (C++ classes defined in someone else's package and third party types (C++ classes defined in some third party library used by a package. The document is based on our experience developping the RcppArmadillo package

Rcpp-package : Writing a package that uses Rcpp highlights the steps involved in making a package that uses Rcpp. The document is based on the Rcpp.package.skeleton function

finally, Rcpp-modules : Exposing C++ functions and classes with Rcpp modules documents the current feature set of Rcpp modules

Rcpp modules

Rcpp modules are inspired from the Boost.Python C++ library. Rcpp modules let you expose C++ classes and functions to the R level with minimal involvment from the programmer

The feature is best described by an example (more examples on the vignette). Say we want to expose this simple class:

This would typically involve external pointers. With Rcpp modules, we can simply declare what we want to expose about this class, and Rcpp takes care of the how to expose it:

The R side consists of grabbing a reference to the module, and just use the World class

The Rcpp-modules vignette gives more details about modules, including how to use them in packages

More details about 0.8.1 release

The inline package is an amazing, yet simple, package for R. It allows to dynamically (within the R session) define R functions and S4 methods with inlined C/C++/Fortran code.

Together with RUnit, inline powers the entire unit test suite of Rcpp.

As agreed with Oleg Sklyar, who maintains inline, we made a few additions to inline to accomodate the needs of the Rcpp family of packages.

cxxfunction

The main addition is cxxfunction which is very similar to cfunction, except that it only focuses on C++ code using the .Call calling convention. cxxfunction uses a plugin system allowing other packages to control the code that is generated before compilation, environment variables, etc ... For example, the next version of
Rcpp defines an inline plugin that takes care of all the details (find the Rcpp include path, link against the Rcpp user library, etc ...)

Here is an example, from the cxxfunction help page using the Rcpp plugin (this will only work with the next version of Rcpp, because the current version does not know about this)

Here is an example using the plugin from the next version of RcppArmadillo

package.skeleton

Another addition to inline concerns the package.skeleton. We've made it S4 generic in inline and defined methods for the CFunc and CFuncList classes. In short, this allows to prototype some code using inline and quickly dump the code into a proper package

For example, here we make two functions using cxxfunction and then generate a package skeleton directly from them

Furthermore, the package.skeleton methods are aware of the plugin system, which allows plugin to have some control of additional steps involved in making the package skeleton, such as Makevars files, etc ...

getDynLib

getDynLib has been introduced in this version of inline to grab a reference to the dynamic library associated with a package, a function (CFunc object) generated by inline, or a set of functions (CFuncList object) generated by inline

This version brings some more additions to the sweave driver that uses highlight to produce nice looking vignettes with color coded R chunks

The driver gains new arguments boxes, bg and border
to control the appearance of the code chunks. When boxes is set to TRUE, the R code chunks are surrounded in boxes, and the arguments bg and border control the background color and the color of the box

Also, when the other highlight is available, the driver will also color code example code in any language that highlight supports. To use this, just surorund the code with <&ltlang=foo&gt> for the language foo. For example:

<<lang=cpp&gt>=
int main(){
return 0 ;
}
@

will output the content of the code chunk as highlighted c++. The Rcpp-modules vignette in the next version of Rcpp uses both these new features. (see the vignette source in r-forge. The vignette is rendered into latex using :

This is now fixed in version 0.1-9 and the latex renderer also gains an argument "minipage" which wraps the latex code in a minipage environment. I've used this to make this vignette for an upcoming feature of Rcpp

I've pushed version 0.1-8 of highlight to CRAN. highlight is a syntax highlighter for R that renders R source code into some markup language, the package ships html and latex renderers but is flexible enough to handle other formats. Syntax highlighting is based on information about the code gathered by a slightly modified version of the R parser, available in the separate parser package.

Since R 2.11.0, it is possible to install custom handlers to respond to http request (GET, POST, ...). highlight takes advantage of this and responds to urls with html syntax highlighted functions. So if the httpd port used by the dynamic help system is 9000 (hint: tools:::httpdPort) :

Armadillo

Armadillo is a C++ linear algebra library aiming towards a good balance
between speed and ease of use. Integer, floating point and complex numbers
are supported, as well as a subset of trigonometric and statistics
functions. Various matrix decompositions are provided through optional
integration with LAPACK and ATLAS libraries.

A delayed evaluation approach is employed (during compile time) to combine
several operations into one and reduce (or eliminate) the need for
temporaries. This is accomplished through recursive templates and template
meta-programming.

This library is useful if C++ has been decided as the language of choice
(due to speed and/or integration capabilities), rather than another language
like Matlab or Octave. It is distributed under a license that is useful in
both open-source and commercial contexts.

Armadillo is primarily developed by
Conrad Sanderson at
NICTA (Australia),
with contributions from around the world.

RcppArmadillo

RcppArmadillo
is an R package that facilitates using Armadillo classes
in R packages through Rcpp.
It achieves the integration by extending Rcpp's
data interchange concepts to Armadillo classes.

Example

Here is a simple implementation of a fast linear regression (provided by
RcppArmadillo via the
fastLm() function):

Note however that you may not want to compute a linear regression fit this
way in order to protect from numerical inaccuracies on rank-deficient
problems. The help page for
fastLm()
provides an example.

Using RcppArmadillo in other packages

RcppArmadillo
is designed so that its classes can be used from other packages.

Using RcppArmadillo requires:

Using the header files provided by Rcpp and RcppArmadillo. This is
typically achieved by adding this line in the DESCRIPTION file of the
client package:

LinkingTo : Rcpp, RcppArmadillo

and the following line in the package code:

#include <RcppArmadillo.h>

Linking against Rcpp dynamic or shared library and librairies needed
by Armadillo, which is achieved by adding this line in the src/Makevars
file of the client package

RcppArmadillo contains a function
RcppArmadillo.package.skeleton, modelled
after package.skeleton from the utils package in base R, that creates a
skeleton of a package using RcppArmadillo, including example code.

Summary

Version 0.8.0 of the Rcpp package was released to CRAN today. This release marks another milestone in the ongoing redesign of the package, and
underlying C++ library.

Overview

Rcpp is an R package and C++ library that facilitates integration of C++
code in R packages.

The package features a set of C++ classes (Rcpp::IntegerVector,
Rcpp::Function, Rcpp::Environment, ...) that makes it easier to manipulate R
objects of matching types (integer vectors, functions, environments, etc
...).

Rcpp takes advantage of C++ language features such as the explicit
constructor/destructor lifecycle of objects to manage garbage collection
automatically and transparently. We believe this is a major improvement over
PROTECT/UNPROTECT. When an Rcpp object is created, it protects the underlying
SEXP so that the garbage collector does not attempt to reclaim the
memory. This protection is withdrawn when the object goes out of
scope. Moreover, users generally do not need to manage memory directly (via
calls to new / delete or malloc / free) as this is done by the Rcpp classes
or the corresponding STL containers.

API

Rcpp provides two APIs: an older set of classes we refer to the classic API
(see below for the section 'Backwards Compatibility) as well as second and
newer set of classes.

Classes of the new Rcpp API belong to the Rcpp namespace. Each class is
associated to a given SEXP type and exposes an interface that allows
manipulation of the object that may feel more natural than the usual use of
macros and functions provided by the R API.

SEXP type

Rcpp class

INTSXP

Rcpp::IntegerVector

REALSXP

Rcpp::NumericVector

RAWSXP

Rcpp::RawVector

LGLSXP

Rcpp::LogicalVector

CPLXSXP

Rcpp::ComplexVector

STRSXP

Rcpp::CharacterVector

VECSXP

Rcpp::List

EXPRSXP

Rcpp::ExpressionVector

ENVSXP

Rcpp::Environment

SYMSXP

Rcpp::Symbol

CLOSXP

BUILTINSXP

Rcpp::Function

SPECIALSXP

LANGSXP

Rcpp::Language

LISTSXP

Rcpp::Pairlist

S4SXP

Rcpp::S4

PROMSXP

Rcpp::Promise

WEAKREFSXP

Rcpp::WeakReference

EXTPTRSXP

template < typename T> Rcpp::XPtr

Some SEXP types do not have dedicated Rcpp classes : NILSXP, DOTSXP,
ANYSXP, BCODESXP and CHARSXP.

Still missing are a few convenience classes such as Rcpp::Date or
Rcpp::Datetime which would map useful and frequently used R data types, but
which do not have an underlying SEXP type.

Data Interchange

Data interchange between R and C++ is managed by extensible and powerful yet
simple mechanisms.

Conversion of a C++ object is managed by the template function Rcpp::wrap.
This function currently manages :

primitive types : int, double, bool, float, Rbyte, ...

std::string, const char*

STL containers such as std::vector<T> and STL maps such as
std::mapr< std::string, Tr> provided that the template type T is wrappable

any class that can be implicitely converted to SEXP, through operator SEXP()

Conversion of an R object to a C++ object is managed by the Rcpp::as<T>
template which can handle:

primitive types

std::string, const char*

STL containers such as std::vector<T>

Rcpp::wrap and Rcpp::as are often used implicitely. For example, when
assigning objects to an environment:

Rcpp contains several examples that illustrate wrap and as. The mechanism was
designed to be extensible. We have developped separate packages to illustrate
how to extend Rcpp conversion mechanisms to third party types.

RcppArmadillo : conversion of types from the Armadillo C++ library.

RcppGSL : conversion of types from the GNU Scientific Library.

Rcpp is also used for data interchange by the RInside package which provides
and easy way of embedding an R instance inside of C++ programs.

inline use

Rcpp depends on the inline package by Oleg Sklyar et al. Rcpp then uses the
'cfunction' provided by inline (with argument Rcpp=TRUE) to compile, link and
load C++ function from the R session.

As of version 0.8.0 of Rcpp, we also define an R function cppfunction that
acts as a facade function to the inline::cfuntion, with specialization for
C++ use.

This allows quick prototyping of compiled code. All our unit tests are based
on cppfunction and can serve as examples of how to use the mechanism. For example
this function (from the runit.GenericVector.R unit test file) defines from
R a C++ (simplified) version of lapply:

## create a compiled function cpp_lapply using cppfunction
cpp_lapply

Using Rcpp in other packages

Rcpp is designed so that its classes are used from other packages. Using Rcpp
requires :

using the header files provided by Rcpp. This is typically done by adding this
line in the package DESRIPTION file:

LinkingTo: Rcpp

and add the following line in the package code:

#include <Rcpp.h>

linking against the Rcpp dynamic or static library, which is achieved by
adding this line to the src/Makevars of the package:

PKG_LIBS = $(shell $(R_HOME)/bin/Rscript -e "Rcpp:::LdFlags()" )

and this line to the src/Makevars.win file:

PKG_LIBS = $(shell Rscript.exe -e "Rcpp:::LdFlags()")

Rcpp contains a function Rcpp.package.skeleton, modelled after
package.skeleton from the utils package in base r, that creates a skeleton of
a package using Rcpp, including example code.

C++ exceptions

C++ exceptions are R contexts are both based on non local jumps (at least
on the implementation of exceptions in gcc), so care must be ensure
that one system does not void assumptions of the other. It is therefore
very strongly recommended that each function using C++ catches
C++ exceptions. Rcpp offers the function forward_exception_to_r
to facilitate forwarding the exception to the "R side" as an R condition.
For example :

Alternatively, functions can enclose the user code with the macros BEGIN_RCPP
and END_RCPP, which provides for a more compact way of programming. The
function above could be written as follows using the macros:

This will create a .Call compatible function "foobar" that calls a
c++ function for which we provide the argument list (int x, int y)
and the return type (int). The macro also encloses the call
in BEGIN_RCPP/END_RCPP so that exceptions are properly forwarded to R.

Quality Assurance

Rcpp uses the RUnit package by Matthias Burger et al and the aforementioned
inline package by Oleg Sklyar et al to provide unit testing.
Rcpp currently has over 500 unit tests (called from more than 230 unit test functions) with
very good coverage of the critical parts of the package and library.

Source code for unit test functions are stored in the unitTests directory
of the installed package and the results are collected in the "Rcpp-unitTests"
vignette.

The unit tests can be both during the standard R package build and testing
process, and also when the package is installed. The latter use is helpful
to ensure that no system components have changed in a way that affect the
Rcpp package since it has been installed. To run the tests, execute

Rcpp:::test()

where an output directory can be provided as an optional first argument.

Backwards Compatibility

We believe the new API is now more complete and useful than the previous set
of classes, which we refer to as the "classic Rcpp API". We would therefore
recommend to package authors using 'classic' Rcpp to move to the new API.
However, the classic API is still maintained and will continue to be
maintained to ensure backwards compatibility for code that uses it.

Packages uses the 'Classic API' can use features of the new API selectively
and in incremental steps. This provides for a non-disruptive upgrade path.

Documentation

The package contains a vignette which provides a short and succinct
introduction to the Rcpp package along with several motivating examples.
Also provided is a vignette containing the regression test summary from
the time the package was built.

A good 2 days after 0.7.6 was released, here comes Rcpp 0.7.7. The reason for this release is that a subtle bug installed itself and we did not catch it in time

The new version also includes two new class templates : unary_call and binary_call that help integration of calls (e.g. Rcpp::Language objects) with STL algorithms. For example here is how we might use
unary_call

Rcpp 0.7.6 was released yesterday. This is mostly a maintenance update since the version 0.7.5 had some very minor issues on windows, but we still managed however to include some new things as well.

Vectors can now use name based indexing. This is typically useful for things like data frame, which really are named lists. Here is an example from our unit tests where we grab a column from a data frame and then compute the sum of its values:

The classes CharacterVector,
GenericVector(aka List) and
ExpressionVector now have iterators. Below is another example from our unit tests, where we use iterators to implement a C++ version of lapply using the std::transform algorithm from the STL.

Generic vectors (lists) gain some methods that make them look more like std::vector from the STL : push_back, push_front, insert and erase. Examples of using these methods are available in our unit tests:

The main thing is the smarter wrap function that now uses techniques of type traits and template meta-programming to have a compile time guess at whether an object is wrappable, and how to do it. Currently wrappable types are :

primitive types : int, double, Rbyte, Rcomplex

std::string

STL containers such as std::vector<T> as long as T is wrappable. This is not strictly tied to the STL, actually any type that has a nested type called iterator and member functions begin() and end() will do

STL maps keyed by strings such as std::map<std::string,T> as long as T is wrappable

any class that can be implicitely converted to SEXP

any class for which the wrap template is partly or fully specialized. (The next version of RInside has an example of that)

Apart from that, other things have changed, here is the relevant section of the NEWS for this release

o wrap has been much improved. wrappable types now are :
- primitive types : int, double, Rbyte, Rcomplex, float, bool
- std::string
- STL containers which have iterators over wrappable types:
(e.g. std::vector, std::deque, std::list, etc ...).
- STL maps keyed by std::string, e.g std::map
- classes that have implicit conversion to SEXP
- classes for which the wrap template if fully or partly specialized
This allows composition, so for example this class is wrappable:
std::vector< std::map > (if T is wrappable)
o The range based version of wrap is now exposed at the Rcpp::
level with the following interface :
Rcpp::wrap( InputIterator first, InputIterator last )
This is dispatched internally to the most appropriate implementation
using traits
o a new namespace Rcpp::traits has been added to host the various
type traits used by wrap
o The doxygen documentation now shows the examples
o A new file inst/THANKS acknowledges the kind help we got from others
o The RcppSexp has been removed from the library.
o The methods RObject::asFoo are deprecated and will be removed
in the next version. The alternative is to use as.
o The method RObject::slot can now be used to get or set the
associated slot. This is one more example of the proxy pattern
o Rcpp::VectorBase gains a names() method that allows getting/setting
the names of a vector. This is yet another example of the
proxy pattern.
o Rcpp::DottedPair gains templated operator<< and operator>> that
allow wrap and push_back or wrap and push_front of an object
o Rcpp::DottedPair, Rcpp::Language, Rcpp::Pairlist are less
dependent on C++0x features. They gain constructors with up
to 5 templated arguments. 5 was choosed arbitrarily and might
be updated upon request.
o function calls by the Rcpp::Function class is less dependent
on C++0x. It is now possible to call a function with up to
5 templated arguments (candidate for implicit wrap)
o added support for 64-bit Windows (thanks to Brian Ripley and Uwe Ligges)