FAQ

1. What are the underlying types of cpp11 objects?

2. How do I add elements to a list?

Use the push_back() method. You will need to use cpp11::as_sexp() if you want to convert arbitrary C++ objects to SEXP before inserting them into the list.

#include <cpp11.hpp>
#include <vector>

[[cpp11::register]]
cpp11::writable::list foo_push() {
  cpp11::writable::list x;

  // An object that is already a `SEXP`
  x.push_back(R_NilValue);

  // A single integer
  x.push_back(cpp11::as_sexp(1));

  // A C++ vector of ints
  std::vector<int> elt{1, 2, 3};
  x.push_back(cpp11::as_sexp(elt));

  return x;
}

To create named lists, use the push_back() method with the named literal syntax. The named literal syntax is defined in the cpp11::literals namespace. In this case, creating the named literal automatically calls as_sexp() for you.

#include <cpp11.hpp>

[[cpp11::register]]
cpp11::writable::list foo_push_named() {
  using namespace cpp11::literals;

  cpp11::writable::list x;
  x.push_back({"foo"_nm = 1});

  return x;
}

Note that if you know the size of the list ahead of time (which you often do!), then it is more efficient to state that up front.

#include <cpp11.hpp>
#include <vector>

[[cpp11::register]]
cpp11::writable::list foo_push_sized() {
  std::vector<int> elt{1, 2, 3};

  R_xlen_t size = 3;

  cpp11::writable::list x(size);
  x[0] = R_NilValue;
  x[1] = cpp11::as_sexp(1);
  x[2] = cpp11::as_sexp(elt);

  return x;
}

3. Does cpp11 support default arguments?

cpp11 does not support default arguments, while convenient they would require more complexity to support than is currently worthwhile. If you need default argument support you can use a wrapper function around your cpp11 registered function. A common convention is to name the internal function with a trailing _.

#include <cpp11.hpp>
[[cpp11::register]]
double add_some_(double x, double amount) {
  return x + amount;
}

add_some <- function(x, amount = 1) {
  add_some_(x, amount)
}
add_some(1)
#> [1] 2
add_some(1, amount = 5)
#> [1] 6

4. How do I create a new empty list?

Define a new writable list object.

cpp11::writable::list x;

5. How do I retrieve (named) elements from a named vector/list?

Use the [] accessor function.

x["foo"]

6. How can I tell whether a vector is named?

Use the named() method for vector classes.

#include <cpp11.hpp>

[[cpp11::register]]
bool is_named(cpp11::strings x) {
  return x.named();
}

is_named("foo")
#> [1] FALSE

is_named(c(x = "foo"))
#> [1] TRUE

7. How do I return a cpp11::writable::logicals object with only a FALSE value?

You need to use list initialization with {} to create the object.

#include <cpp11.hpp>

[[cpp11::register]]
cpp11::writable::logicals my_false() {
  return {FALSE};
}

[[cpp11::register]]
cpp11::writable::logicals my_true() {
  return {TRUE};
}

[[cpp11::register]]
cpp11::writable::logicals my_both() {
  return {TRUE, FALSE, TRUE};
}

my_false()
#> [1] FALSE

my_true()
#> [1] TRUE

my_both()
#> [1]  TRUE FALSE  TRUE

8. How do I create a new empty environment?

To do this you need to call the base::new.env() function from C++. This can be done by creating a cpp11::function object and then calling it to generate the new environment.

#include <cpp11.hpp>

[[cpp11::register]]
cpp11::environment create_environment() {
  cpp11::function new_env(cpp11::package("base")["new.env"]);
  return new_env();
}

9. How do I assign and retrieve values in an environment? What happens if I try to get a value that doesn’t exist?

Use [] to retrieve or assign values from an environment by name. If a value does not exist, it will error. To check for existence ahead of time, use the exists() method.

#include <cpp11.hpp>

[[cpp11::register]]
bool foo_exists(cpp11::environment x) {
  return x.exists("foo");
}

[[cpp11::register]]
void set_foo(cpp11::environment x, double value) {
  x["foo"] = value;
}

x <- new.env()

foo_exists(x)
#> [1] FALSE

set_foo(x, 1)

foo_exists(x)
#> [1] TRUE

10. How can I create a cpp11:raws from a std::string?

There is no built in way to do this. One method would be to push_back() each element of the string individually.

#include <cpp11.hpp>

[[cpp11::register]]
cpp11::raws push_raws() {
  std::string x("hi");
  cpp11::writable::raws out;

  for (auto c : x) {
    out.push_back(c);
  }

  return out;
}

push_raws()
#> [1] 68 69

11. How can I create a std::string from a cpp11::writable::string?

Because C++ does not allow for two implicit cast, explicitly cast to cpp11::r_string first.

#include <cpp11.hpp>
#include <string>

[[cpp11::register]]
std::string my_string() {
  cpp11::writable::strings x({"foo", "bar"});
  std::string elt = cpp11::r_string(x[0]);
  return elt;
}

12. What are the types for C++ iterators?

The iterators are ::iterator classes contained inside the vector classes. For example the iterator for cpp11::doubles would be cpp11::doubles::iterator and the iterator for cpp11::writable::doubles would be cpp11::writable::doubles::iterator.

13. My code has using namespace std, why do I still have to include std:: in the signatures of [[cpp11::register]] functions?

The using namespace std directive will not be included in the generated code of the function signatures, so they still need to be fully qualified. However you will not need to qualify the type names within those functions.

