Converting from Rcpp

Class comparison table

Incomplete list of Rcpp features not included in cpp11

• None of Modules
• None of Sugar
• Some parts of Attributes
  • No dependencies
  • No random number generator restoration
  • No support for roxygen2 comments
  • No interfaces

Read-only vs writable vectors

The largest difference between cpp11 and Rcpp classes is that Rcpp classes modify their data in place, whereas cpp11 classes require copying the data to a writable class for modification.

The default classes, e.g. cpp11::doubles are read-only classes that do not permit modification. If you want to modify the data you need to use the classes in the cpp11::writable namespace, e.g. cpp11::writable::doubles.

In addition use the writable variants if you need to create a new R vector entirely in C++.

Fewer implicit conversions

Rcpp also allows very flexible implicit conversions, e.g. if you pass a REALSXP to a function that takes a Rcpp::IntegerVector() it is implicitly converted to a INTSXP. These conversions are nice for usability, but require (implicit) duplication of the data, with the associated runtime costs.

cpp11 throws an error in these cases. If you want the implicit coercions you can add a call to as.integer() or as.double() as appropriate from R when you call the function.

Calling R functions from C++

Calling R functions from C++ is similar to using Rcpp.

Rcpp::Function as_tibble("as_tibble", Rcpp::Environment::namespace_env("tibble"));
as_tibble(x, Rcpp::Named(".rows", num_rows), Rcpp::Named(".name_repair", name_repair));

using namespace cpp11::literals; // so we can use ""_nm syntax

auto as_tibble = cpp11::package("tibble")["as_tibble"];
as_tibble(x, ".rows"_nm = num_rows, ".name_repair"_nm = name_repair);

Appending behavior

One major difference in Rcpp and cpp11 is how vectors are grown. Rcpp vectors have a push_back() method, but unlike std::vector() no additional space is reserved when pushing. This makes calling push_back() repeatably very expensive, as the entire vector has to be copied each call.

In contrast cpp11 vectors grow efficiently, reserving extra space. Because of this you can do ~10,000,000 vector appends with cpp11 in approximately the same amount of time that Rcpp does 10,000, as this benchmark demonstrates.

library(cpp11test)
grid <- expand.grid(len = 10 ^ (0:7), pkg = "cpp11", stringsAsFactors = FALSE)
grid <- rbind(
  grid,
  expand.grid(len = 10 ^ (0:4), pkg = "rcpp", stringsAsFactors = FALSE)
)
b_grow <- bench::press(.grid = grid,
  {
    fun = match.fun(sprintf("%sgrow_", ifelse(pkg == "cpp11", "", paste0(pkg, "_"))))
    bench::mark(
      fun(len)
    )
  }
)[c("len", "pkg", "min", "mem_alloc", "n_itr", "n_gc")]
saveRDS(b_grow, "growth.Rds", version = 2)

Random Number behavior

Rcpp unconditionally includes calls to GetRNGstate() and PutRNGstate() before each wrapped function. This ensures that if any C++ code calls the R API functions unif_rand(), norm_rand(), exp_rand() or R_unif_index() the random seed state is set accordingly. cpp11 does not do this, so you must include the calls to GetRNGstate() and PutRNGstate() yourself if you use any of those functions in your C++ code. See R-exts 6.3 - Random number generation for details on these functions.

One convenient way to do safely is to use a simple class:

class local_rng {
public:
  local_rng() {
    GetRNGstate();
  }

  ~local_rng(){
    PutRNGstate();
  }
};

void foo() {
  local_rng rng_state;
  /* my code using the RNG */
}

Mechanics of converting a package from Rcpp

1. Add cpp11 to LinkingTo
2. Convert all instances of // [[Rcpp::export]] to [[cpp11::register]]
3. Clean and recompile the package, e.g. pkgbuild::clean_dll() pkgload::load_all()
4. Run tests devtools::test()
5. Start converting function by function
   • Remember you can usually inter-convert between cpp11 and Rcpp classes by going through SEXP if needed.
   • Converting the code a bit at a time (and regularly running your tests) is the best way to do the conversion correctly and make progress
   • Doing a separate commit after converting each file (or possibly each function) can make finding any regressions with git bisect much easier in the future.

Common issues when converting

// bad
cpp11::writable::logicals({FALSE});

// good
cpp11::writable::logicals({r_bool(FALSE)});

// good
cpp11::writable::logicals({FALSE, NA_LOGICAL});