[Rcpp-commits] r353 - papers/rjournal
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Jan 12 16:25:22 CET 2010
Author: romain
Date: 2010-01-12 16:25:22 +0100 (Tue, 12 Jan 2010)
New Revision: 353
Modified:
papers/rjournal/FrancoisEddelbuettel.bib
papers/rjournal/FrancoisEddelbuettel.tex
papers/rjournal/Makefile
Log:
some revisions and more examples
Modified: papers/rjournal/FrancoisEddelbuettel.bib
===================================================================
--- papers/rjournal/FrancoisEddelbuettel.bib 2010-01-12 09:33:33 UTC (rev 352)
+++ papers/rjournal/FrancoisEddelbuettel.bib 2010-01-12 15:25:22 UTC (rev 353)
@@ -29,6 +29,13 @@
url = {http://CRAN.R-project.org/package=inline},
}
+ at Manual{cran:Rserve,
+ title = {Rserve: Binary R server},
+ author = {Simon Urbanek},
+ note = {R package version 0.6-1},
+ url = {http://www.rforge.net/Rserve/},
+ }
+
@InProceedings{batesdebroy01:cppclasses,
author = {Douglas M. Bates and Saikat DebRoy},
title = {{C++} Classes for {R} Objects},
@@ -38,7 +45,6 @@
address = {TU Vienna, Austria}
}
-
@Unpublished{javagailemanly07:r_cpp,
author = {James J. Java and Daniel P. Gaile and Kenneth E. Manly},
title = {R/Cpp: Interface Classes to Simplify Using R Objects in C++ Extensions},
@@ -47,3 +53,11 @@
year = 2007
}
+ at InProceedings{runnalls09:cxxr,
+ author= {Andrew Runnalls},
+ title = {Aspects of CXXR internals},
+ booktitle = {Directions in Statistical Computing},
+ address = {University of Copenhagen, Denmark},
+ year= 2009
+ }
+
Modified: papers/rjournal/FrancoisEddelbuettel.tex
===================================================================
--- papers/rjournal/FrancoisEddelbuettel.tex 2010-01-12 09:33:33 UTC (rev 352)
+++ papers/rjournal/FrancoisEddelbuettel.tex 2010-01-12 15:25:22 UTC (rev 353)
@@ -66,12 +66,20 @@
unpublished paper, express several ideas that are close to some of our
approaches, though not yet fully fleshed out.
-Rserve was early with C++ use in one of its clients and also wrapped SEXP
-objects.
+Rserve \citep{cran:Rserve} was early with C++ use in one
+of its clients and also wrapped SEXP objects.
+% FIXME: the Rserve client does not know about SEXP, it defines
+% Rexp, something that looks like SEXP, but isn't;
+% R does not have to be on the client side
-CXXR comes from the other side and aims to rebuild R using a C++.
+CXXR \citep{runnalls09:cxxr} comes from the other side
+and aims to rebuild R using a C++. If moving from C to C++ is to be
+compared with improving someone's house, \pkg{Rcpp} is repainting the
+walls where CXXR rebuilds from the foundations.
+% maybe we do a bit more than the walls ?
+% new more comfortable furnitures ?
-rppbind ...
+rcppbind ...
Whit A ...
@@ -311,47 +319,26 @@
Besides classes, the \pkg{Rcpp} package also contains utilities allowing
conversion from R objects to C++ types and vice-versa. Through
polymorphism, the \code{wrap} set of functions can be used to wrap
-some data structure into an \code{RObject} instance. In total, the
-\pkg{Rcpp} defines 23 different \code{wrap} functions, listed below :
+some data structure into an \code{RObject} instance.
-\begin{small}
-\begin{center}
-\begin{tabular}{cc}
-C++ type & \pkg{Rcpp} type \\
-\hline
-\code{SEXP} & $\star$ \\
-\hline
-\code{bool} & \code{LogicalVector} \\
-\code{double} & \code{NumericVector} \\
-\code{int} & \code{IntegerVector} \\
-\code{size\_t} & \code{IntegerVector} \\
-\code{unsigned char} & \code{RawVector} \\
-\code{string} & \code{CharacterVector} \\
-\code{char*} & \code{CharacterVector} \\
-\hline
-\code{vector<int>} & \code{IntegerVector} \\
-\code{vector<double>} & \code{NumericVector} \\
-\code{vector<unsigned char>} & \code{RawVector} \\
-\code{vector<bool>} & \code{LogicalVector} \\
-\code{vector<string>} & \code{CharacterVector} \\
-\hline
-\code{set<int>} & \code{IntegerVector} \\
-\code{set<double>} & \code{NumericVector} \\
-\code{set<unsigned char>} & \code{RawVector} \\
-\code{set<string>} & \code{CharacterVector} \\
-\hline
-\code{initializer\_list<int>} & \code{IntegerVector} \\
-\code{initializer\_list<double>} & \code{NumericVector} \\
-\code{initializer\_list<unsigned char>} & \code{RawVector} \\
-\code{initializer\_list<bool>} & \code{LogicalVector} \\
-\code{initializer\_list<string>} & \code{CharacterVector} \\
-\code{initializer\_list<RObject>} & \code{List} \\
-\hline
-\end{tabular}
-\begin{small}$\star$ : depends on the type of the \code{SEXP}\end{small}
-\end{center}
-\end{small}
+In total, the \pkg{Rcpp} defines 23 different \code{wrap}
+functions, including :
+\begin{itemize}
+\item SEXP
+\item primitive types : \code{bool}, \code{int}, \code{double},
+\code{size\_t}, \code{unsigned char} (byte), \code{std::string} and
+\code{char*}
+\item stl vectors of these types: \code{vecor<int>},
+\code{vector<double>}, \code{vector<bool>}, \code{vector<unsigned char>},
+\code{vector<string>}
+\item stl sets : \code{set<int>}, \code{set<double>}, \code{set<unsigned char>},
+\code{set<string>}
+\item initializer lists (only available in GCC 4.4).
+\end{itemize}
+Each type is wrapped in the most sensible class, e.g. \code{vector<double>}
+is wrapped into an \pkg{NumericVector} object, which in turns encapsulates
+a numeric vector (a \code{SEXP} of type \code{REALSXP}).
Here are a few examples of \code{wrap} calls:
\begin{example}
@@ -379,9 +366,128 @@
\section{external pointers}
-factor this out from romain's blog
+In addition to primitive data types, R can handle arbitrary pointers
+by encapsulating the pointer in a special R object, the external
+pointer. \cite{R:exts} documents the available API R has to offer to
+deal with external pointers.
+\pkg{Rcpp} takes advantage of C++ templates and smart pointers and
+defines the templated class \code{XPtr} that acts as a smart
+pointer to the underlying C++ object.
+Assuming we get from R an external pointer to a \code{std::vector<int>}
+c++ object, we can manipulate it as such using the \code{XPtr} class:
+
+\begin{example}
+// xp is an external pointer
+// to a std::vector<int>
+XPtr< std::vector<int> > p(xp) ;
+p->push\_back(1) ;
+p->push\_back(2) ;
+p->size() ;
+\end{example}
+
+The \code{XPtr} class directly derives from the \code{RObject} class.
+Thanks to its template parameter and overloading of the \code{->}
+and \code{*} operators, objects of the \code{XPtr<Foo>} generated
+class look and feel like raw pointers (\code{Foo*}).
+
+Making an external pointer from a raw pointer is equally easy using
+another constructor.
+
+\begin{example}
+std::vector<int> *pv = new std::vector<int> ;
+XPtr< std::vector<int> > p(pv,true) ;
+\end{example}
+
+The creation of the instance of the \code{XPtr< std::vector<int> >}
+smart extenal pointer to a \code{std::vector<int>} hides the
+R API that is typically used for external pointers, including registration
+of a finalizer to be executed to free the memory of the vector when the
+external pointer goes out of scope.
+
+\section{other examples}
+
+The last example shows how to use \pkg{Rcpp} to emulate the R code below.
+For more examples, the reader is invited to
+refer to the comprehensive documentation included in \pkg{Rcpp}
+as well as the many examples that the package contains as part of
+its unit tests.
+
+\begin{example}
+> rnorm( 10L, sd = 100.0 )
+\end{example}
+
+The code can be expressed in several ways in \pkg{Rcpp}, the first version
+shows the use of the \code{Environment} and \code{Function} classes.
+
+\begin{example}
+Environment stats("package:stats") ;
+Function rnorm = stats.get("rnorm") ;
+return rnorm(10, Named("sd", 100.0) ) ;
+\end{example}
+
+We first pull out the \code{rnorm} function from the environment
+called \samp{package:stats} in the search path, then call the function
+using syntax similar to calling the function in R. The \code{Named}
+class is an utility class that helps emulating the use of
+named arguments.
+
+The second version shows the use of the \code{Language} class, which
+manage calls (LANGSXP).
+
+\begin{example}
+Language call("rnorm", 10, Named("sd", 100 ) ) ;
+call.eval() ;
+\end{example}
+
+%TODO: implement Language::eval( ) !!
+
+In this version, we first create a call to the symbol "rnorm" and
+evaluate the call in the global environment, this is similar to the
+R code :
+
+\begin{example}
+> eval( call( "rnorm", 10L, sd = 100 ) )
+\end{example}
+
+Using the R api, the first example, using the actual
+\code{rnorm} function,
+translates to :
+
+\begin{example}
+SEXP stats = PROTECT(
+\ \ R_FindNamespace( mkString("stats") ) ) ;
+SEXP rnorm = PROTECT(
+\ \ findVarInFrame( stats, install("rnorm") ) ) ;
+SEXP call = PROTECT( LCONS( rnorm,
+\ \ CONS(ScalarInteger(10),
+\ \ \ \ CONS(ScalarReal(100.0), R_NilValue)))) ;
+SET_TAG( CDDR(call), install("sd") ) ;
+SEXP res = PROTECT( eval( call, R_GlobalEnv ) );
+UNPROTECT(4) ;
+return res ;
+\end{example}
+
+and the second example, using the \samp{rnorm} symbol, and therefore
+involving implicit lookup in hte search path, can be written as:
+
+\begin{example}
+SEXP call = PROTECT(
+\ \ LCONS( install("rnorm"),
+\ \ \ \ CONS(ScalarInteger(10),
+\ \ \ \ \ \ CONS(ScalarReal(100.0), R_NilValue)))) ;
+SET_TAG( CDDR(call), install("sd") ) ;
+SEXP res = PROTECT( eval( call, R_GlobalEnv ) );
+UNPROTECT(2) ;
+return res ;
+\end{example}
+
+
+
+\section{Limitations}
+
+
\section{Summary}
Modified: papers/rjournal/Makefile
===================================================================
--- papers/rjournal/Makefile 2010-01-12 09:33:33 UTC (rev 352)
+++ papers/rjournal/Makefile 2010-01-12 15:25:22 UTC (rev 353)
@@ -5,6 +5,8 @@
rm -fr RJwrapper.out
rm -fr RJwrapper.aux
rm -fr RJwrapper.log
+ rm -fr RJwrapper.bbl
+ rm -fr RJwrapper.blg
RJwrapper.pdf: RJwrapper.tex FrancoisEddelbuettel.tex RJournal.sty
pdflatex RJwrapper.tex
More information about the Rcpp-commits
mailing list