Merge pull request #1167 from RcppCore/feature/faq_addition

Add FAQ entry on growing vectors

.Rbuildignore

@@ -28,3 +28,4 @@ vignettes/Makefile
 vignettes/rmd
 \.github
 ^issue.*\.md
+^note.*\.md

ChangeLog

@@ -1,3 +1,7 @@
+2021-07-24  Dirk Eddelbuettel  <edd@debian.org>
+
+	* vignettes/rmd/Rcpp-FAQ.Rmd: New entry on growing vectors
+
 2021-07-08  Dirk Eddelbuettel  <edd@debian.org>
 
         * DESCRIPTION (Version, Date): Roll minor version

vignettes/rmd/Makefile

@@ -22,4 +22,4 @@ Rcpp-jss-2011.pdf:	Rcpp-jss-2011.tex
 			cp -vax $@ ../pdf
 
 clean:
-			@rm -rf *.aux *.log *.out *.tex *.pdf Rcpp-introduction_cache Rcpp-libraries_cache pinp.cls Rcpp-jss-2011.bbl Rcpp-jss-2011.blg auto
+			@rm -rf *.aux *.log *.out *.toc *.tex *.pdf Rcpp-introduction_cache Rcpp-libraries_cache pinp.cls Rcpp-jss-2011.bbl Rcpp-jss-2011.blg auto

vignettes/rmd/Rcpp-FAQ.Rmd

@@ -61,7 +61,7 @@ bibliography: Rcpp
 #watermark: false
 
 # Customize footer, eg by referencing the vignette
-footer_contents: "Rcpp Vignette"
+footer_contents: "Rcpp FAQ Vignette"
 
 # Omit \pnasbreak at end
 skip_final_break: true
@@ -1775,3 +1775,32 @@ redefines `TRUE` leading to bad interactions with the `Rboolean` enum type. A
 very simple solution is to be more careful and conservative with `#include`
 files and a) have `#include <mach/boolean.h>` appear first and b) skip
 the `#include <Rinternals.h>` as it is included by `Rcpp.h` anyway.
+
+## Can we grow Rcpp vectors like STL vectors via 'push*'
+
+No. Use actual STL vectors instead. This has been stated clearly many times going
+back to the [original announcement in Feb 2010](https://lists.r-forge.r-project.org/pipermail/rcpp-devel/2010-February/000410.html),
+StackOverflow answers in [Dec 2011](https://stackoverflow.com/a/8631853/143305)
+and in [Dec 2012](https://stackoverflow.com/a/13783044/143305),
+the rcpp-devel list in [Jun 2013](https://lists.r-forge.r-project.org/pipermail/rcpp-devel/2013-June/006078.html),
+another StackOverflow answer in [Nov 2013](https://stackoverflow.com/a/19829440/143305),
+an early Rcpp Gallery post in [Dec 2013](https://gallery.rcpp.org/articles/plyr-c-to-rcpp/),
+again on StackOverflow [Dec 2014](https://stackoverflow.com/a/27585789/143305), as well as in
+the 'Advanced R' [first](http://adv-r.had.co.nz/Rcpp.html#stl) and
+[second](https://adv-r.hadley.nz/rcpp.html#stl) editions.
+For emphasis, here is a quote from the [rcpp-devel post](https://lists.r-forge.r-project.org/pipermail/rcpp-devel/2013-June/006078.html):
+
+> Those are somehow cosmetic additions. The usual suggestion is not to
+> use push_front and push_back on Rcpp types.
+>
+> We use R's memory, and in R, resizing a vector means moving the data.
+> So if you push_back 3 times, you're moving the data 3 times.
+>
+> Using R own memory is the best ever decision we made in Rcpp. You can
+> always use your own data structures to accumulate data, perhaps using
+> stl types and then convert back to R types, which is something we make
+> easy to do.
+
+Many code examples and packages show exactly that approach (as _e.g._ discussed
+in the [Rcpp Gallery post](https://gallery.rcpp.org/articles/plyr-c-to-rcpp/)).
+Anybody who claims otherwise is (possibly intentionally) misleading.