Clarify column over allocation and modify by reference

[robitalec]

Related to kaijagahm/vultureUtils#44

This is documented in the FAQ here: https://docs.ropensci.org/spatsoc/articles/faq.html#package-design

But as mentioned in the thread above, not in the Value section of help pages beyond eg. "group_pts returns the input DT appended with a group column."

• Add link to FAQ package design in help pages
• Clarify which functions mod by ref / not in FAQ
• Expand FAQ package design with truelength details, over allocation details
• Fix check for setalloccol where truelength <= ncols
• Highlight over allocated columns lost through dplyr related to dplyr_col_select() reconstructs bare data.table objects tidyverse/dplyr#6171 and dplyr:::dplyr_reconstruct
• Clarify when setalloccol and when setDT
• Add examples from comment on linked issue to FAQ

library(data.table)
library(dplyr, warn.conflicts = FALSE)

d1 <- data.table(x = 1)
attr(d1, "foo") <- "bar"
truelength(d1)
#> [1] 1025
d2 <- dplyr:::dplyr_col_select(d1, "x")
attr(d2, "foo")
#> [1] "bar"
truelength(d2)
#> [1] 0

^{Created on 2023-09-17 with reprex v2.0.2}

References:

• https://github.com/tidyverse/dplyr/blob/main/R/generics.R#L192-L223
• https://rdatatable.gitlab.io/data.table/articles/datatable-reference-semantics.html#reference-semantics
• https://github.com/Rdatatable/data.table/blob/master/R/data.table.R#L2856-L2873
• https://rdatatable.gitlab.io/data.table/articles/datatable-faq.html#reading-data-table-from-rds-or-rdata-file
• https://github.com/robitalec/irg/blob/master/R/internal.R#L12-L19
• https://rdatatable.gitlab.io/data.table/reference/truelength.html
• options(datatable.verbose=TRUE)