add example

Author: MichaelChirico

vignettes/datatable-programming.Rmd

@@ -156,7 +156,21 @@ substitute2(
 
 We can see in the output that both the functions names, as well as the names of the variables passed to those functions, have been replaced. We used `substitute2` for convenience. In this simple case, base R's `substitute` could have been used as well, though it would've required usage of `lapply(env, as.name)`.
 
-Note that `outer = sqrt`, i.e., providing the _symbol_ instead of the function as a _character string_ is supported, and sometimes required (e.g. for namespace-qualified names like `pkg::foo`), but that there are some subtle differences between the two approaches that are beyond the scope of this vignette. We only note here that similar considerations apply for whether to specify `what=` in `do.call()` as a string or a symbol.
+Note that `outer = sqrt`, i.e., providing the _symbol_ instead of the function as a _character string_ is supported, and sometimes required (e.g. for namespace-qualified names like `pkg::foo`), but that there are some subtle differences between the two approaches. To get a hint of this, observe:
+
+```{r hypotenuse_substitute2_symbol}
+substitute2(
+  outer(inner(var1) + inner(var2)),
+  env = list(
+    outer = sqrt,
+    inner = "square",
+    var1 = "a",
+    var2 = "b"
+  )
+)
+```
+
+The implications of this are beyond the scope of this vignette. We only note here that similar considerations apply for whether to specify `what=` in `do.call()` as a string or a symbol.
 
 Now, to use substitution inside `[.data.table`, we don't need to call the `substitute2` function. As it is now being used internally, all we have to do is to provide `env` argument, the same way as we've provided it to the `substitute2` function in the example above. Substitution can be applied to the `i`, `j` and `by` (or `keyby`) arguments of the `[.data.table` method. Note that setting the `verbose` argument to `TRUE` can be used to print expressions after substitution is applied. This is very useful for debugging.