FAQ

a Romain François b Source: `vignettes/rmd/Rcpp-FAQ.Rmd` `Rcpp-FAQ.Rmd` · without

vignette("Rcpp-jss-2011")
vignette("Rcpp-introduction")
vignette("Rcpp-attributes")
vignette("Rcpp-package")
fx <- cxxfunction(signature(x = "numeric"),
  'NumericVector xx(x);
   return wrap(std::accumulate(xx.begin(),
                               xx.end(), 0.0));',
   plugin = "Rcpp")
res <- fx(seq(1, 10, by=0.5))
res
## [1] 104.5
fx <- cxxfunction(signature(),
                  paste(readLines("myfile.cpp"),
                        collapse="\n"),
                  plugin = "Rcpp")
cppFunction('double accu(NumericVector x) {
  return(std::accumulate(x.begin(), x.end(), 0.0));
}')
res <- accu(seq(1, 10, by=0.5))
res
## [1] 104.5
$ R CMD INSTALL mypkg && \
     Rscript --default-packages=mypkg -e \
         'someFunctionToTickle(3.14)'
$ R CMD INSTALL mypkg && \
     r -l mypkg -e 'someFunctionToTickle(3.14)'
$ export PKG_CXXFLAGS=\
              `Rscript -e "Rcpp:::CxxFlags()"`
$ R CMD SHLIB myfile.cpp
#ifdef _OPENMP
  #include <omp.h>
#endif
#ifdef _OPENMP
    // multithreaded OpenMP version of code
#else
    // single-threaded version of code
#endif
inc <- 'template <typename T>
        class square :
          public std::function<T(T)> {
            public:
              T operator()( T t) const {
                return t*t;
              }
        };
       '

src <- '
       double x = Rcpp::as<double>(xs);
       int i = Rcpp::as<int>(is);
       square<double> sqdbl;
       square<int> sqint;
       return Rcpp::DataFrame::create(
                    Rcpp::Named("x", sqdbl(x)),
                    Rcpp::Named("i", sqint(i)));
       '
fun <- cxxfunction(signature(xs="numeric",
                             is="integer"),
                   body=src, include=inc,
                   plugin="Rcpp")

fun(2.2, 3L)
##      x i
## 1 4.84 9
#include <Rcpp.h>

template <typename T> class square :
    public std::function<T(T)> {
      public:
      T operator()( T t) const {
        return t*t ;
      }
};

// [[Rcpp::export]]
Rcpp::DataFrame fun(double x, int i) {
       square<double> sqdbl;
       square<int> sqint;
       return Rcpp::DataFrame::create(
           Rcpp::Named("x", sqdbl(x)),
           Rcpp::Named("i", sqint(i)));
}

/*** R
fun(2.2, 3L)
*/
lines = '// copy the data to armadillo structures
arma::colvec x = Rcpp::as<arma::colvec> (x_);
arma::mat Y = Rcpp::as<arma::mat>(Y_) ;
arma::colvec z = Rcpp::as<arma::colvec>(z_) ;

// calculate the result
double result = arma::as_scalar(
    arma::trans(x) * arma::inv(Y) * z);

// return it to R
return Rcpp::wrap(result);'

writeLines(a, file = "myfile.cpp")
fx <- cxxfunction(signature(x_="numeric",
                            Y_="matrix",
                            z_="numeric" ),
                  paste(readLines("myfile.cpp"),
                        collapse="\n"),
                  plugin="RcppArmadillo" )
fx(1:4, diag(4), 1:4)
#include <RcppArmadillo.h>

// [[Rcpp::depends(RcppArmadillo)]]

// [[Rcpp::export]]
double fx(arma::colvec x, arma::mat Y,
          arma::colvec z) {
    // calculate the result
    double result = arma::as_scalar(
        arma::trans(x) * arma::inv(Y) * z
    );
    return result;
}

/*** R
fx(1:4, diag(4), 1:4)
*/
fx <- cxxfunction(signature(),
                  'RNGScope();
                   return rnorm(5, 0, 100);',
                  plugin="Rcpp")
set.seed(42)
fx()
## [1] 137.096 -56.470  36.313  63.286  40.427
fx()
## [1] 137.096 -56.470  36.313  63.286  40.427
cppFunction('Rcpp::NumericVector ff(int n) {
              return rnorm(n, 0, 100);  }')
