In RcppCore/Rcpp: Seamless R and C++ Integration

without

knitr::opts_chunk$set(cache=FALSE)
library(Rcpp)
library(inline)
options("width"=50, digits=5)

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

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

This first installs the packages, and then uses the command-line tool
\rdoc{utils}{Rscript} (which ships with `R`) to load the package, and execute
the \proglang{R} expression following the `-e` switch. Such an
expression can contain multiple statements separated by semicolons.
\rdoc{utils}{Rscript} is available on all three core operating systems.

On Linux, one can also use `r` from the `littler` package
\citep{CRAN:littler} which is an alternative front end to \proglang{R}
designed for both `#!` (hashbang) scripting and command-line use. It has
slightly faster start-up times than \rdoc{utils}{Rscript}; and both give a
guaranteed clean slate as a new session is created.

The example then becomes

```{bash, eval = FALSE}
$ R CMD INSTALL mypkg && \
     r -l mypkg -e 'someFunctionToTickle(3.14)'

which first defines and exports two relevant environment variables which
`R CMD SHLIB` then relies on.  On other operating systems, appropriate
settings may have to be used to define the environment variables.

This approach corresponds to the very earliest ways of building programs and
can still be found in some deprecated documents (as _e.g._ some of
Dirk's older 'Intro to HPC with R' tutorial slides).  It is still not
recommended as there are tools and automation mechanisms that can do the work
for you.

Note that we always need to set `PKG_CXXFLAGS` (or equally `PKG_CPPFLAGS`) to tell R
where the \pkg{Rcpp} headers files are located.

Once `R CMD SHLIB` has created the dyanmically-loadable file (with
extension `.so` on Linux, `.dylib` on macOS or `.dll` on
Windows), it can be loaded in an R session via \rdoc{base}{dyn.load}, and the
function can be executed via \rdoc{base}{.Call}.  Needless to say, we
\emph{strongly} recommend using a package, or at least Rcpp Attributes as
either approach takes care of a lot of these tedious and error-prone manual
steps.

## But R CMD SHLIB still does not work

We have had reports in the past where build failures occurred when users had
non-standard code in their `~/.Rprofile` or `Rprofile.site` (or
equivalent) files.

If such code emits text on `stdout`, the frequent and implicit
invocation of `Rscript -e "..."` (as in \faq{using-r-cmd-shlib}
above) to retrieve settings directly from \pkg{Rcpp} will fail.

You may need to uncomment such non-standard code, or protect it by wrapping
it inside `if (interactive())`, or possibly try to use
`Rscript --vanilla` instead of plain `Rscript`.

## What about `LinkingTo `

\proglang{R} has only limited support for cross-package linkage.

We now employ the `LinkingTo` field of the `DESCRIPTION` file
of packages using \pkg{Rcpp}. But this only helps in having \proglang{R}
compute the location of the header files for us.

The actual library location and argument still needs to be provided by the
user. This topic can get complicated real quickly, and there is an entire
vignette devoted to it, so see \citet{CRAN:Rcpp:Libraries}.

Also note that an important change arrived with \pkg{Rcpp} release 0.11.0 and
concerns the automatic registration of functions; see
Section \ref{function-registration} below.

## Does \pkg{Rcpp} work on windows

Yes of course. See the Windows binaries provided by CRAN.

## Can I use \pkg{Rcpp} with Visual Studio

Not a chance.

And that is not because we are meanies but because \proglang{R} and Visual
Studio simply do not get along. As \pkg{Rcpp} is all about extending
\proglang{R} with \proglang{C++} interfaces, we are bound by the available
toolchain.  And \proglang{R} simply does not compile with Visual Studio. Go
complain to its vendor if you are still upset.

(These days the 'Code' editor derived from it is popular and can of course be
used with \proglang{R} and \pkg{Rcpp}; see its documentation for the required
plugins. Such use still falls back to the default compilers \proglang{R} is
used with on the given system so see \faq{q:what-compiler} above.)

## I am having problems building Rcpp on macOS, any help  {#q:OSX}

There are three known issues regarding Rcpp build problems on macOS.  If you are
building packages with RcppArmadillo, there is yet another issue that is
addressed separately in \faq{q:OSXArma} below.

### Lack of a Compiler

By default, macOS does not ship with an active compiler. Depending on the
\proglang{R} version being used, there are different development environment
setup procedures. For the current \proglang{R} version, we recommend observing
the official procedure used in
[Section 6.3.2 macOS](https://cran.r-project.org/doc/manuals/r-release/R-admin.html#macOS-packages)
and [Section C.3 macOS](https://cran.r-project.org/doc/manuals/r-release/R-admin.html#macOS)
of the [R Installation and Administration](https://cran.r-project.org/doc/manuals/r-release/R-admin.html)
manual.

### Differing macOS R Versions Leading to Binary Failures

There are _three_ (or more) distinct versions of R for macOS.
The first version is a legacy version meant for macOS 10.6 (Snow Leopard) -
10.8 (Mountain Lion). The second version is for more recent system
macOS 10.9 (Mavericks) and 10.10 (Yosemite). Finally, the third and most
up-to-date version supports macOS 10.11 (El Capitan), 10.12 (Sierra), and 10.13 (High Sierra).
The distinction comes as a result of a change in the compilers shipped with the
operating system as highlighted previously. As a result, avoid sending
\textbf{package binaries} to collaborators if they are working on older
operating systems as the \proglang{R} binaries for these versions will not be
able to mix. In such cases, it is better to provide collaborators with the
\textbf{package source} and allow them to build the package locally.

### OpenMP Support

By default, the macOS operating environment lacks the ability to parallelize
sections of code using the [\proglang{OpenMP}
standard](http://openmp.org/wp/).  Within \proglang{R} 3.4.*, the default
developer environment was _changed_ to allow for \proglang{OpenMP} to be used
on macOS by using a non-default toolchain provided by R Core Team maintainers
for macOS.  Having said this, it is still important to protect any reference
to \proglang{OpenMP} as some users may not yet have the ability to use
\proglang{OpenMP}.

To setup the appropriate protection for using \proglang{OpenMP}, the process
is two-fold. First, protect the inclusion of headers with:

```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)

