RcppHoney Introduction
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.
Rationale
In C++ we often have containers that are not compatible with R or Rcpp
with data already in them (std::vector, std::set, etc.). One would like
to be able to operate on these containers without having to copy them into
Rcpp structures like IntegerVector. RcppHoney aims to address this
problem by providing operators and functions with R semantics that can be
used on any iterator-based container.
Introduction
RcppHoney allows any iterator-based container to be “hooked” in. Once a
container type is hooked to RcppHoney, it is granted operators (+, -, *, /, etc.)
and a host of other mathematical functions that can be run on it. It also
becomes interoperable with any other hooked data structure. This lets us
write expressions that look like std::vector + Rcpp::IntegerVector +
log(Rcpp::NumericVector) and get the expected results.
Implementation
RcppHoney has several structures that are hooked in by default. Currently
they are std::vector, std::set, and Rcpp::VectorBase. The ability to
hook in custom structures is also provided.
All operators and functions are implemented as
expression templates
to minimize memory usage and enhance performance. The goal here is to only
copy the data into an R compatible structure when we must (i.e. when we
return it to R). This is achieved through the use of the RcppHoney::operand
class. RcppHoney::operand provides an iterable interface to the result
types of operators and functions.
RcppHoney currently provides all the basic mathematical operators (+, -, *, /)
as well as some common
functions
(abs, sin, cos, exp, etc.). Eventually all of the functionality provided by
Rcpp::sugar as well as anything else we can think of will be supported.
Enough about the abstract though…let’s see it in action.
Example
The following example shows how to hook in a custom data structure
(in this case std::list) as well as the types of expressions that can be
created once a data structure is hooked in.
// [[Rcpp::depends(RcppHoney)]]
#include <RcppCommon.h>
#include <RcppHoneyForward.hpp> // we have to do this because we're going to hook in a non-default structure
#include <list>
// We have to declare our hooks before we include RcppHoney.hpp
namespace RcppHoney {
namespace hooks {
// Hook in all std::list types (could be more specific)
template< typename T, typename A >
traits::true_type is_hooked(const std::list< T, A > &val);
// Tell RcppHoney that NA has meaning in std::list
template< typename T, typename A >
traits::true_type has_na(const std::list< T, A > &val);
// Tell RcppHoney that it needs to create basic (e.g. std::list + std::list) operators
template< typename T, typename A >
traits::true_type needs_basic_operators(const std::list< T, A > &val);
// Tell RcppHoney that it needs to create scalar (e.g. std::list + int/double) operators
template< typename T, typename A >
traits::true_type needs_scalar_operators(const std::list< T, A > &val);
// Tell RcppHoney that this set of types is part of the FAMILY_USER + 1 family.
// This is used in conjunction with needs_basic_operators. If you have
// needs_basic_operators return RcppHoney::traits::false_type, then only types
// that are not part of the same family will have binary operators created
// between them.
template< typename T, typename A >
traits::int_constant< FAMILY_USER + 1 > family(const std::list< T, A > &val);
} // namespace hooks
} // namespace RcppHoney
#include <RcppHoney.hpp>
// [[Rcpp::export]]
Rcpp::NumericVector example_manually_hooked() {
// We manually hooked std::list in to RcppHoney so we'll create one
std::list< int > l;
l.push_back(1); l.push_back(2); l.push_back(3); l.push_back(4); l.push_back(5);
// std::vector is already hooked in to RcppHoney in default_hooks.hpp so we'll
// create one of those too
std::vector< int > v(l.begin(), l.end());
// And for good measure, let's create an Rcpp::NumericVector which is also hooked by default
Rcpp::NumericVector v2(v.begin(), v.end());
// Now do some weird operations incorporating std::vector, std::list, Rcpp::NumericVector
// and some RcppHoney functions and return it. The return value will be equal to the following
// R snippet:
// v <- 1:5
// result <- 42 + v + v + log(v) - v - v + sqrt(v) + -v + 42
// We can store our result in any of RcppHoney::LogicalVector, RcppHoney::IntegerVector, or
// RcppHoney::NumericVector and simply return it to R. These classes inherit from their
// Rcpp counterparts and add a new constructor. The only copy of the data, in this case, is when
// we assign our expression to retval. Since it is then a "native" R type, returning it is a
// shallow copy. Alternatively we could write this as:
// return Rcpp::wrap(1 + v + RcppHoney::log(v) - v - 1 + RcppHoney::sqrt(v) + -v2);
RcppHoney::NumericVector retval
= 42 + l + v + RcppHoney::log(v) - v - l + RcppHoney::sqrt(v) + -v2 + 42;
return retval;
}Conclusion
RcppHoney is a powerful tool for allowing different container types to interoperate
under Rcpp. It can save development time as well as help the user generate faster
and more readable code.
RcppHoney is available via CRAN though as it is still
in an alpha state and changing rapidly, it is recommended that you install it from
source. Source code is available at
github.com/dcdillon/RcppHoney.
R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.