set.seed(42)
ff(5)
## [1] 137.096 -56.470  36.313  63.286  40.427
ff(5)
## [1] -10.6125 151.1522  -9.4659 201.8424  -6.2714
set.seed(42)
rnorm(5, 0, 100)
## [1] 137.096 -56.470  36.313  63.286  40.427
rnorm(5, 0, 100)
## [1] -10.6125 151.1522  -9.4659 201.8424  -6.2714
src <- 'Rcpp::NumericVector v(4);
        v[0] = R_NegInf; // -Inf
        v[1] = NA_REAL;  // NA
        v[2] = R_PosInf; // Inf
        v[3] = 42;       // c.f. Hitchhiker Guide
        return Rcpp::wrap(v);'
fun <- cxxfunction(signature(), src, plugin="Rcpp")
fun()
## [1] -Inf   NA  Inf   42
#include <Rcpp.h>

// [[Rcpp::export]]
Rcpp::NumericVector fun(void) {
    Rcpp::NumericVector v(4);
    v[0] = R_NegInf; // -Inf
    v[1] = NA_REAL;  // NA
    v[2] = R_PosInf; // Inf
    v[3] = 42;       // c.f. Hitchhiker Guide
    return v;
}
txt <- 'arma::mat Am = Rcpp::as< arma::mat >(A);
        arma::mat Bm = Rcpp::as< arma::mat >(B);
        return Rcpp::wrap( Am * Bm );'
mmult <- cxxfunction(signature(A="numeric",
                               B="numeric"),
                     body=txt,
                     plugin="RcppArmadillo")
A <- matrix(1:9, 3, 3)
B <- matrix(9:1, 3, 3)
C <- mmult(A, B)
C

#include <RcppArmadillo.h>

// [[Rcpp::depends(RcppArmadillo)]]

// [[Rcpp::export]]
arma::mat mult(arma::mat A, arma::mat B) {
    return A*B;
}

/*** R
A <- matrix(1:9, 3, 3)
B <- matrix(9:1, 3, 3)
mult(A,B)
*/
# simple example of seeding RNG and
# drawing one random number
gslrng <- '
int seed = Rcpp::as<int>(par) ;
gsl_rng_env_setup();
gsl_rng *r = gsl_rng_alloc (gsl_rng_default);
gsl_rng_set (r, (unsigned long) seed);
double v = gsl_rng_get (r);
gsl_rng_free(r);
return Rcpp::wrap(v);'

plug <- Rcpp::Rcpp.plugin.maker(
    include.before = "#include <gsl/gsl_rng.h>",
    libs = paste(
"-L/usr/local/lib/R/site-library/Rcpp/lib -lRcpp",
"-Wl,-rpath,/usr/local/lib/R/site-library/Rcpp/lib",
"-L/usr/lib -lgsl -lgslcblas -lm")
)
registerPlugin("gslDemo", plug )
fun <- cxxfunction(signature(par="numeric"),
                   gslrng, plugin="gslDemo")
