Rcpp: cppFunction – R documentation

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

cppFunction

Define an R Function with a C++ Implementation

Description

Dynamically define an R function with C++ source code. Compiles and links a shared library with bindings to the C++ function then defines an R function that uses .Call to invoke the library.

Usage

cppFunction(code, depends = character(), plugins = character(), includes = character(),
            env = parent.frame(), rebuild = FALSE, cacheDir = getOption("rcpp.cache.dir", 
            tempdir()), showOutput = verbose, verbose = getOption("verbose"))

Arguments

`code`	Source code for the function definition.
`depends`	Character vector of packages that the compilation depends on. Each package listed will first be queried for an inline plugin to determine header files to include. If no plugin is defined for the package then a header file based the package's name (e.g. `PkgName.h`) will be included.
`plugins`	Character vector of inline plugins to use for the compilation.
`includes`	Character vector of user includes (inserted after the includes provided by `depends`).
`env`	The environment in which to define the R function. May be `NULL` in which case the defined function can be obtained from the return value of `cppFunction`.
`rebuild`	Force a rebuild of the shared library.
`cacheDir`	Directory to use for caching shared libraries. If the underlying code passed to `sourceCpp` has not changed since the last invocation then a cached version of the shared library is used. The default value of `tempdir()` results in the cache being valid only for the current R session. Pass an alternate directory to preserve the cache across R sessions.
`showOutput`	`TRUE` to print `R CMD SHLIB` output to the console.
`verbose`	`TRUE` to print detailed information about generated code to the console.

Details

Functions defined using cppFunction must have return types that are compatible with Rcpp::wrap and parameter types that are compatible with Rcpp::as.

The shared library will not be rebuilt if the underlying code has not changed since the last compilation.

Value

An R function that uses .Call to invoke the underlying C++ function.

Note

You can also define R functions with C++ implementations using the sourceCpp function, which allows you to separate the C++ code into it's own source file. For many use cases this is an easier and more maintainable approach.

Examples

## Not run: 

cppFunction(
    'int fibonacci(const int x) {
        if (x == 0) return(0); 
        if (x == 1) return(1);
        return (fibonacci(x - 1)) + fibonacci(x - 2);
    }')

cppFunction(depends = "RcppArmadillo",
    'List fastLm(NumericVector yr, NumericMatrix Xr) {
        
        int n = Xr.nrow(), k = Xr.ncol();
        
        arma::mat X(Xr.begin(), n, k, false); 
        arma::colvec y(yr.begin(), yr.size(), false);
        
        arma::colvec coef = arma::solve(X, y);
        arma::colvec resid = y - X*coef;
        
        double sig2 = arma::as_scalar(arma::trans(resid)*resid/(n-k) );
        arma::colvec stderrest = arma::sqrt(
            sig2 * arma::diagvec(arma::inv(arma::trans(X)*X)));
        
        return List::create(Named("coefficients") = coef,
            Named("stderr")       = stderrest
        );
    }')
    
cppFunction(plugins=c("cpp11"), '
    int useCpp11() {
        auto x = 10;
        return x;
    }')
    

## 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