---
title: "FAQ"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{FAQ}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
library(cpp11)
```
Below are some Frequently Asked Questions about cpp11.
If you have a question that you think would fit well here please [open an issue](https://github.com/r-lib/cpp11/issues/new/choose).
#### 1. What are the underlying types of cpp11 objects?
| vector | element |
| --- | --- |
| cpp11::integers | int |
| cpp11::doubles | double |
| cpp11::logical | cpp11::r_bool |
| cpp11::strings | cpp11::r_string |
| cpp11::raws | uint8_t |
| cpp11::list | SEXP |
#### 2. How do I add elements to a named list?
Use the `push_back()` method with the named literal syntax.
The named literal syntax is defined in the `cpp11::literals` namespace.
```{cpp11}
#include
[[cpp11::register]]
cpp11::list foo_push() {
using namespace cpp11::literals;
cpp11::writable::list x;
x.push_back({"foo"_nm = 1});
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 `_`.
```{cpp11}
#include
[[cpp11::register]]
double add_some_(double x, double amount) {
return x + amount;
}
```
```{r}
add_some <- function(x, amount = 1) {
add_some_(x, amount)
}
add_some(1)
add_some(1, amount = 5)
```
#### 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.
```{cpp11}
#include
[[cpp11::register]]
bool is_named(cpp11::strings x) {
return x.named();
}
```
```{r}
is_named("foo")
is_named(c(x = "foo"))
```
#### 7. How do I return a `cpp11::writable::logicals` object with only a `FALSE` value?
You need to use [list initialization](https://en.cppreference.com/w/cpp/language/list_initialization) with `{}` to create the object.
```{cpp11}
#include
[[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};
}
```
```{r}
my_false()
my_true()
my_both()
```
#### 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.
```{cpp11}
#include
[[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 return `R_UnboundValue`.
```{cpp11}
#include
[[cpp11::register]]
bool foo_exists(cpp11::environment x) {
return x["foo"] != R_UnboundValue;
}
[[cpp11::register]]
void set_foo(cpp11::environment x, double value) {
x["foo"] = value;
}
```
```{r}
x <- new.env()
foo_exists(x)
set_foo(x, 1)
foo_exists(x)
```
#### 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.
```{cpp11}
#include
[[cpp11::register]]
cpp11::raws push_raws() {
std::string x("hi");
cpp11::writable::raws out;
for (auto c : x) {
out.push_back(c);
}
return out;
}
```
```{r}
push_raws()
```
#### 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.
```{cpp11}
#include
#include
[[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
```{cpp11, eval = FALSE}
#include
#include
using namespace std;
[[cpp11::register]]
string foobar() {
return string("foo") + "-bar";
}
```
But this will compile and work as intended
```{cpp11}
#include
#include
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.
```{cpp11}
#include
[[cpp11::register]]
void add_one(cpp11::sexp x_sexp) {
cpp11::writable::integers x(std::move(x_sexp.data()));
for (auto&& value : x) {
++value;
}
}
```
```{r}
x <- c(1L, 2L, 3L, 4L)
.Internal(inspect(x))
add_one(x)
.Internal(inspect(x))
x
```