01 - Introduction

Memory protection

The single most error-prone aspect of Rapi programming is the protection stack. Every newly allocated SEXP must be explicitly protected against garbage collection with PROTECT(), and every PROTECT() call must be matched by an UNPROTECT() call before the function returns. Counting protects is fragile: adding a branch or an early return can easily leave the stack unbalanced, causing the infamous “stack imbalance in .Call” warning or, worse, a silent segfault.

cpp4r’s writable vector types protect themselves on construction and automatically unprotect on destruction via RAII, so there is nothing to count. The [[cpp4r::register]] attribute also handles the .Call boilerplate, including wrapping the return value in an appropriate SEXP.

Example: Summing a sequence of numbers with Rapi versus cpp4r.

SEXP rapi_sum(SEXP x_sxp) {
  int n = Rf_length(x_sxp);
  SEXP out = PROTECT(Rf_allocVector(REALSXP, 1));  // must PROTECT
  double total = 0;
  double* x = REAL(x_sxp);
  for (int i = 0; i < n; ++i) total += x[i];
  REAL(out)[0] = total;
  UNPROTECT(1);  // must count manually
  return out;
}

[[cpp4r::register]] double cpp4r_sum(cpp4r::doubles x) {
  double total = 0;
  for (double v : x) total += v;
  return total;
}

Creating vectors

Rapi requires calling Rf_allocVector() with the correct SEXPTYPE constant, then protecting the result before any further allocation can happen.

SEXP rapi_make_ints() {
  SEXP out = PROTECT(Rf_allocVector(INTSXP, 3));
  INTEGER(out)[0] = 1;
  INTEGER(out)[1] = 2;
  INTEGER(out)[2] = 3;
  UNPROTECT(1);
  return out;
}

cpp4r provides typed writable classes with familiar container semantics.

[[cpp4r::register]] cpp4r::writable::integers cpp4r_make_ints() {
  cpp4r::writable::integers out;
  out.push_back(1);
  out.push_back(2);
  out.push_back(3);
  return out;
}

Or with a brace-enclosed initializer list:

[[cpp4r::register]] cpp4r::writable::integers cpp4r_make_ints() {
  return {1, 2, 3};
}

The same pattern applies to doubles, logicals, strings, and raws.

Type checking and coercion

Rapi lets you pass any SEXP anywhere. Checking that the caller supplied the right type is your responsibility.

SEXP rapi_add_one(SEXP x_sxp) {
  if (TYPEOF(x_sxp) != REALSXP) Rf_error("x must be a double vector");
  int n = Rf_length(x_sxp);
  SEXP out = PROTECT(Rf_allocVector(REALSXP, n));
  double* x = REAL(x_sxp);
  double* o = REAL(out);
  for (int i = 0; i < n; ++i) o[i] = x[i] + 1;
  UNPROTECT(1);
  return out;
}

cpp4r constructors throw an informative error automatically when the type does not match.

[[cpp4r::register]] cpp4r::writable::doubles cpp4r_add_one(cpp4r::doubles x) {
  cpp4r::writable::doubles out(x.size());
  for (R_xlen_t i = 0; i < x.size(); ++i) out[i] = x[i] + 1;
  return out;
}

For explicit coercion between compatible types, cpp4r provides as_doubles(), as_integers(), etc., which also check for loss of precision.

cpp4r::writable::doubles y;
y.push_back(10.00);
cpp4r::writable::integers i(cpp4r::as_integers(y));  // ok: 10.00 -> 10

cpp4r::writable::doubles x;
x.push_back(10.01);
cpp4r::as_integers(x);  // throws: 10.01 is not representable as int

Strings

Strings are among the trickiest types in Rapi. A character vector (STRSXP) is an array of CHARSXP pointers, each of which carries its own encoding. You must call SET_STRING_ELT() to set elements (not a plain array assignment), and you must use CHAR() or Rf_translateCharUTF8() to read them back.

cpp4r exposes r_string and strings with std::string-like comparison and iteration, and SET_STRING_ELT/STRING_ELT are hidden behind ordinary subscript operators.

Example: Print a greeting for each name in a character vector with Rapi versus cpp4r.

SEXP rapi_greet(SEXP names_sxp) {
  int n = Rf_length(names_sxp);
  SEXP out = PROTECT(Rf_allocVector(STRSXP, n));
  for (int i = 0; i < n; ++i) {
    const char* name = Rf_translateCharUTF8(STRING_ELT(names_sxp, i));
    char buf[256];
    snprintf(buf, sizeof(buf), "Hello, %s!", name);
    SET_STRING_ELT(out, i, Rf_mkCharCE(buf, CE_UTF8));
  }
  UNPROTECT(1);
  return out;
}