fun(0)
myplugin <- getPlugin("Rcpp")
myplugin$env$PKG_CXXFLAGS <- "-std=c++11"
f <- cxxfunction(signature(),
                 settings = myplugin, body = '
    std::vector<double> x = { 1.0, 2.0, 3.0 };
    return Rcpp::wrap(x);
')
f()
src <- '
  Rcpp::NumericMatrix x(2,2);
  x.fill(42);           // or another value
  Rcpp::List dimnms =   // list with 2 vecs
    Rcpp::List::create( // with static names
      Rcpp::CharacterVector::create("cc", "dd"),
      Rcpp::CharacterVector::create("ee", "ff")
    );
  // and assign it
  x.attr("dimnames") = dimnms;
  return(x);
'
fun <- cxxfunction(signature(),
                   body=src, plugin="Rcpp")
fun()
#include <Rcpp.h>

// [[Rcpp::export]]
Rcpp::List fun(void) {
    Rcpp::NumericMatrix x(2,2);
    x.fill(42);           // or another value
    Rcpp::List dimnms =   // list with 2 vecs
      Rcpp::List::create( // with static names
        Rcpp::CharacterVector::create("cc", "dd"),
        Rcpp::CharacterVector::create("ee", "ff"));
    // and assign it
    x.attr("dimnames") = dimnms;
    return(x);
}
BigInts <- cxxfunction(signature(),
  'std::vector<long> bigints;
   bigints.push_back(12345678901234567LL);
   bigints.push_back(12345678901234568LL);
   Rprintf("Difference of %ld\\n",
       12345678901234568LL - 12345678901234567LL);
   return wrap(bigints);',
  plugin="Rcpp", includes="#include <vector>")

retval <- BigInts()

# Unique 64-bit integers were cast to identical
# lower precision numerics behind my back with
# no warnings or errors whatsoever.  Error.

stopifnot(length(unique(retval)) == 2)
#include <Rcpp.h>

// [[Rcpp::export]]
void sample_defaults(
        NumericVector x =
        NumericVector::create(), // Size 0 vector
        bool bias = true,        // Set to true
        std::string method =
            "rcpp rules!") {     // Set string

    Rcpp::Rcout << "x size: " << x.size() << ", ";
    Rcpp::Rcout << "bias value: " << bias << ", ";
    Rcpp::Rcout << "method value: " << ".";

}

/*** R
sample_defaults()                 # all defaults
sample_defaults(1:5)              # supply x values

sample_defaults(bias = FALSE,     # supply bool
                method = "Rlang") # and string
*/
conda install gxx_linux-64
void implicit_ref(NumericVector X);
void explicit_ref(NumericVector& X);
#include<Rcpp.h>

// [[Rcpp::export]]
void implicit_ref(Rcpp::NumericVector X) {
   X = X + 1.0;
}

// [[Rcpp::export]]
void explicit_ref(Rcpp::NumericVector& X) {
   X = X + 1.0;
}
a <- 1.5:4.5
b <- 1.5:4.5
implicit_ref(a)
a
## [1] 2.5 3.5 4.5 5.5
explicit_ref(b)
b
## [1] 2.5 3.5 4.5 5.5
#include<Rcpp.h>

// [[Rcpp::export]]
void int_vec_type(Rcpp::IntegerVector X) {
   X = X + 1.0;
}

// [[Rcpp::export]]
void num_vec_type(Rcpp::NumericVector X) {
   X = X + 1.0;
}
a <- 1:5
b <- 1:5
class(a)
## [1] "integer"
int_vec_type(a)
a # variable a changed as a side effect
## [1] 2 3 4 5 6
num_vec_type(b)
b # b unchanged as copy was made for numeric
## [1] 1 2 3 4 5
#include <Rcpp.h>

// [[Rcpp::export]]
Rcpp::IntegerVector const_override_ex(
        const Rcpp::IntegerVector& X) {

  Rcpp::IntegerVector Y(X); // Create object
                            // from SEXP

  Y = Y * 2;                // Modify new object

  return Y;                 // Return new object
}
x <- 1:10    # an integer sequence
# returning an altered value
const_override_ex(x)
##  [1]  2  4  6  8 10 12 14 16 18 20
# but the original value is altered too!
x
##  [1]  2  4  6  8 10 12 14 16 18 20
#include<Rcpp.h>

// [[Rcpp::export]]
std::string explicit_string_conv(
        Rcpp::CharacterVector X) {

    std::string s;  // define storage
    s = X[0];       // assign from CharacterVector

    return s;
}
error: no viable conversion from 'Proxy'
(aka 'string_proxy<16>') to 'std::string'
(aka 'basic_string<char, char_traits<char>,
allocator<char> >')
#include<Rcpp.h>

// [[Rcpp::export]]
void vec_scalar_assign(int n, double fill_val) {
  Rcpp::NumericVector X(n);
  Rcpp::Rcout << "Value of Vector " <<
      "on Creation: " <<
      std::endl << X << std::endl;

  X = fill_val;

  Rcpp::Rcout << "Value of Vector " <<
      "after Assignment: " <<
      std::endl << X << std::endl;
}
vec_scalar_assign(5L, 3.14)
## Value of Vector on Creation: 
## 0 0 0 0 0
## Value of Vector after Assignment: 
## 3.14
#include<Rcpp.h>

// [[Rcpp::export]]
void mat_scalar_assign(int n, double fill_val) {
  Rcpp::NumericMatrix X(n, n);
  Rcpp::Rcout << "Value of Matrix " <<
      "on Creation: " <<
      std::endl << X << std::endl;

  X = fill_val;

  Rcpp::Rcout << "Value of Matrix " <<
      "after Assignment: " <<
      std::endl << X << std::endl;
}
mat_scalar_assign(2L, 3.0)
## Value of Matrix on Creation: 
## 0.00000 0.00000
## 0.00000 0.00000
## 
## Value of Matrix after Assignment: 
## 0.00000 0.00000 0.00000
## 0.00000 0.00000 0.00000
## 0.00000 0.00000 0.00000
#include <Rcpp.h>
// Force compilation mode to C++11
// [[Rcpp::plugins(cpp11)]]

// [[Rcpp::export]]
bool test_long_vector_support() {
#ifdef RCPP_HAS_LONG_LONG_TYPES
  return true;
#else
  return false;
#endif
}
test_long_vector_support()
## [1] TRUE
#include <Rcpp.h>

// [[Rcpp::export]]
Rcpp::CharacterVector preferred_sort(
        Rcpp::CharacterVector x) {

  Rcpp::CharacterVector y = Rcpp::clone(x);
  y.sort();

  return y;
}

// [[Rcpp::export]]
Rcpp::CharacterVector stl_sort(
        Rcpp::CharacterVector x) {

  Rcpp::CharacterVector y = Rcpp::clone(x);
  std::sort(y.begin(), y.end());

  return y;
}
set.seed(123)
(X <- sample(c(LETTERS[1:5], letters[1:6]), 11))
##  [1] "C" "f" "B" "a" "e" "E" "D" "d" "c" "A" "b"
preferred_sort(X)
##  [1] "A" "B" "C" "D" "E" "a" "b" "c" "d" "e" "f"
stl_sort(X)
##  [1] "f" "f" "f" "f" "f" "f" "f" "f" "f" "C" "f"
#include <Rcpp.h>

// [[Rcpp::export]]
Rcpp::CharacterVector rcpp_sort(
        Rcpp::CharacterVector X) {
  X.sort();
  return X;
}
x <- c("B", "b", "c", "A", "a")
sort(x)
## [1] "a" "A" "b" "B" "c"
rcpp_sort(x)
## [1] "A" "B" "a" "b" "c"

FAQ

Dirk Eddelbuettel

Romain François

Getting started

How do I get started

What do I need

What compiler can I use

What other packages are useful

What licenses can I choose for my code

Compiling and Linking

How do I use in my package

How do I quickly prototype my code

Using inline

Using Rcpp Attributes

How do I convert my prototype code to a package

How do I quickly prototype my code in a package

But I want to compile my code with R CMD SHLIB

But R CMD SHLIB still does not work

What about LinkingTo

Does work on windows

Can I use with Visual Studio

I am having problems building Rcpp on macOS, any help

Lack of a Compiler

Differing macOS R Versions Leading to Binary Failures

OpenMP Support

Additional Information and Help

Does work on solaris/suncc

Does work with REvolution R

Is it related to Rho (formerly CXXR)

How do I quickly prototype my code using Attributes

What about the ‘no-linking’ feature

I am having problems building RcppArmadillo on macOS, any help

Examples

Can I use templates with

Using inline with Templated Code

Using Rcpp Attributes with Templated Code

Can I do matrix algebra with Rcpp

Using inline with RcppArmadillo

Using Rcpp Attributes with RcppArmadillo

Can I use code from the Rmath header and library with

Can I use NA and Inf with

Can I easily multiply matrices

How do I write a plugin for and/or Rcpp Attributes

How can I pass one additional flag to the compiler

How can I set matrix row and column names

Why can long long types not be cast correctly

What LaTeX packages do I need to typeset the vignettes

Why is there a limit of 20 on some constructors

Can I use default function parameters with

Can I use C++11, C++14, C++17, … with

How do I use it within (Python’s) Conda setup?

Can I speed up compilation?

Support

Is the API documented

Does it really work

Where can I ask further questions

Where can I read old questions and answers

I like it. How can I help

I don’t like it. How can I help

Can I have commercial support for

I want to learn quickly. Do you provide training courses

Where is the code repository

Known Issues

changed the (const) object I passed by value

Issues with implicit conversion from an object to a scalar or other object

Using operator= with a scalar replaced the object instead of filling element-wise

Long Vector support on Windows

Sorting with STL on a CharacterVector produces problematic results

Lexicographic order of string sorting differs due to capitalization

Package building fails with ‘symbols not found’

Can we use exceptions and stop() across shared libraries?

My package errors with “‘dataptr’ not provided by Rcpp”

On macOS, ‘no matching function for call to R_lsInternal’

Can we grow Rcpp vectors like STL vectors via ’push*’

Converting a large number of Date objects seems slow

What about `LinkingTo`

Can I use `NA` and `Inf` with

Using `operator=` with a scalar replaced the object instead of filling element-wise

Sorting with STL on a `CharacterVector` produces problematic results

On macOS, ‘no matching function for call to `R_lsInternal`’