Add small comment in Modules vignette following #1322

Author: eddelbuettel

ChangeLog

@@ -1,3 +1,8 @@
+2024-07-30  Dirk Eddelbuettel  <[email protected]>
+
+	* vignettes/rmd/Rcpp-modules.Rmd (are): Add short two-sentence
+	illustration following GitHub issue #1322
+
 2024-07-24  Dirk Eddelbuettel  <[email protected]>
 
 	* DESCRIPTION (Version, Date): Roll micro version

vignettes/rmd/Rcpp-modules.Rmd

@@ -1,6 +1,6 @@
 ---
-title: | 
-       | Exposing \proglang{C++} functions and classes 
+title: |
+       | Exposing \proglang{C++} functions and classes
        | with \pkg{Rcpp} modules
 
 # Use letters for affiliations
@@ -180,7 +180,7 @@ Consider the simple `Uniform` class below:
 ```cpp
 class Uniform {
 public:
-    Uniform(double min_, double max_) : 
+    Uniform(double min_, double max_) :
        min(min_), max(max_) {}
 
     NumericVector draw(int n) {
@@ -203,15 +203,15 @@ with these two functions:
 using namespace Rcpp;
 
 /// create external pointer to a Uniform object
-RcppExport SEXP Uniform__new(SEXP min_, 
+RcppExport SEXP Uniform__new(SEXP min_,
                              SEXP max_) {
     // convert inputs to appropriate C++ types
-    double min = as<double>(min_), 
+    double min = as<double>(min_),
            max = as<double>(max_);
 
-    // create pointer to an Uniform object and 
+    // create pointer to an Uniform object and
     // wrap it as an external pointer
-    Rcpp::XPtr<Uniform> 
+    Rcpp::XPtr<Uniform>
     ptr( new Uniform( min, max ), true );
 
     // return the external pointer to the R side
@@ -220,7 +220,7 @@ RcppExport SEXP Uniform__new(SEXP min_,
 
 /// invoke the draw method
 RcppExport SEXP Uniform__draw(SEXP xp, SEXP n_) {
-    // grab the object as a XPtr (smart pointer) 
+    // grab the object as a XPtr (smart pointer)
     // to Uniform
     Rcpp::XPtr<Uniform> ptr(xp);
 
@@ -252,7 +252,7 @@ DE 21 Sep 2013: there must a bug somewhere in the vignette processing
 ```{r, eval=FALSE}
 f1 <- cxxfunction( , "", includes = unifModCode,
                   plugin = "Rcpp" )
-getDynLib(f1)  ## will display info about 'f1' 
+getDynLib(f1)  ## will display info about 'f1'
 ```
 
 The following listing shows some \textsl{manual} wrapping to access the code,
@@ -276,7 +276,7 @@ setMethod("$", "Uniform", function(x, name) {
 # syntactic sugar to allow new( "Uniform", ... )
 setMethod("initialize", "Uniform",
           function(.Object, ...) {
-    .Object@pointer <- 
+    .Object@pointer <-
         .Call(Uniform_method("new"), ...)
     .Object
 } )
@@ -295,7 +295,7 @@ class in a way that makes both the internal
 
 
 
-# Rcpp modules 
+# Rcpp modules
 
 The design of Rcpp modules has been influenced by \proglang{Python} modules which are generated by the
 `Boost.Python` library \citep{Abrahams+Grosse-Kunstleve:2003:Boost.Python}.
@@ -447,7 +447,7 @@ double norm(double x, double y) {
 }
 
 RCPP_MODULE(mod) {
-    function("norm", &norm, 
+    function("norm", &norm,
              "Provides a simple vector norm");
 }
 ```
