[Rcpp-commits] r1371 - pkg/Rcpp/inst/doc
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat May 29 22:33:02 CEST 2010
Author: edd
Date: 2010-05-29 22:33:02 +0200 (Sat, 29 May 2010)
New Revision: 1371
Modified:
pkg/Rcpp/inst/doc/Rcpp-modules.Rnw
Log:
use \pkg{Rcpp} and \proglang{C++}
Modified: pkg/Rcpp/inst/doc/Rcpp-modules.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-modules.Rnw 2010-05-29 19:46:15 UTC (rev 1370)
+++ pkg/Rcpp/inst/doc/Rcpp-modules.Rnw 2010-05-29 20:33:02 UTC (rev 1371)
@@ -55,11 +55,13 @@
\newcommand{\hlsymbol}[1]{\textcolor[rgb]{0,0,0}{#1}}%
\newcommand{\hlprompt}[1]{\textcolor[rgb]{0,0,0}{#1}}%
+\usepackage[colorlinks]{hyperref}
+\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 \pkg{Rcpp} modules}
\begin{document}
@@ -67,38 +69,38 @@
\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:
\InputIfFileExists{snippets/hello}{}{}
-One can expose a such a function using \texttt{Rcpp} converters
+One can expose a such a function using \pkg{Rcpp} converters
\InputIfFileExists{snippets/helloexpose}{}{}
@@ -112,7 +114,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:
@@ -121,7 +123,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 :
\InputIfFileExists{snippets/WorldRcpp}{}{}
@@ -130,35 +132,35 @@
\InputIfFileExists{snippets/WorldRcppR}{}{}
-\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}
+\section{\pkg{Rcpp} modules}
-Rcpp modules are inspired from Python modules that are generated
+\textsl{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 :
\InputIfFileExists{snippets/helloModule}{}{}
-The code creates a module called an Rcpp module called \texttt{yada}
-that exposes the \texttt{hello} function. \texttt{Rcpp} automatically
+The code creates a module called an \pkg{Rcpp} module called \texttt{yada}
+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}:
\InputIfFileExists{snippets/helloModuleR}{}{}
@@ -184,9 +186,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
+\pkg{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.
@@ -195,7 +197,7 @@
\InputIfFileExists{snippets/WorldModule}{}{}
-\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
@@ -209,13 +211,13 @@
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
-to support creation of \texttt{World} objects from R. The Rcpp module assumes
+to support creation of \texttt{World} objects from R. The \pkg{Rcpp} module assumes
responsabilities for type conversion for input and output types.
\InputIfFileExists{snippets/WorldModuleR}{}{}
@@ -233,21 +235,21 @@
\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:
\InputIfFileExists{snippets/S4dispatch}{}{}
\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}
-The following example illustrates how to use Rcpp modules to expose
+The following example illustrates how to use \pkg{Rcpp} modules to expose
the class \texttt{std::vector<double>} from the STL.
\InputIfFileExists{snippets/modulestdvec}{}{}
More information about the Rcpp-commits
mailing list