[[cpp4r::register]]
cpp4r::writable::strings cpp4r_greet(cpp4r::strings names) {
  cpp4r::writable::strings out(names.size());
  for (R_xlen_t i = 0; i < names.size(); ++i) {
    out[i] = "Hello, " + std::string(names[i]) + "!";
  }
  return out;
}

String construction and comparison work without encoding bookkeeping:

cpp4r::writable::strings x;
x.push_back("a");
x.push_back("b");
// x[0] == "a" works directly

Missing values (NA)

Each vector type in R has its own sentinel for missing values (NA_INTEGER, NA_REAL, NA_LOGICAL, NA_STRING, NA_COMPLEX). In Rapi you test for them differently per type, which is easy to get wrong.

// doubles: use ISNA() or ISNAN()
if (ISNA(REAL(x)[i])) { ... }
// integers: compare to NA_INTEGER directly
if (INTEGER(x)[i] == NA_INTEGER) { ... }
// strings: compare to NA_STRING
if (STRING_ELT(x, i) == NA_STRING) { ... }

cpp4r provides a uniform cpp4r::is_na() template and cpp4r::na<T>() constructor.

// Works the same way for all vector element types
if (cpp4r::is_na(x[i])) { ... }

// Create typed NAs
int    int_na  = cpp4r::na<int>(); // == NA_INTEGER
double dbl_na  = cpp4r::na<double>(); // ISNA() == true
cpp4r::r_bool  bool_na = cpp4r::na<cpp4r::r_bool>(); // == NA_LOGICAL
cpp4r::r_string str_na = cpp4r::na<cpp4r::r_string>(); // == NA_STRING

Error handling

Rf_error() in Rapi works by calling longjmp(), which unwinds the C stack without invoking C++ destructors. This means any RAII cleanup — including destructors of std::vector, std::string, file handles, etc. — is silently skipped when an R error occurs inside your code.

SEXP rapi_bad(SEXP x_sxp) {
  std::vector<double> tmp(1000); // destructor will NOT run on R error
  // ...
  Rf_error("something went wrong"); // longjmp — tmp leaks
  return R_NilValue;
}

cpp4r’s cpp4r::stop() and cpp4r::unwind_protect() use R’s unwind API to translate R errors into C++ exceptions, so destructors run correctly.

[[cpp4r::register]] void cpp4r_safe_example(cpp4r::doubles x) {
  std::vector<double> tmp(x.size());  // destructor WILL run
  // ...
  cpp4r::stop("something went wrong"); // throws unwind_exception; tmp cleaned up
}

cpp4r::safe[] is a convenience wrapper for calling Rapi functions that may throw R errors from within protected contexts:

SEXP out = cpp4r::safe[Rf_allocVector](REALSXP, 1);
// If Rf_allocVector triggers an R error, it is caught and re-thrown as
// a C++ exception rather than longjmp-ing past your destructors.

Lists

Building a named list with Rapi requires multiple PROTECT calls, manual name assignment via a character vector, and careful indexing.

cpp4r uses named-argument literals and brace initializers.

Example: Create a list with Rapi versus cpp4r.

SEXP rapi_make_list() {
  SEXP out   = PROTECT(Rf_allocVector(VECSXP, 2));
  SEXP names = PROTECT(Rf_allocVector(STRSXP, 2));

  SET_STRING_ELT(names, 0, Rf_mkChar("x"));
  SET_STRING_ELT(names, 1, Rf_mkChar("y"));

  SEXP x = PROTECT(Rf_allocVector(REALSXP, 1));
  REAL(x)[0] = 1.0;
  SET_VECTOR_ELT(out, 0, x);

  SEXP y = PROTECT(Rf_allocVector(INTSXP, 2));
  INTEGER(y)[0] = 3;
  INTEGER(y)[1] = 4;
  SET_VECTOR_ELT(out, 1, y);

  Rf_setAttrib(out, R_NamesSymbol, names);

  UNPROTECT(4);
  return out;
}

[[cpp4r::register]] cpp4r::writable::list cpp4r_make_list() {
  using namespace cpp4r::literals;
  return {
    "x"_nm = {1.0},
    "y"_nm = {3, 4},
  };
}

Pushing elements onto an existing list is equally straightforward:

cpp4r::writable::list x;
x.push_back(cpp4r::writable::doubles({1.}));
x.push_back(cpp4r::writable::integers({3, 4, 5}));
x.push_back(cpp4r::writable::strings({"foo", "bar"}));

Calling R functions from C++

Calling an R function from Rapi requires finding it in the right environment, building a pairlist of arguments, evaluating a language object, and protecting intermediates throughout.

cpp4r uses cpp4r::package() to look up exported functions, which can then be called with ordinary C++ function-call syntax.

Example: Call median(x, na.rm = TRUE) from Rapi versus cpp4r.

