[Rcpp-commits] r1384 - pkg/Rcpp/inst/doc/Rcpp-modules

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

Author: romain
Date: 2010-05-31 20:28:08 +0200 (Mon, 31 May 2010)
New Revision: 1384

Modified:
   pkg/Rcpp/inst/doc/Rcpp-modules/Rcpp-modules.Rnw
Log:
use \pkg{Rcpp} and \proglang{C++}

Modified: pkg/Rcpp/inst/doc/Rcpp-modules/Rcpp-modules.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-modules/Rcpp-modules.Rnw	2010-05-31 18:11:26 UTC (rev 1383)
+++ pkg/Rcpp/inst/doc/Rcpp-modules/Rcpp-modules.Rnw	2010-05-31 18:28:08 UTC (rev 1384)
@@ -5,43 +5,45 @@
 \usepackage{alltt}           
 \usepackage[authoryear,round,longnamesfirst]{natbib}
 
+\usepackage[colorlinks]{hyperref}
 \setmargrb{0.75in}{0.75in}{0.75in}{0.75in}
+\newcommand{\proglang}[1]{\textsf{#1}}
+\newcommand{\pkg}[1]{{\fontseries{b}\selectfont #1}}
 
-\usepackage[colorlinks]{hyperref}
 \author{Dirk Eddelbuettel \and Romain Fran\c{c}ois}
-\title{Exposing C++ functions and classes with Rcpp modules}
+\title{Exposing \proglang[C++} functions and classes with Rcpp modules}
 
 \begin{document}
 \maketitle
 
 \abstract{
   \noindent
-  \textsl{Rcpp modules} have been introduced in version 0.8.1 of \texttt{Rcpp}
-  to allow programmers to simply expose C++ functions and classes to R.  
+  \textsl{Rcpp modules} have been introduced in version 0.8.1 of \pkg{Rcpp}
+  to allow programmers to simply expose \proglang[C++} functions and classes to R.  
   \textsl{Rcpp modules} are inspired from the \texttt{Boost.Python} \citep{Boost:Python}
-  C++ library which provides the same features (and much more) for 
+  \proglang[C++} library which provides the same features (and much more) for 
   Python. This document is a short overview of the capabilities of modules.
 }
 
 \section{Motivation}
 
-Exposing C++ functionality to R is greatly facilitated by the \texttt{Rcpp}
-package and underlying C++ library \citep{CRAN:Rcpp}. \texttt{Rcpp}
-facilitates R and C++ integration by replacing use of the traditionnal R API
-by a consistent set of C++ classes.
+Exposing \proglang[C++} functionality to R is greatly facilitated by the \pkg{Rcpp}
+package and underlying \proglang[C++} library \citep{CRAN:Rcpp}. \pkg{Rcpp}
+facilitates R and \proglang[C++} integration by replacing use of the traditionnal R API
+by a consistent set of \proglang[C++} classes.
 
 However, these facilities are limited to a function by function basis. The 
 programmer has to implement a \texttt{.Call} compatible function
-using classes of the \texttt{Rcpp} API. 
+using classes of the \pkg{Rcpp} API. 
 
 \subsection{Exposing functions}
 
-Exposing existing C++ functions to R through \texttt{Rcpp}
+Exposing existing \proglang[C++} functions to R through \pkg{Rcpp}
 usually involves writing an additional wrapper function that is responsible
 for converting input objects to the appropriate types, calling the function
 and converting the results back to a suitable type that can be returned to 
 R: the traditionnal \texttt{SEXP} from the R API or any type from the 
-\texttt{Rcpp} API that offer implicit conversion to \texttt{SEXP} (many of them do).
+\pkg{Rcpp} API that offer implicit conversion to \texttt{SEXP} (many of them do).
 
 Consider the \texttt{hello} function below: 
 
@@ -53,7 +55,7 @@
 }
 @
 
-One can expose a such a function using \texttt{Rcpp} converters
+One can expose a such a function using \pkg{Rcpp} converters
 
 <<lang=cpp>>=
 RcppExport SEXP hello_wrapper( SEXP who){
@@ -79,7 +81,7 @@
 
 \subsection{Exposing classes}
 
-Exposing C++ classes or structs is even more of a challenge because it
+Exposing \proglang[C++} classes or structs is even more of a challenge because it
 requires writing glue code for each function that is to be exposed. Consider the 
 simple \texttt{World} class below: 
 
@@ -98,7 +100,7 @@
 We might want a way to create objects of this class, and use the member
 functions \texttt{greet} and \texttt{set} to alter the object. External pointers 
 \citep{R:exts} are the perfect vessel for this, and using the 
-\texttt{Rcpp:::XPtr} template from \texttt{Rcpp} we can expose the class
+\texttt{Rcpp:::XPtr} template from \pkg{Rcpp} we can expose the class
 by exposing three functions : 
 
 <<lang=cpp>>=
@@ -141,23 +143,23 @@
 w$greet()
 @
 
-\texttt{Rcpp} considerably simplifies the code that would be involved for using 
+\pkg{Rcpp} considerably simplifies the code that would be involved for using 
 external pointers with the traditional R API. This still involves 
 a lot of pattern code that quickly becomes hard to maintain and error prone. 
 \textsl{Rcpp modules} offer a much nicer way to expose the \texttt{World}
-class in a way that makes both the internal C++ code and the R code easier. 
+class in a way that makes both the internal \proglang[C++} code and the R code easier. 
 
 \section{Rcpp modules}
 
 Rcpp modules are inspired from Python modules that are generated
 by the \texttt{Boost.Python} library. They provide an easy way to expose
-C++ functions and classes to R, grouped together in a single entity. 
+\proglang[C++} functions and classes to R, grouped together in a single entity. 
 
 The module is created in a cpp file using the \texttt{RCPP\_MODULE}
 macro, which then contains declarative code of what the module 
 exposes to R. 
 
-\subsection{Exposing C++ functions}
+\subsection{Exposing \proglang[C++} functions}
 
 Consider the \texttt{hello} function from the previous section. 
 We can expose it to R :
@@ -176,11 +178,11 @@
 @
 
 The code creates a module called an Rcpp module called \texttt{yada}
-that exposes the \texttt{hello} function. \texttt{Rcpp} automatically 
+that exposes the \texttt{hello} function. \pkg{Rcpp} automatically 
 deduces the conversions that are needed for input and output. 
 
 On the R side, the module is simply retrieved by using the \texttt{Module}
-function from \texttt{Rcpp}:
+function from \pkg{Rcpp}:
 
 <<eval=FALSE>>=
 require( Rcpp )
@@ -255,9 +257,9 @@
 can be managed by the \texttt{Rcpp::wrap} template
 \end{itemize}
 
-\subsection{Exposing C++ classes}
+\subsection{Exposing \proglang[C++} classes}
 
-Rcpp modules also provide a mechanism for exposing C++ classes. The mechanism
+Rcpp modules also provide a mechanism for exposing \proglang[C++} classes. The mechanism
 internally uses external pointers, but the user should consider this as
 hidden implementation details as this is properly encapsulated.
 
@@ -291,7 +293,7 @@
 }                     
 @
 
-\texttt{class\_} is templated by the C++ class or struct that is to be exposed
+\texttt{class\_} is templated by the \proglang[C++} class or struct that is to be exposed
 to R. The parameter of the \texttt{class\_<World>} constructor is the name we will
 use on the R side. It usually makes sense to use the same name as the class 
 name, but this is not forced, which might be useful when exposing a class 
@@ -305,9 +307,9 @@
 providing the name that will be used on the R side (e.g. \texttt{greet}) and 
 a pointer to the actual member function (e.g. \texttt{\&World::greet} )
 \item free funtions that take a pointer to the target class as their 
-first parameter such as the C++ function \texttt{clearWorld} in the previous
+first parameter such as the \proglang[C++} function \texttt{clearWorld} in the previous
 example. Again, we provide the R name for the method (\texttt{clear}) and 
-a pointer to the C++ function. 
+a pointer to the \proglang[C++} function. 
 \end{itemize}
 
 The module exposes the default constructor of the \texttt{World} class as well
@@ -350,10 +352,10 @@
 
 \subsubsection{S4 dispatch}
 
-When a C++ class is exposed by the \texttt{class\_} template, 
+When a \proglang[C++} class is exposed by the \texttt{class\_} template, 
 a new S4 class is registered as well. This allows implementation of R-level 
 (S4) dispatch. For example, one might implement the \texttt{show}
-method for C++ \texttt{World} objects: 
+method for \proglang[C++} \texttt{World} objects: 
 
 <<eval=FALSE>>=
 setMethod( "show", "World", function(object){
@@ -364,7 +366,7 @@
 
 \subsubsection{Special methods}
 
-\texttt{Rcpp} considers the methods \texttt{[[} and \texttt{[[<-} special, 
+\pkg{Rcpp} considers the methods \texttt{[[} and \texttt{[[<-} special, 
 and promote them to indexing methods on the R side. 
 
 \subsubsection{Full example}