Merge branch 'issue7369' of https://github.com/Rdatatable/data.table into issue7369

Author: venom1204

vignettes/datatable-faq.Rmd

@@ -56,7 +56,7 @@ For consistency so that when you use data.table in functions that accept varying
 
 You may have heard that it is generally bad practice to refer to columns by number rather than name, though. If your colleague comes along and reads your code later they may have to hunt around to find out which column is number 5. If you or they change the column ordering higher up in your R program, you may produce wrong results with no warning or error if you forget to change all the places in your code which refer to column number 5. That is your fault not R's or data.table's. It's really really bad. Please don't do it. It's the same mantra as professional SQL developers have: never use `select *`, always explicitly select by column name to at least try to be robust to future changes.
 
-Say column 5 is named `"region"` and you really must extract that column as a vector not a data.table. It is more robust to use the column name and write `DT$region` or `DT[["region"]]`; i.e., the same as base R. Using base R's `$` and `[[` on data.table is encouraged. Not when combined with `<-` to assign (use `:=` instead for that) but just to select a single column by name they are encouraged.A key difference, however, is that DT$col and DT[['col']] may return a reference, while DT[, col] always returns a copy. This can have important consequences and is explained in the vignette("datatable-reference-semantics", package="data.table").
+Say column 5 is named `"region"` and you really must extract that column as a vector not a data.table. It is more robust to use the column name and write `DT$region` or `DT[["region"]]`; i.e., the same as base R. Using base R's `$` and `[[` on data.table is encouraged. Not when combined with `<-` to assign (use `:=` instead for that) but just to select a single column by name they are encouraged. A key difference, however, is that DT$col and DT[['col']] may return a reference, while DT[, col] always returns a copy. This can have important consequences and is explained in the `vignette("datatable-reference-semantics", package="data.table")`.
 
 There are some circumstances where referring to a column by number seems like the only way, such as a sequence of columns. In these situations just like data.frame, you can write `DT[, 5:10]` and `DT[,c(1,4,10)]`. However, again, it is more robust (to future changes in your data's number of and ordering of columns) to use a named range such as `DT[,columnRed:columnViolet]` or name each one `DT[,c("columnRed","columnOrange","columnYellow")]`. It is harder work up front, but you will probably thank yourself and your colleagues might thank you in the future. At least you can say you tried your best to write robust code if something does go wrong.
 

vignettes/datatable-reference-semantics.Rmd

@@ -367,31 +367,27 @@ However we could improve this functionality further by *shallow* copying instead
 
 When you extract a single column as a vector, there is a subtle but important difference between standard R methods ($ and [[...]]) and data.table's j expression. DT$col and DT[['col']] may return a reference to the internal column, while DT[, col] always returns a copy.
 
-This means a variable created with `$` can change if the `data.table` is modified later, which can be unexpected. A single example demonstrates this behavior and how `copy()` provides a solution:
-
+A short example:
 ```{r}
 DT = data.table(a = 1:3)
 
-# Create three variables using the different methods
-x_ref = DT$a        # 1. By reference with $
-y_cpy = DT[, a]     # 2. By copy with []
-z_cpy = copy(DT$a)  # 3. Forced copy with copy()
+# three ways to get the column
+x_ref = DT$a        # may be a reference
+y_cpy = DT[, a]     # always a copy
+z_cpy = copy(DT$a)  # forced copy
 
-# Now, modify the original data.table by reference
+# modify DT by reference
 DT[, a := a + 10L]
 
-# Check the variables:
-x_ref 
-#> [1] 11 12 13
-y_cpy
-#> [1] 1 2 3
-z_cpy 
-#> [1] 1 2 3
+# observe results
+x_ref   # may show 11 12 13
+y_cpy   # 1 2 3
+z_cpy   # 1 2 3
 ```
 
 To select a single column as a vector, remember:
 - `DT[, mycol]` is safer as it always returns a new, independent copy.
-- `DT$mycol` and `DT[['mycol']]` are fast but may return a reference.
+- `DT$mycol` is fast but may return a reference. Use `copy(DT$mycol)` to guarantee independence.
 
 ## Summary