This repo aims to provide some useful additional information about R's internal C API, or Rapi for short. This site draws heavily from Section 5 ("System and foreign language interfaces") of Writing R extensions, R internals, and inspection of R's source code to see how functions are used.
Here we focus on best practices and modern tools. To wit, we recommend that you use R_NO_REMAP
so all API functions have the prefix R_
or Rf_
:
#define R_NO_REMAP
#include <R.h>
#include <Rinternals.h>
(Including <Rinternals.h>
seems like bad form. However, it doesn't actually give you access to the "internal" internal API unless you set some additional flags. Instead it lets you access the "public" internal API, which is both necessary and safe. Yes, this is confusing.)
At the C-level, all R objects are stored in a common datatype, the SEXP
, or S-expression. A SEXP
is a variant type, with subtypes or SEXPTYPE
s for all R's data structures. This site roughly breaks Rapi into chapters based on the SEXPTYPE
the functions work with:
-
Vectors cover the most important data structures: vectors. This includes
LGLSXP
,INTSXP
,REALSXP
,CPLXSXP
,STRSXP
,VECSXP
,RAWSXP
, andEXPRSXP
. -
Strings: Character vectors are a more complex object made of vector
CHARSXP
s. -
Environments, or
ENVSXP
s. -
Functions, including
CLOSXP
s and the rarerBUILTINSXP
s,SPECIALSXP
s andFUNSXPs
. -
Symbols,
SYMSXP
s. -
Pairlists, including
LISTSXP
s and the relatedNILSXP
,LANGSXP
, andDOTSXP
. This chapter also includes a discussion of attributes, which are powered by pair lists. -
External pointers, or
XPTRSXP
s.
Other categories are: