---
title: "Frequently Asked Questions"
author: "Christian Düben"
date: "October 29, 2024"
output: 
  rmarkdown::html_vignette:
    number_sections: true
vignette: >
  %\VignetteIndexEntry{Frequently Asked Questions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## What does "by reference" mean?
<p style="text-align: justify">It means that the method directly modifies the input object. You call these functions without having to assign the return value. Many of them return `NULL`. To, e.g., merge elements from container `y` into container `x`, you call `merge(x, y)`, not `x <- merge(x, y)`. Function descriptions document which methods update their input by reference (`merge`'s description: "Merge two objects by reference").</p>

## Do I have to learn C++ to use this package?
<p style="text-align: justify">No, the package documentation contains the necessary information and explains it in a language targeting R users. However, for a deeper understanding of the container types and their optimal use cases, it helps to know C++.</p>

## Why are many methods not available for all container types?
<p style="text-align: justify">That has to do with the nature of the containers. This package follows the C++ Standard Template Library in that regard.</p>

## Do I need to read the package documentation, if I know how the method works in C++?
<p style="text-align: justify">Yes. This package tweaks methods to make them more intuitive for R users. It, e.g., utilizes 1-based, not 0-based, indexing. And functions like `count` and `contains` accept a vector as an input in cppcontainers, whereas the C++ counterpart restricts it to single values. Always read the package documentation.</p>

## Why does cppcontainers not cover all Standard Template Library container methods?
<p style="text-align: justify">The first reason is that not all functions are meaningful to use from R. One example is the `equal_range` method returning iterators. A second explanation lies in the C++ standard. cppcontainers uses C++20. It, therefore, excludes methods introduced to the Standard Template Library in later standards.</p>

## Why does cppcontainers use C++20?
<p style="text-align: justify">Newer standards support more features. At the time of writing, C++20 is the newest C++ standard that quasi all R users can compile. C++23 is still too new to have almost universal coverage across machines, and it primarily introduces methods that are not well suited for use from R.</p>

## Why does my R session crash?
<p style="text-align: justify">If your session crashes, you may have triggered a segmentation fault by trying to access data out of bounds. It, e.g., occurs when you have a CppVector of length 10 and you try to access the non-existent 11th element through `x[11]`. This is the intended behavior. For computational efficiency, cppcontainers just adds a thin wrapper without further checks around many C++ methods. Use `at` to access elements with bounds checks.</p>

## Are cppcontainers objects thread-safe?
This package does not guarantee thread-safety. Do not modify cppcontainers objects across parallel processes, unless you exactly know how the interface between R and C++ and the respective C++ data structures work.

## Can I nest container types?
No, cppcontainers objects only store primitive values. Use Rcpp to compile nested container arrangements. Implementing all potential container combinations in cppcontainers would increase the size of the package exponentially.