SEXP rapi_call_median(SEXP x_sxp) {
  SEXP fn   = PROTECT(Rf_findFun(Rf_install("median"),
                                 R_FindNamespace(Rf_mkString("stats"))));
  SEXP args = PROTECT(Rf_lang3(fn, x_sxp, Rf_ScalarLogical(1)));
  int err = 0;
  SEXP out = PROTECT(R_tryEval(args, R_GlobalEnv, &err));
  if (err) Rf_error("median() failed");
  UNPROTECT(3);
  return out;
}

[[cpp4r::register]] double cpp4r_call_median(cpp4r::doubles x) {
  auto median = cpp4r::package("stats")["median"];
  return median(x, true);  // na.rm = true
}

Named arguments work with the _nm literal:

using namespace cpp4r::literals;
double res = median("x"_nm = x, "na.rm"_nm = true);

Environments

Reading and writing variables in an R environment with Rapi requires converting names to SYMSXPs with Rf_install().

cpp4r wraps environments with subscript operators.

Example: Set and get a variable in an environment with Rapi versus cpp4r.

void rapi_set_env(SEXP env_sxp, const char* name, double value) {
  SEXP sym = Rf_install(name);
  SEXP val = PROTECT(Rf_ScalarReal(value));
  Rf_defineVar(sym, val, env_sxp);
  UNPROTECT(1);
}

double rapi_get_env(SEXP env_sxp, const char* name) {
  SEXP sym = Rf_install(name);
  SEXP val = Rf_findVarInFrame(env_sxp, sym);
  if (val == R_UnboundValue) Rf_error("'%s' not found", name);
  return REAL(val)[0];
}

[[cpp4r::register]] void cpp4r_env_roundtrip(SEXP env_sxp) {
  cpp4r::environment env(env_sxp);
  env["foo"] = 1;                              // set
  int v = cpp4r::as_cpp<int>(env["foo"]);      // get -> 1
  env.remove("foo");
}

External pointers

Wrapping a C++ object as an R external pointer with Rapi requires writing a custom finalizer function, registering it, and carefully managing the pointer lifetime.

cpp4r provides a templated external_pointer<T> that owns the pointer and runs the deleter automatically when the R object is garbage collected.

Example: Create an external pointer to a std::vector<int> with Rapi versus cpp4r.

static void my_finalizer(SEXP ptr_sxp) {
  if (R_ExternalPtrAddr(ptr_sxp)) {
    delete static_cast<std::vector<int>*>(R_ExternalPtrAddr(ptr_sxp));
    R_ClearExternalPtr(ptr_sxp);
  }
}

SEXP rapi_make_extptr() {
  std::vector<int>* v = new std::vector<int>{1, 2};
  SEXP ptr = PROTECT(R_MakeExternalPtr(v, R_NilValue, R_NilValue));
  R_RegisterCFinalizerEx(ptr, my_finalizer, TRUE);
  UNPROTECT(1);
  return ptr;
}

[[cpp4r::register]]
cpp4r::external_pointer<std::vector<int>> cpp4r_make_extptr() {
  auto* v = new std::vector<int>{1, 2};
  return cpp4r::external_pointer<std::vector<int>>(v);
}

Custom deleters are supported as a non-type template parameter:

void my_deleter(int* p) { delete p; }

cpp4r::external_pointer<int, my_deleter> ptr(new int(42));
ptr.reset();  // deleter called here

Matrices

Rapi has no matrix type distinct from vectors; a matrix is a vector with a dim attribute. Setting and reading dim must be done manually.

cpp4r provides doubles_matrix<by_row> and doubles_matrix<by_column> that expose rows or columns as slices and keep nrow() / ncol() in sync with the dim attribute automatically.

Example: Create a matrix with Rapi versus cpp4r.

SEXP rapi_make_matrix(int nrow, int ncol) {
  SEXP out = PROTECT(Rf_allocMatrix(REALSXP, nrow, ncol));
  // Column-major: element [i, j] is at index i + nrow * j
  for (int j = 0; j < ncol; ++j)
    for (int i = 0; i < nrow; ++i)
      REAL(out)[i + nrow * j] = (double)(i * ncol + j);
  UNPROTECT(1);
  return out;
}

[[cpp4r::register]]
cpp4r::writable::doubles_matrix<cpp4r::by_row> cpp4r_make_matrix() {
  cpp4r::writable::doubles_matrix<cpp4r::by_row> out(5, 2);
  // out.nrow() == 5, out.ncol() == 2
  for (R_xlen_t i = 0; i < out.nrow(); ++i)
    for (R_xlen_t j = 0; j < out.ncol(); ++j)
      out(i, j) = static_cast<double>(i * out.ncol() + j);
  return out;
}

Row or column slices can be iterated directly:

cpp4r::doubles_matrix<cpp4r::by_row> m(sexp);
auto row0 = m[0];  // a slice of the first row

Summary

The table below summarises the main improvements cpp4r provides over direct Rapi use.