The following won’t compile

#include <cpp11.hpp>
#include <string>

using namespace std;

[[cpp11::register]]
string foobar() {
  return string("foo") + "-bar";
}

But this will compile and work as intended

#include <cpp11.hpp>
#include <string>

using namespace std;

[[cpp11::register]]
std::string foobar() {
  return string("foo") + "-bar";
}

14. How do I modify a vector in place?

In place modification breaks the normal semantics of R code. In general it should be avoided, which is why cpp11::writable classes always copy their data when constructed.

However if you are positive in-place modification is necessary for your use case you can use the move constructor to do this.

#include <cpp11.hpp>

[[cpp11::register]]
void add_one(cpp11::sexp x_sexp) {
  cpp11::writable::integers x(std::move(x_sexp.data()));
  for (auto&& value : x) {
    ++value;
  }
}

x <- c(1L, 2L, 3L, 4L)
.Internal(inspect(x))
#> @1059c2e88 13 INTSXP g0c2 [REF(2)] (len=4, tl=0) 1,2,3,4
add_one(x)
.Internal(inspect(x))
#> @1059c2e88 13 INTSXP g0c2 [REF(5)] (len=4, tl=0) 2,3,4,5
x
#> [1] 2 3 4 5

15. Should I call cpp11::unwind_protect() manually?

cpp11::unwind_protect() is cpp11’s way of safely calling R’s C API. In short, it allows you to run a function that might throw an R error, catch the longjmp() of that error, promote it to an exception that is thrown and caught by a try/catch that cpp11 sets up for you at .Call() time (which allows destructors to run), and finally tells R to continue unwinding the stack now that the C++ objects have had a chance to destruct as needed.

Since cpp11::unwind_protect() takes an arbitrary function, you may be wondering if you should use it for your own custom needs. In general, we advise against this because this is an extremely advanced feature that is prone to subtle and hard to debug issues.

#include <cpp11.hpp>

class A {
 public:
  ~A();
};

A::~A() {
  Rprintf("hi from the destructor!");
}

[[cpp11::register]]
void test_destructor_ok() {
  A a{};
  cpp11::unwind_protect([&] {
    Rf_error("oh no!");
  });
}

[[cpp11::register]]
void test_destructor_bad() {
  cpp11::unwind_protect([&] {
    A a{};
    Rf_error("oh no!");
  });
}

test_destructor_ok()
#> Error: oh no!
#> hi from the destructor!

test_destructor_bad()
#> Error: oh no!

#include <cpp11.hpp>

[[cpp11::register]]
void test_nested() {
  cpp11::unwind_protect([&] {
    cpp11::unwind_protect([&] {
      Rf_error("oh no!");
    });
  });
}

#include <cpp11.hpp>

[[cpp11::register]]
void test_hidden_nested() {
  cpp11::unwind_protect([&] {
    cpp11::stop("oh no!");
  });
}

#include <cpp11.hpp>

[[cpp11::register]]
void test_inner() {
  cpp11::stop("oh no!")
}

[[cpp11::register]]
void test_outer() {
  auto fn = cpp11::package("mypackage")["test_inner"]
  fn();
}

16. Ok but I really want to call cpp11::unwind_protect() manually

If you’ve read the above bullet and still feel like you need to call unwind_protect(), then you should keep in mind the following when writing the function to unwind-protect:

• You shouldn’t create any C++ objects that have destructors.
• You shouldn’t use any parts of the cpp11 API that may call unwind_protect().
• You must be very careful not to call unwind_protect() in a nested manner.

In other words, if you only use plain-old-data types, are careful to never throw exceptions, and only use R’s C API, then you can use unwind_protect().

One place you may want to do this is when working with long character vectors. Unfortunately, due to the way cpp11 must protect the individual CHARSXP objects that make up a character vector, it can currently be quite slow to use the cpp11 API for this. Consider this example of extracting out individual elements with x[i] vs using the native R API:

#include <cpp11.hpp>

[[cpp11::register]]
cpp11::sexp test_extract_cpp11(cpp11::strings x) {
  const R_xlen_t size = x.size();

  for (R_xlen_t i = 0; i < size; ++i) {
    (void) x[i];
  }

  return R_NilValue;
}

[[cpp11::register]]
cpp11::sexp test_extract_r_api(cpp11::strings x) {
  const R_xlen_t size = x.size();
  const SEXP data{x};

  cpp11::unwind_protect([&] {
    for (R_xlen_t i = 0; i < size; ++i) {
      (void) STRING_ELT(data, i);
    }
  });

  return R_NilValue;
}

set.seed(123)
x <- sample(letters, 1e6, replace = TRUE)

bench::mark(
  test_extract_cpp11(x),
  test_extract_r_api(x)
)
#> Warning: Some expressions had a GC in every iteration; so filtering is
#> disabled.
#> # A tibble: 2 × 6
#>   expression                 min   median `itr/sec` mem_alloc `gc/sec`
#>   <bch:expr>            <bch:tm> <bch:tm>     <dbl> <bch:byt>    <dbl>
#> 1 test_extract_cpp11(x)  24.05ms  24.98ms      39.7        0B     59.6
#> 2 test_extract_r_api(x)   1.12ms   1.14ms     874.         0B      0

We plan to improve on this in the future, but for now this is one of the only places where we feel it is reasonable to call unwind_protect() manually.