updated vignettes, updated NEWS and ChangeLog

Author: eddelbuettel

ChangeLog

@@ -1,8 +1,18 @@
+2018-07-26  Dirk Eddelbuettel  <[email protected]>
+
+	* vignettes/Rcpp-FAQ.Rmd: Use collapse: true
+
+2018-07-25  Dirk Eddelbuettel  <[email protected]>
+
+	* vignettes/Rcpp-extending.Rmd: Use collapse: true
+
 2018-07-24  Martin Lysy  <[email protected]>
 
-        * R/loadRcppClass.R: Search in R module for 'Class' instead of 'CppClass'.
+        * R/loadRcppClass.R: Search in R module for 'Class' instead of
+	'CppClass'.
         * R/exposeClass.R: Fixed 'rename' argument to work as expected.
-        * inst/unitTests/runit.exposeClass.R: Added unit tests for the above.
+        * inst/unitTests/runit.exposeClass.R: Added unit tests for the
+	above.
 
 2018-07-23  Dirk Eddelbuettel  <[email protected]>
 

inst/NEWS.Rd

@@ -3,6 +3,25 @@
 \newcommand{\ghpr}{\href{https://github.com/RcppCore/Rcpp/pull/#1}{##1}}
 \newcommand{\ghit}{\href{https://github.com/RcppCore/Rcpp/issues/#1}{##1}}
 
+\section{Changes in Rcpp version 0.12.19 (2018-09-xx)}{
+  \itemize{
+    \item Changes in Rcpp API:
+    \itemize{
+      TBD
+    }
+    \item Changes in Rcpp Modules:
+    \itemize{
+      \item Improved \code{exposeClass} functionality along with added
+      test (Martin Lysy in \ghpr{886} fixing \ghit{879}).
+    }
+    \item Changes in Rcpp Documentation:
+    \itemize{
+      \item Several vignettes now use the \code{collapse} argument to
+      show output in the corresponding code block.
+    }
+  }
+}
+
 \section{Changes in Rcpp version 0.12.18 (2018-07-21)}{
   \itemize{
     \item Changes in Rcpp API:

vignettes/Rcpp-FAQ.Rmd

@@ -67,7 +67,9 @@ footer_contents: "Rcpp Vignette"
 skip_final_break: true
 
 # Produce a pinp document
-output: pinp::pinp
+output:
+    pinp::pinp:
+        collapse: true
 
 header-includes: >
   \newcommand{\proglang}[1]{\textsf{#1}}
@@ -85,6 +87,13 @@ vignette: >
 
 \tableofcontents
 
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(cache=TRUE)
+library(Rcpp)
+library(inline)
+options("width"=50, digits=5)
+```
+
 # Getting started
 
 ## How do I get started
@@ -246,7 +255,7 @@ The \pkg{inline} package \citep{CRAN:inline} provides the functions
 function that uses `accumulate` from the (\proglang{C++}) Standard
 Template Library to sum the elements of a numeric vector.
 
-```{r, eval = FALSE}
+```{r}
 fx <- cxxfunction(signature(x = "numeric"),
     'NumericVector xx(x);
      return wrap(
@@ -259,18 +268,6 @@ res <- fx(seq(1, 10, by=0.5))
 res
 ```
 
-```{r, eval = FALSE, echo=FALSE}
-stopifnot(identical(res, sum(seq(1, 10, by=0.5))))
-```
-
-<!--
-\pkg{Rcpp} uses \pkg{inline} to power its entire unit test suite. Consult the
-`unitTests` directory of \pkg{Rcpp} for several hundred further examples.
-```{r, eval = FALSE}
-list.files( system.file( "unitTests", package = "Rcpp" ), pattern = "^runit[.]" )
-```
--->
-
 One might want to use code that lives in a \proglang{C++} file instead of writing
 the code in a character string in R. This is easily achieved by using
 \rdoc{base}{readLines}:
@@ -289,16 +286,17 @@ useful as it shows how \pkg{inline} runs the show.
 
 Rcpp Attributes \citep{CRAN:Rcpp:Attributes}, and also discussed in
 \faq{prototype-using-attributes} below, permits an even easier
-route to integrating R and C++.  It provides three key functions. First, \rdoc{Rcpp}{evalCpp}
-provide a means to evaluate simple C++ expression which is often useful for
-small tests, or to simply check if the toolchain is set up
-correctly. Second, \rdoc{Rcpp}{cppFunction} can be used to create C++ functions
-for R use on the fly.  Third, `Rcpp::sourceCpp` can integrate entire files in
-order to define multiple functions.
+route to integrating R and C++.  It provides three key functions.
+First, \rdoc{Rcpp}{evalCpp} provide a means to evaluate simple C++
+expression which is often useful for small tests, or to simply check
+if the toolchain is set up correctly. Second, \rdoc{Rcpp}{cppFunction}
+can be used to create C++ functions for R use on the fly.  Third,
+`Rcpp::sourceCpp` can integrate entire files in order to define
+multiple functions.
 
 The example above can now be rewritten as:
 
-```{r, eval = FALSE}
+```{r}
 cppFunction('double accu(NumericVector x) {
    return(
       std::accumulate(x.begin(), x.end(), 0.0)
@@ -647,7 +645,7 @@ what we show below.
 Most certainly, consider this simple example of a templated class
 which squares its argument:
 
-```{r, eval = FALSE}
+```{r}
 inc <- 'template <typename T>
         class square :
           public std::unary_function<T,T> {
@@ -821,7 +819,7 @@ two calls result in the same random draws. If we wanted to control the draws,
 we could explicitly set the seed after the `RNGScope` object has been
 instantiated.
 
-```{r, eval = FALSE}
+```{r}
 fx <- cxxfunction(signature(),
                   'RNGScope();
                    return rnorm(5, 0, 100);',
@@ -837,7 +835,7 @@ random variable distributed as $N(m,s)$.
 
 Using Rcpp Attributes, this can be as simple as
 
-```{r, eval = FALSE}
+```{r}
 cppFunction('Rcpp::NumericVector ff(int n) {
               return rnorm(n, 0, 100);  }')
 set.seed(42)
@@ -858,7 +856,7 @@ as well as R, and that identical random number draws are obtained.
 
 \noindent Yes, see the following example:
 
-```{r, eval = FALSE}
+```{r}
 src <- 'Rcpp::NumericVector v(4);
         v[0] = R_NegInf; // -Inf
         v[1] = NA_REAL;  // NA
@@ -892,7 +890,7 @@ Rcpp::NumericVector fun(void) {
 \noindent Yes, via the \pkg{RcppArmadillo} package which builds upon \pkg{Rcpp} and the
 wonderful Armadillo library described above in \faq{matrix-algebra}:
 
-```{r, eval = FALSE}
+```{r}
 txt <- 'arma::mat Am = Rcpp::as< arma::mat >(A);
         arma::mat Bm = Rcpp::as< arma::mat >(B);
         return Rcpp::wrap( Am * Bm );'
@@ -903,16 +901,9 @@ mmult <- cxxfunction(signature(A="numeric",
 A <- matrix(1:9, 3, 3)
 B <- matrix(9:1, 3, 3)
 C <- mmult(A, B)
+C
 ```
 
-<!--
-```{r eval=FALSE}
-A <- matrix(1:9, 3, 3)
-B <- matrix(9:1, 3, 3)
-A %*% B
-```
--->
-
 Armadillo supports a full range of common linear algebra operations.
 
 The \pkg{RcppEigen} package provides an alternative using the
@@ -1334,7 +1325,7 @@ As a result, the \pkg{Rcpp} object is ``linked'' to the original \proglang{R} ob
 Thus, if an operation is performed on the \pkg{Rcpp} object, such as adding 1
 to each element, the operation also updates the \proglang{R} object causing the change to be propagated to \proglang{R}'s interactive environment.
 
-```cpp
+```{Rcpp}
 #include<Rcpp.h>
 
 // [[Rcpp::export]]
@@ -1348,9 +1339,9 @@ void explicit_ref(Rcpp::NumericVector& X) {
 }
 ```
 
-R use:
+R use
 
-```{r, eval = FALSE}
+```{r}
 a <- 1.5:4.5
 b <- 1.5:4.5
 implicit_ref(a)
@@ -1374,7 +1365,7 @@ and, thus, there would _not_ be a link between the \pkg{Rcpp} object
 and \proglang{R} object. So, any changes in \proglang{C++} would not be propagated to
 \proglang{R} unless otherwise specified.
 
-```cpp
+```{Rcpp}
 #include<Rcpp.h>
 
 // [[Rcpp::export]]
@@ -1390,14 +1381,14 @@ void num_vec_type(Rcpp::NumericVector X) {
 
 R use:
 
-```{r, eval=FALSE}
+```{r}
 a <- 1:5
 b <- 1:5
 class(a)
 int_vec_type(a)
-a
+a # variable a changed as a side effect
 num_vec_type(b)
-b
+b # b unchanged as copy was made for numeric
 ```
 
 With this being said, there is one last area of contention with the proxy model:
@@ -1410,36 +1401,43 @@ would be allowed to be modified by the compiler and, thus, modifying the initial
 `SEXP` object. Therefore, the initially secure \proglang{R} object would be altered.
 To illustrate this phenomenon, consider the following scenario:
 
-```cpp
+```{Rcpp}
 #include <Rcpp.h>
 
 // [[Rcpp::export]]
-Rcpp::NumericVector const_override_ex(
-        const Rcpp::NumericVector& X) {
+Rcpp::IntegerVector const_override_ex(
+        const Rcpp::IntegerVector& X) {
 
-  Rcpp::NumericVector Y(X); // Create object
+  Rcpp::IntegerVector Y(X); // Create object
                             // from SEXP
 
   Y = Y * 2;                // Modify new object
 
-  return X;                 // Return old object
+  return Y;                 // Return new object
 }
 ```
 
 R use:
 
-```{r, eval=FALSE}
-x <- 1:10
+```{r}
+x <- 1:10    # an integer sequence
+# returning an altered value
 const_override_ex(x)
+# but the original value is altered too!
 x
 ```
 
+So we see that with `SEXP` objects, the `const` declaration can be
+circumvented as it is really a pointer to the underlying R object.
+
+
 ## Issues with implicit conversion from an \pkg{Rcpp} object to a scalar or other \pkg{Rcpp} object
 
-Not all \pkg{Rcpp} expressions are directly compatible with `operator=`.
-Compability issues stem from many \pkg{Rcpp} objects and functions returning an
-intermediary result which requires an explicit conversion.  In such cases, the
-user may need to assist the compiler with the conversion.
+Not all \pkg{Rcpp} expressions are directly compatible with
+`operator=`.  Compability issues stem from many \pkg{Rcpp} objects and
+functions returning an intermediary result which requires an explicit
+conversion.  In such cases, the user may need to assist the compiler
+with the conversion.
 
 There are two ways to assist with the conversion. The first is to construct
 storage variable for a result, calculate the result, and then store a value
@@ -1495,7 +1493,7 @@ is cast into the appropriate \pkg{Rcpp} object type. Therefore, if a
 via `operator=`, then the resulting `Vector` would have a length of
 1. See the following code snippet for the aforementioned behavior.
 
-```cpp
+```{Rcpp}
 #include<Rcpp.h>
 
 // [[Rcpp::export]]
@@ -1515,7 +1513,7 @@ void vec_scalar_assign(int n, double fill_val) {
 
 R use:
 
-```{r, eval=FALSE}
+```{r}
 vec_scalar_assign(5L, 3.14)
 ```
 
@@ -1526,7 +1524,7 @@ results while attempting to use the assignment operator with a scalar. In
 particular, the scalar will be coerced into a square `Matrix` and then
 assigned. For an example of this behavior, consider the following code:
 
-```cpp
+```{Rcpp}
 #include<Rcpp.h>
 
 // [[Rcpp::export]]
@@ -1546,7 +1544,7 @@ void mat_scalar_assign(int n, double fill_val) {
 
 R use:
 
-```{r, eval=FALSE}
+```{r}
 mat_scalar_assign(2L, 3.0)
 ```
 
@@ -1574,7 +1572,7 @@ by \pkg{Rcpp} attributes. This is engaged by adding
 For diagnostic and illustrativative purposes, consider the following code
 which checks to see if `R_xlen_t` is available on your platform:
 
-```cpp
+```{Rcpp}
 #include <Rcpp.h>
 // Force compilation mode to C++11
 // [[Rcpp::plugins(cpp11)]]
@@ -1591,7 +1589,7 @@ bool test_long_vector_support() {
 
 R use:
 
-```{r, eval = FALSE}
+```{r}
 test_long_vector_support()
 ```
 
@@ -1627,7 +1625,7 @@ type. Though, sorting is slightly problematic due to locale as explained in the
 next entry. In the interim, the following code example illustrates the preferred
 approach alongside the problematic STL approach:
 
-```cpp
+```{Rcpp}
 #include <Rcpp.h>
 
 // [[Rcpp::export]]
@@ -1653,7 +1651,7 @@ Rcpp::CharacterVector stl_sort(
 
 R use:
 
-```{r, eval=FALSE}
+```{r}
 set.seed(123)
 (X <- sample(c(LETTERS[1:5], letters[1:6]), 11))
 preferred_sort(X)
@@ -1680,7 +1678,7 @@ capitalized words are sorted together followed by the sorting of lowercase
 words instead of a mixture of capitalized and lowercase words. The issue is
 illustrated by the following code example:
 
-```cpp
+```{Rcpp}
 #include <Rcpp.h>
 
 // [[Rcpp::export]]
@@ -1693,7 +1691,7 @@ Rcpp::CharacterVector rcpp_sort(
 
 R use:
 
-```{r, eval=FALSE}
+```{r}
 x <- c("B", "b", "c", "A", "a")
 sort(x)
 rcpp_sort(x)