@@ -475,7 +475,7 @@ double norm(double x, double y) {
 RCPP_MODULE(mod_formals) {
     function("norm",
              &norm,
-             List::create(_["x"] = 0.0, 
+             List::create(_["x"] = 0.0,
                           _["y"] = 0.0),
              "Provides a simple vector norm");
 }
@@ -515,7 +515,7 @@ args(norm)
 ```
 
 The ellipsis (`...`) can be used to denote that additional arguments
-are optional; it does not take a default value. 
+are optional; it does not take a default value.
 
 ```{Rcpp mod_formals3, eval=FALSE}
 using namespace Rcpp;
@@ -539,6 +539,11 @@ norm <- mod$norm
 args(norm)
 ```
 
+As of mid-2024, more recent versions of R no longer tolerate 'empty' strings
+as placeholders for missing arguments. It is preferable to simply not list
+any arguments for functions that take no arguments. Issue #1322 has an example.
+
+
 ## Exposing \proglang{C++} classes using Rcpp modules
 
 Rcpp modules also provide a mechanism for exposing \proglang{C++} classes, based
@@ -553,7 +558,7 @@ class may be exposed to \proglang{R} as follows:
 using namespace Rcpp;
 class Uniform {
 public:
-    Uniform(double min_, double max_) : 
+    Uniform(double min_, double max_) :
        min(min_), max(max_) {}
 
     NumericVector draw(int n) const {
@@ -680,7 +685,7 @@ The `.field_readonly` exposes a public field with read-only access from \proglan
 It also accepts the description of the field.
 
 ```cpp
-  .field_readonly("y", &Foo::y, 
+  .field_readonly("y", &Foo::y,
                   "documentation for y")
 ```
 
@@ -691,11 +696,11 @@ allowed:
 
 ```cpp
   // with getter and setter
-  .property("z", &Foo::get_z, 
+  .property("z", &Foo::get_z,
             &Foo::set_z, "Documentation for z")
 
   // with only getter
-  .property("z", 
+  .property("z",
             &Foo::get_z, "Documentation for z")
 ```
 
@@ -740,7 +745,7 @@ public:
     }
 
     IntegerVector stats() const {
-        return 
+        return
         IntegerVector::create(_["read"] = nread,
                               _["write"] = nwrite);
     }
@@ -822,7 +827,7 @@ to restrict the candidate methods.
 
 ### Special methods
 
-\pkg{Rcpp} considers the methods `[[` and `[[<-` special, 
+\pkg{Rcpp} considers the methods `[[` and `[[<-` special,
 and promotes them to indexing methods on the \proglang{R} side.
 
 ### Object finalizers
@@ -930,14 +935,14 @@ RCPP_MODULE(yada){
     using namespace Rcpp;
 
     class_<World>("World")
-    
+
     // expose the default constructor
     .constructor()
 
     .method("greet", &World::greet)
     .method("set", &World::set)
     ;
-    
+
 }
 ```
 
@@ -1015,24 +1020,24 @@ bar$handleFoo(foo)
 The following example illustrates how to use Rcpp modules to expose
 the class `std::vector<double>` from the STL.
 
-```{Rcpp mod_vec, eval=FALSE} 
-typedef std::vector<double> vec; 	
-void vec_assign(vec* obj, 
+```{Rcpp mod_vec, eval=FALSE}
+typedef std::vector<double> vec;
+void vec_assign(vec* obj,
                 Rcpp::NumericVector data) {
     obj->assign(data.begin(), data.end());
 }
-void vec_insert(vec* obj, int position, 
+void vec_insert(vec* obj, int position,
                 Rcpp::NumericVector data) {
     vec::iterator it = obj->begin() + position;
     obj->insert(it, data.begin(), data.end());
 }
-Rcpp::NumericVector vec_asR( vec* obj ) { 
-   return Rcpp::wrap( *obj ); 
+Rcpp::NumericVector vec_asR( vec* obj ) {
+   return Rcpp::wrap( *obj );
 }
-void vec_set(vec* obj, int i, double value) { 
-   obj->at( i ) = value; 
+void vec_set(vec* obj, int i, double value) {
+   obj->at( i ) = value;
 }
-// Fix for C++11, where we cannot directly expose 
+// Fix for C++11, where we cannot directly expose
 // member functions vec::resize and vec::push_back
 void vec_resize (vec* obj, int n) {
     obj->resize(n);
@@ -1044,7 +1049,7 @@ void vec_push_back (vec* obj, double value) {
 RCPP_MODULE(mod_vec) {
     using namespace Rcpp;
 
-    // we expose class std::vector<double> 
+    // we expose class std::vector<double>
     // as "vec" on the R side
     class_<vec>("vec")
 
@@ -1066,8 +1071,8 @@ RCPP_MODULE(mod_vec) {
     .const_method("front", &vec::front)
     .const_method("at", &vec::at )
 
-    // exposing free functions taking a 
-    // std::vector<double>* as their first 
+    // exposing free functions taking a
+    // std::vector<double>* as their first
     // argument
     .method("assign", &vec_assign)
     .method("insert", &vec_insert)
@@ -1233,7 +1238,7 @@ objects are exposed.
 
 ### Deprecated legacy method using loadRcppModules
 
-Prior to release 0.9.11, where `loadModule` was introduced, 
+Prior to release 0.9.11, where `loadModule` was introduced,
 loading all functions and classes from a module
 into a package namespace was achieved using the `loadRcppModules` function
 within the `.onLoad` body.
@@ -1246,7 +1251,7 @@ within the `.onLoad` body.
 
 This will look in the package's `DESCRIPTION` file for the `RcppModules`
 field, load each declared module and populate their contents into the
-package's namespace. For example, a package defining modules 
+package's namespace. For example, a package defining modules
 `yada`, `stdVector`, `NumEx` would have this declaration:
 
 ```
@@ -1346,5 +1351,3 @@ This note introduced \textsl{Rcpp modules} and illustrated how to expose
 \proglang{C++} function and classes more easily to \proglang{R}.
 We hope that \proglang{R} and \proglang{C++} programmers
 find \textsl{Rcpp modules} useful.
-
-