#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()
fx()

cppFunction('Rcpp::NumericVector ff(int n) {
              return rnorm(n, 0, 100);  }')
set.seed(42)
ff(5)
ff(5)
set.seed(42)
rnorm(5, 0, 100)
rnorm(5, 0, 100)

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()

#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
explicit_ref(b)
b

#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)
int_vec_type(a)
a # variable a changed as a side effect
num_vec_type(b)
b # b unchanged as copy was made for numeric

#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)
# but the original value is altered too!
x

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

The second way to help the compiler is to use an explicit \pkg{Rcpp} type conversion
function, if one were to exist. Examples of \pkg{Rcpp} type conversion functions
include `as<T>()`, `.get()` for `cumsum()`, `is_true()`
and `is_false()` for `any()` or `all()`.

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

Assignment using the `operator=` with either `Vector` and
`Matrix` classes will not elicit an element-wise fill. If you seek an
element-wise fill, then use the `.fill()` member method to propagate a
single value throughout the object. With this being said, the behavior of
`operator=` differs for the `Vector` and `Matrix` classes.

The implementation of the `operator=` for the `Vector` class will
replace the existing vector with the assigned value. This behavior is valid
even if the assigned value is a scalar value such as 3.14 or 25 as the object
is cast into the appropriate \pkg{Rcpp} object type. Therefore, if a
`Vector` is initialized to have a length of 10 and a scalar is assigned
via `operator=`, then the resulting `Vector` would have a length of
1. See the following code snippet for the aforementioned behavior.

```{Rcpp}
#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)

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

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

#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))
preferred_sort(X)
stl_sort(X)

#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)
rcpp_sort(x)

RcppCore/Rcpp Seamless R and C++ Integration

In RcppCore/Rcpp: Seamless R and C++ Integration

Getting started

How do I get started

What do I need

What compiler can I use {#q:what-compiler}

What other packages are useful

What licenses can I choose for my code

Compiling and Linking

How do I use \pkg{Rcpp} in my package {#make-package}

How do I quickly prototype my code

Using inline

Using Rcpp Attributes {#using-attributes}

How do I convert my prototyped code to a package {#from-inline-to-package}

How do I quickly prototype my code in a package {#using-a-package}

But I want to compile my code with R CMD SHLIB {#using-r-cmd-shlib}

Additional Information and Help

Does \pkg{Rcpp} work on solaris/suncc

Does \pkg{Rcpp} work with REvolution R

Is it related to Rho (formerly CXXR)

How do I quickly prototype my code using Attributes {#prototype-using-attributes}

What about the 'no-linking' feature {#function-registration}

I am having problems building RcppArmadillo on macOS, any help {#q:OSXArma}

Examples

Can I use templates with \pkg{Rcpp}

Using inline with Templated Code

Using Rcpp Attributes with Templated Code

Can I do matrix algebra with Rcpp {#matrix-algebra}

Using inline with RcppArmadillo {#using-inline-armadillo}

Using Rcpp Attributes with RcppArmadillo

Can I use code from the Rmath header and library with \pkg{Rcpp}

Can I use NA and Inf with \pkg{Rcpp}

Can I easily multiply matrices

How do I write a plugin for \pkg{inline} 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 \pkg{Rcpp}

Can I use C++11, C++14, C++17, ... with \pkg{Rcpp}

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 {#helping}

I don't like it. How can I help {#dont-like-help}

Can I have commercial support for \pkg{Rcpp}

I want to learn quickly. Do you provide training courses

Where is the code repository

Known Issues

\pkg{Rcpp} changed the (const) object I passed by value

Issues with implicit conversion from an \pkg{Rcpp} object to a scalar or other \pkg{Rcpp} object

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

R Package Documentation

Browse R Packages

We want your feedback!

RcppCore/Rcpp
Seamless R and C++ Integration

Can I use `NA` and `Inf` with \pkg{Rcpp}

Sorting with STL on a `CharacterVector` produces problematic results

On macOS, 'no matching function for call to `R_lsInternal`'