[Rcpp-commits] r1428 - pkg/Rcpp/inst/doc/Rcpp-modules
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Jun 5 01:12:56 CEST 2010
Author: edd
Date: 2010-06-05 01:12:56 +0200 (Sat, 05 Jun 2010)
New Revision: 1428
Modified:
pkg/Rcpp/inst/doc/Rcpp-modules/Rcpp-modules.Rnw
Log:
one set of edits
Modified: pkg/Rcpp/inst/doc/Rcpp-modules/Rcpp-modules.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-modules/Rcpp-modules.Rnw 2010-06-04 18:33:49 UTC (rev 1427)
+++ pkg/Rcpp/inst/doc/Rcpp-modules/Rcpp-modules.Rnw 2010-06-04 23:12:56 UTC (rev 1428)
@@ -19,7 +19,7 @@
\newcommand{\pkg}[1]{{\fontseries{b}\selectfont #1}}
\author{Dirk Eddelbuettel \and Romain Fran\c{c}ois}
-\title{Exposing \proglang{C++} functions and classes with Rcpp modules}
+\title{Exposing \proglang{C++} functions and classes with \pkg{Rcpp} modules}
<<echo=FALSE>>=
link <- function( f, package, text = f, root = "http://finzi.psych.upenn.edu/R/library/" ){
@@ -47,19 +47,23 @@
\abstract{
\noindent
- This note discusses \textsl{Rcpp modules} which have been introduced in version 0.8.1 of \pkg{Rcpp}.
- \textsl{Rcpp modules} allow programmers to more easily expose \proglang{C++} functions and classes to \proglang{R}.
- \textsl{Rcpp modules} are inspired from the \texttt{Boost.Python} \citep{Boost:Python}
- \proglang{C++} library which provides the same features (and much more) for
- Python. This document is a short overview of the capabilities of modules.
+ This note discusses \textsl{Rcpp modules} which have been introduced in
+ version 0.8.1 of \pkg{Rcpp}. \textsl{Rcpp modules} allow programmers to
+ expose \proglang{C++} functions and classes to \proglang{R} with relative
+ ease. \textsl{Rcpp modules} are inspired from the \texttt{Boost.Python}
+ \proglang{C++} library \citep{Boost:Python} which provides the same
+ features (and much more) for Python. This document is a short overview of
+ the capabilities of modules.
}
\section{Motivation}
-Exposing \proglang{C++} functionality to \proglang{R} is greatly facilitated by the \pkg{Rcpp}
-package and underlying \proglang{C++} library \citep{CRAN:Rcpp}. \pkg{Rcpp}
-facilitates \proglang{R} and \proglang{C++} integration by replacing use of the traditionnal \proglang{R} API
-by a consistent set of \proglang{C++} classes.
+Exposing \proglang{C++} functionality to \proglang{R} is greatly facilitated
+by the \pkg{Rcpp} package and underlying \proglang{C++} library
+\citep{CRAN:Rcpp}. \pkg{Rcpp} smoothese many of the rough edges in
+\proglang{R} and \proglang{C++} integration by replacing the traditionnal
+\proglang{R} API \citep{R:exts} with a consistent set of \proglang{C++}
+classes.
However, these facilities are limited to a function by function basis. The
programmer has to implement a \Sexpr{link(".Call")} compatible function
@@ -68,11 +72,15 @@
\subsection{Exposing functions}
Exposing existing \proglang{C++} functions to \proglang{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. This return type may be the traditionnal \texttt{SEXP} from the \proglang{R} API, or any type from the
-\pkg{Rcpp} API that offers implicit conversion to \texttt{SEXP} (many of them do).
+usually involves several steps. One often writes either an additional wrapper
+function that is responsible for converting input objects to the appropriate
+types, calling the actual worker function and converting the results back to
+a suitable type that can be returned to R. Alternatively, one can alter the
+worker function by changes its signature and return value the interface
+prescribed by the \texttt{.Call()} function of the \proglang{R} API. The
+return type has to the traditionnal \texttt{SEXP} from the \proglang{R}
+API. But with \pkg{Rcpp} we can also use one of the many types from the
+\pkg{Rcpp} API that offers implicit conversion to \texttt{SEXP}.
Consider the \texttt{hello} function below:
@@ -94,8 +102,13 @@
}
@
-Or more traditionally using the \proglang{R} API :
+Here we use the (templated) \pkg{Rcpp} converter \texttt{as()} which can
+transform from a \texttt{SEXP} to a number of different \proglang{C++} and
+\pkg{Rcpp} types. The \pkg{Rcpp} function \texttt{wrap()} offers the opposite
+functionality and converts many known types to a \texttt{SEXP}.
+For comparison, the traditionally approach using the \proglang{R} API looks similar
+
<<lang=cpp>>=
extern "C" SEXP hello_wrapper( SEXP who){
std::string input = CHAR(STRING_ELT(input,0)) ;
@@ -180,11 +193,12 @@
\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
-\proglang{C++} functions and classes to \proglang{R}, grouped together in a single entity.
+Rcpp modules are inspired from Python modules that are generated by the
+\texttt{Boost.Python} library \citep{Boost:Python}. They provide an easy way
+to expose \proglang{C++} functions and classes to \proglang{R}, grouped
+together in a single entity.
-The module is created in a cpp file using the \texttt{RCPP\_MODULE}
+The module is created in a \texttt{cpp} file using the \texttt{RCPP\_MODULE}
macro, which then contains declarative code of what the module
exposes to \proglang{R}.
@@ -208,10 +222,11 @@
The code creates an Rcpp module called \texttt{yada}
that exposes the \texttt{hello} function. \pkg{Rcpp} automatically
-deduces the conversions that are needed for input and output.
+deduces the conversions that are needed for input and output. This alleviates
+the need for a wrapper function using either \pkg{Rcpp} or the \proglang{R} API.
-On the \proglang{R} side, the module is simply retrieved by using the \Sexpr{link("Module")}
-function from \pkg{Rcpp}:
+On the \proglang{R} side, the module is simply retrieved by using the
+\Sexpr{link("Module")} function from \pkg{Rcpp}:
<<eval=FALSE>>=
require( Rcpp )
@@ -285,7 +300,8 @@
\item The output type must be either \texttt{void} or any type that
can be managed by the \texttt{Rcpp::wrap} template.
\item The function name itself has to be unique, in other words no two functions with
- the same name but different signatures (as in \proglang{C++} itself) are allowed.
+ the same name but different signatures itself are allowed (whereas this is
+ possible in \proglang{C++} itself).
\end{itemize}
\subsection{Exposing \proglang{C++} classes}
@@ -331,8 +347,8 @@
generated from a template.
The construction of the object is then followed by two calls to the
-\texttt{method} member function of \texttt{class\_<World>}. \texttt{method}
-can expose :
+\texttt{method} member function of \texttt{class\_<World>}. The
+\texttt{method} methods can expose :
\begin{itemize}
\item member functions of the target class, such as \texttt{greet} or \texttt{set}, by
providing the name that will be used on the \proglang{R} side (e.g. \texttt{greet}) and
@@ -343,9 +359,10 @@
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 \proglang{R}. The Rcpp module assumes
-responsabilities for type conversion for input and output types.
+The module exposes the default constructor of the \texttt{World} class as
+well to support creation of \texttt{World} objects from \proglang{R}. The
+\pkg{Rcpp} module assumes responsabilities for type conversion for input and
+output types.
<<eval=FALSE>>=
require( Rcpp )
@@ -440,7 +457,7 @@
@
The \texttt{x} property is declared with both getter (\texttt{getX}) and
-setter (\texttt{x}) so that we can read and write the property at the R level
+setter (\texttt{setX}) so that we can read and write the property at the R level
with the dollar operator.
The\texttt{y} property only exposes a getter (\texttt{getY}) so attempting to
More information about the Rcpp-commits
mailing list