1. C++ functions belong to C++ files
In the first chapter
2. Previously, in this course
you used the "evalCpp()" function to evaluate simple C++ expressions, and "cppFunction()" to define simple C++ functions directly from the console or from an R script. These are great tools to get started but they don't match the typical experience of writing C++ code with Rcpp.
3. Using .cpp files
The next step is to use files with "(dot)cpp" extensions to host C++ code that may contain one or more C++ functions to be exposed to the R side.
Here you have an example of a cpp file that defines a C++ function called "timesTwo()". On the R side, you can use the function "sourceCpp()" from Rcpp to compile and load the function into your global environment.
Let's break down, and see what happens in this (dot)cpp file.
4. Include the Rcpp header file
The Rcpp package contains a C++ library which consists of various interdependent header files. Header files contain functions which can be used in any program by using the hash include directive.
Rcpp is made of thousands of lines of C++ code, spread in multiple header files for its own organization, but you don't need to worry about any of that, because all of these files are included in a convenient order when you use "#include <Rcpp.h>".
Most of the time, "Rcpp.h" is the only header file you need when you write C++ code with Rcpp.
5. Using the Rcpp namespace
C++ namespaces are a convenient way to group together objects that are related, in such a way that they are isolated from the rest of the codebase. Two different namespaces could define the same function and the colon colon operator, also known as the namespace operator, can be used to specify which of these namespaces you want the function from. This is similar to calling a function in R without attaching its package.
When writing code that uses the Rcpp codebase, you will use objects from the Rcpp namespace.
To avoid repeating their origin, you can add the "using namespace Rcpp" directive. This is similar to loading an R package with the library to avoid prefixing all of the functions you use from it.
In this particular example, the using directive is actually not needed because we don't use anything from Rcpp yet, but it is a good practice to always have it because soon enough you will.
6. Exporting the function to R
When you write several C++ functions, you would rather have the functions that deal with low-level implementations hidden from R. We call these internal functions. And the functions you want to call from R, are called exported functions.
The third line in the cpp file here is a comment, but a very special comment. It is a comment to express that
7. The function itself
what directly follows is an exported C++ function.
Rcpp uses the special export comment to alter your code before it is compiled and generate boilerplate code that acts as an interface between the R world and the C++ world.
By the way, if you are still not sure if you get the difference between internal and exported functions, don't worry. You will see them in the next video!
8. source the C++ file
Once you have written the C++ function and decorated it with the special "Rcpp::export" comment, you can load it into the R session with the "sourceCpp()" function.
Even though very different mechanisms are in place here, you can view "sourceCpp()" as an equivalent to the source function from base R, but for C++ code.
9. Let's practice!
Time for practice!