[Rcpp-commits] r616 - papers/rjournal

[noreply at r-forge.r-project.org]

Author: romain
Date: 2010-02-06 22:38:25 +0100 (Sat, 06 Feb 2010)
New Revision: 616

Modified:
   papers/rjournal/EddelbuettelFrancois.tex
Log:
condense 3 paragraphs into one. Move the wrappable explanation after the code

Modified: papers/rjournal/EddelbuettelFrancois.tex
===================================================================
--- papers/rjournal/EddelbuettelFrancois.tex	2010-02-06 21:36:01 UTC (rev 615)
+++ papers/rjournal/EddelbuettelFrancois.tex	2010-02-06 21:38:25 UTC (rev 616)
@@ -21,7 +21,6 @@
 based on a set of functions and macros operating on \code{SEXP}, the internal
 representation of R objects.
 
-% appendix A of Chambers's software for data analysis ?
 In this article, we discuss the functionality of the \pkg{Rcpp}
 package, which we believe simplifies dramatically the usage of C++ code
 in R. Combining R and C++ is not a new idea, so we start with
@@ -40,6 +39,9 @@
 %        pages so be it. I like the paper as it is. But it may be harder
 %        to argue for a new publication in JSS or elsewhere is the only
 %        new piece is XPtr. That said by then we may have new toys ...
+% [Romain] There are a few more things we could show. That said I'm not 
+%          desperate to dive into another article just now, and we'd probably 
+%          want to be able to quote this one (if accepted, etc ...)
 highlights some of the key design and implementation choices: 
 lightweight encapsulation of R object in C++ classes, automatic
 garbage collection strategy, code inlining, data interchange between 
@@ -49,8 +51,6 @@
 as opposed to the traditional R API. Many more examples are available within
 the package, both as explicit examples and as part of the numerous unit tests.
 
-%\section{Background}
-
 \subsection{Historical Context}
 
 \pkg{Rcpp} first appeared in 2005 as a contribution to the \pkg{RQuantLib}
@@ -229,27 +229,15 @@
 relieves the programmer from writing boiler plate code to manage
 the protection stack with \code{PROTECT} and \code{UNPROTECT} macros.
 
-% [Romain] : maybe we can shorten the next 3 paragraphs
-%            it does not say much more than if we just spell out the 
-%            names of the methods
-% [Dirk]  I was looking at that too this morning. Maybe combine from three
-%         short paragraphs into one?  Do you want to give it a try?
-The \code{RObject} class defines a set of member functions that
-can be used on any R object, regardless of its type. The member
-functions \code{isNULL}, \code{isObject} and \code{isS4} can be 
-used to query properties of the object. 
+The \code{RObject} class defines a set of member functions applicable
+to any R object, regardless of its type. This ranges from 
+querying properties of the object (\texttt{isNULL}, \texttt{isObject}, 
+\texttt{isS4}), management of the attributes 
+(\texttt{attributeNames}, \texttt{hasAttribute}, \texttt{attr}) and 
+handling of slots\footnote{The member functions that deal with slots
+are only applicable on S4 objects. Using these functions on 
+non-S4 objects throws exceptions. } (\texttt{hasSlot}, \texttt{slot}).
 
-Regarding attributes, the member functions 
-\code{attributeNames} can be used to retrieve the names of the attributes, 
-the \code{hasAttribute} can be used to query the existence of an attribute and 
-the \code{attr} can be used to either get the current value of an 
-attribute, or set the value to some other object.
-
-Similarly, the member functions \code{hasSlot} and \code{slot}
-can be used to manage slots of an S4 object. These function throw 
-C++ exceptions when used on objects that are not S4 objects, or when 
-trying to access a slot that does not exist for a class.
-
 \subsection{Derived classes}
 
 Internally, an R object must have one type amongst the set of 
@@ -388,6 +376,8 @@
 % [Romain]: RInside fully specializes wrap for these types: 
 %           vector<vector<double>> and vector<vector<int>>
 % [Dirk:] *Plonk* Yes.
+% [Romain:] Hmmm. not sure about that anymore. Maybe it is a bit confusing. Don't know. Will sleep on it.
+%           and you don't actually quote RInside. 
 \end{itemize}
 An example for the full specialisation of the templated \code{wrap} function
 is provided by \code{vector< vector< double > >} and \code{vector< vector< int
@@ -398,14 +388,9 @@
 using modern techniques of template meta programming and class traits.
 
 % [Romain] : should we put the explanation after the code ?
-The design allows composition, so for example objects of the class
-\code{std::vector< std::map<std::string,int> >} are wrappable. This is 
-because \code{int} is wrappable (as a primitive type), consequently 
-\code{std::map<std::string,int>} is wrappable (as an STL map of 
-wrappable types keyed by strings, and therefore
-\code{std::vector< std::map<std::string,int> >} is wrappable (as a 
-STL container of wrappable objects). The example code below
-illustrates this: 
+% [Romain] : trying this now
+The following code snippet illustrates that the design allows
+composition:
 
 \begin{example}
 std::vector< std::map<std::string,int> > v ;
@@ -423,13 +408,21 @@
 \end{example}
 
 The code creates a list of two named vectors, equal to the list that 
-can be created by the following R code. 
+can be created by the following R code, equivalent to the 
+data structure created by this R code. 
 
 \begin{example}
 list( c( bar = 2L, foo = 1L) , 
       c( bar = 2L, bling = 3L, foo = 1L) )
 \end{example}
 
+The C++ type \code{std::vector< std::map<std::string,int> >} is wrappable because: 
+\texttt{int} is wrappable (as a primitive type), therefore 
+\texttt{std::map<std::string,int>} is wrappable (as a STL map 
+of wrappable types keyed by strings), and finally 
+\texttt{std::vector< std::map<std::string,int> >} is wrappable 
+(as an STL container of wrappable types).
+
 \subsection{R to C++ : as}
 
 The reversed conversion is implemented by variations of the