Rcpp: exportAttribute – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

exportAttribute

Rcpp::export Attribute

Description

The Rcpp::export attribute is added to a C++ function definition to indicate that it should be made available as an R function. The sourceCpp and compileAttributes functions process the Rcpp::export attribute by generating the code required to call the C++ function from R.

Arguments

name

Specify an alternate name for the generated R function (optional, defaults to the name of the C++ function if not specified).

Details

Functions marked with the Rcpp::export attribute must meet several conditions to be correctly handled:

Be defined in the global namespace (i.e. not within a C++ namespace declaration).
Have a return type that is either void or compatible with Rcpp::wrap and parameter types that are compatible with Rcpp::as (see sections 3.1 and 3.2 of the Rcpp-introduction vignette for more details).
Use fully qualified type names for the return value and all parameters. However, Rcpp types may appear without the namespace qualifier (i.e. DataFrame is okay as a type name but std::string must be specified fully).

If default argument values are provided in the C++ function definition then these defaults are also used for the exported R function. For example, the following C++ function:

DataFrame readData(
    CharacterVector file, 
    CharacterVector exclude = CharacterVector::create(),
    bool fill = true)

Will be exported to R as:

function (file, exclude = character(0), fill = TRUE)

Note that C++ rules for default arguments still apply: they must occur consecutively at the end of the function signature and unlike R can't rely on the values of other arguments.

Note

When a C++ function has export bindings automatically generated by the compileAttributes function, it can optionally also have a direct C++ interface generated using the Rcpp::interfaces attribute.

The Rcpp::export attribute is specified using a syntax compatible with the new generalized attributes feature of the C++11 standard. Note however that since this feature is not yet broadly supported by compilers it needs to be specified within a comment (see examples below).

Examples

## Not run: 

#include <Rcpp.h>

using namespace Rcpp;

// [[Rcpp::export]]
int fibonacci(const int x) {

   if (x == 0) return(0);
   if (x == 1) return(1);
   
   return (fibonacci(x - 1)) + fibonacci(x - 2);
}

// [[Rcpp::export("convolveCpp")]]
NumericVector convolve(NumericVector a, NumericVector b) {

   int na = a.size(), nb = b.size();
   int nab = na + nb - 1;
   NumericVector xab(nab);
    
   for (int i = 0; i < na; i++)
      for (int j = 0; j < nb; j++)
         xab[i + j] += a[i] * b[j];
    
   return xab;
}

## End(Not run)

Rcpp

Seamless R and C++ Integration

v1.0.6

GPL (>= 2)

Authors

Dirk Eddelbuettel, Romain Francois, JJ Allaire, Kevin Ushey, Qiang Kou, Nathan Russell, Douglas Bates and John Chambers

Initial release

2021-01-14