[Rcpp-commits] r2983 - pkg/Rcpp/inst/doc
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Apr 9 23:34:42 CEST 2011
Author: edd
Date: 2011-04-09 23:34:42 +0200 (Sat, 09 Apr 2011)
New Revision: 2983
Modified:
pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw
Log:
fixes from Achim's polishing of Rcpp-intro vignette (modulo one citation he suggested)
re-added nojss, short sweave snippet and final paragraph of intro now referring to paper
Modified: pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw 2011-04-09 21:33:46 UTC (rev 2982)
+++ pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw 2011-04-09 21:34:42 UTC (rev 2983)
@@ -1,74 +1,53 @@
%% use JSS class -- use 'nojss' to turn off header
\documentclass[shortnames,nojss,article]{jss}
-%\VignetteIndexEntry{Rcpp-introduction}
-%\VignetteKeywords{foreign function interface, .Call, C++, R}
-%\VignettePackage{Rcpp}
+\usepackage{booktabs,flafter,thumbpdf}
-\usepackage{booktabs} % fancier \hrule
-\usepackage{flafter} % for table 2
+\author{Dirk Eddelbuettel\\Debian Project \And Romain Fran\c{c}ois\\\proglang{R} Enthusiasts}
+\Plainauthor{Dirk Eddelbuettel, Romain Fran\c{c}ois}
-\newcommand{\R}{\proglang{R}\ } % NB forces a space so not good before % fullstop etc.
-\newcommand{\Cpp}{\proglang{C++}\ }
-
-\author{Dirk Eddelbuettel\\Debian Project \And Romain Fran\c{c}ois\\R Enthusiasts}
-\title{Rcpp: Seamless \R and \Cpp Integration}
-
-\Plainauthor{Dirk Eddelbuettel, Romain Fran\c{c}ois} % , Second Author} %% comma-separated
+\title{\pkg{Rcpp}: Seamless \proglang{R} and \proglang{C++} Integration}
\Plaintitle{Rcpp: Seamless R and C++ Integration}
-\Shorttitle{Rcpp: Seamless R and C++ Integration}
\Abstract{
- \noindent
- The \pkg{Rcpp} package simplifies integrating \Cpp code with \proglang{R}. It
- provides a consistent \Cpp class hierarchy that maps various types of \R
- objects (vectors, matrices, functions, environments, ...) to dedicated \Cpp
- classes. Object interchange between \R and \Cpp is managed by
+ The \pkg{Rcpp} package simplifies integrating \proglang{C++} code with \proglang{R}. It
+ provides a consistent \proglang{C++} class hierarchy that maps various types of \proglang{R}
+ objects (vectors, matrices, functions, environments, \dots) to dedicated \proglang{C++}
+ classes. Object interchange between \proglang{R} and \proglang{C++} is managed by
simple, flexible and extensible concepts which include broad support for
- \Cpp Standard Template Library idioms. \Cpp code can both be
+ \proglang{C++} Standard Template Library idioms. \proglang{C++} code can both be
compiled, linked and loaded on the fly, or added via packages.
Flexible error and exception code handling is provided.
\pkg{Rcpp} substantially lowers the barrier for programmers wanting to
- combine \Cpp code with \proglang{R}.
+ combine \proglang{C++} code with \proglang{R}.
}
-\Keywords{\proglang{R}, \proglang{C++}, Foreign function interface, \code{.Call}} %% at least one keyword must be supplied
-\Plainkeywords{R, C++, Foreign function interface, .Call} %% without formatting
+\Keywords{\proglang{R}, \proglang{C++}, foreign function interface, \code{.Call}}
+\Plainkeywords{R, C++, foreign function interface, .Call}
-%% publication information
-%% NOTE: Typically, this can be left commented and will be filled out by the technical editor
-%% \Volume{13}
-%% \Issue{9}
-%% \Month{September}
-%% \Year{2004}
-%% \Submitdate{2004-09-29}
-%% \Acceptdate{2004-09-29}
+\Volume{40}
+\Issue{8}
+\Month{April}
+\Year{2011}
+\Submitdate{2010-11-15}
+\Acceptdate{2011-03-21}
\Address{
Dirk Eddelbuettel \\
Debian Project \\
- River Forest, IL, USA\\
- %% Telephone: +43/1/31336-5053
- %% Fax: +43/1/31336-734
+ River Forest, IL, United States of America\\
E-mail: \email{edd at debian.org}\\
- URL: \url{http://dirk.eddelbuettel.com}\\
+ URL: \url{http://dirk.eddelbuettel.com/}\\
- % Can we add a second author ?
Romain Fran\c{c}ois\\
- Professional R Enthusiast\\
- 1 rue du Puits du Temple, 34 000 Montpellier\\
- FRANCE \\
+ Professional \proglang{R} Enthusiast\\
+ 1 rue du Puits du Temple\\
+ 34 000 Montpellier, France \\
E-mail: \email{romain at r-enthusiasts.com}\\
- URL: \url{http://romainfrancois.blog.free.fr}
+ URL: \url{http://romainfrancois.blog.free.fr/}
}
%% need no \usepackage{Sweave.sty}
-% ------------------------------------------------------------------------
-
-\begin{document}
-
-%\SweaveOpts{engine=R,eps=FALSE}
-
<<prelim,echo=FALSE,print=FALSE>>=
library(Rcpp)
rcpp.version <- packageDescription("Rcpp")$Version
@@ -78,50 +57,54 @@
%
+\begin{document}
+
+\vspace*{-0.25cm}
+
\section{Introduction}
-\R \citep{R:Main} is an extensible system.
-The `Writing R Extensions' manual \citep{R:Extensions}
-describes in detail how to augment \R with compiled code,
+\proglang{R} \citep{R:Main} is an extensible system.
+The `Writing \proglang{R} Extensions' manual \citep{R:Extensions}
+describes in detail how to augment \proglang{R} with compiled code,
focusing mostly on the \proglang{C} language, but also mentioning
-\proglang{C++} and \proglang{Fortran}. The \R Application Programming
-Interface (API) described in `Writing R Extensions' is
+\proglang{C++} and \proglang{Fortran}. The \proglang{R} application programming
+interface (API) described in `Writing \proglang{R} Extensions' is
based on a set of functions and macros operating on \code{SEXP} (pointers to
-\code{SEXPREC} or `S expression' structures, see the `R Language'
-manual \citep{R:Language} for details) which are the internal
-representation of \R objects.
-%
+\code{SEXPREC} or `\proglang{S} expression' structures, see the `\proglang{R} Language'
+manual \citealp{R:Language} for details) which are the internal
+representation of \proglang{R} objects.
In this article, we discuss the functionality of the \pkg{Rcpp}
-package \citep{CRAN:Rcpp}, which simplifies the usage of \Cpp code
-in \proglang{R}. Combining \R and \Cpp is not a new idea, so we start with
+package \citep{CRAN:Rcpp}, which simplifies the usage of \proglang{C++} code
+in \proglang{R}. Combining \proglang{R} and \proglang{C++} is not a new idea, so we start with
a short review of other approaches and give some historical
background on the development of \pkg{Rcpp}.
-% [RF] I find talking about classic API in here confusing, why not just keep it
-% to the Historical context subsection.
The \pkg{Rcpp} package provides a consistent API for seamlessly accessing,
-extending or modifying \R objects at the \Cpp level. The API is a rewritten
+extending or modifying \proglang{R} objects at the \proglang{C++} level. The API is a rewritten
and extented version of an earlier API which we refer to as the `classic
\pkg{Rcpp} API'. It is still provided in the \pkg{RcppClassic} package \citep{CRAN:RcppClassic}
to ensure compatibility, but its use is otherwise deprecated.
All new development should use the richer second API which
-is enclosed in the \pkg{Rcpp} \Cpp
+is enclosed in the \pkg{Rcpp} \proglang{C++}
namespace, and corresponds to the redesigned code base.
This article highlights some of the key design and implementation choices of
-the new API: Lightweight encapsulation of \R objects in \Cpp classes, automatic
-garbage collection strategy, code inlining, data interchange between \R and
+the new API: Lightweight encapsulation of \proglang{R} objects in \proglang{C++} classes, automatic
+garbage collection strategy, code inlining, data interchange between \proglang{R} and
\proglang{C++}, and error handling.
Several examples are included to illustrate the benefits of using \pkg{Rcpp}
-as opposed to the traditional \R API. Many more examples are available within
+as opposed to the traditional \proglang{R} API. Many more examples are available within
the package, both as explicit examples and as part of the numerous unit tests.
+%
+The \pkg{Rcpp} package is available from the Comprehensive \proglang{R} Archive Network (CRAN)
+at \url{http://CRAN.R-project.org/package=Rcpp}.
\makeatletter
\if at nojss
- This vignette corresponds to a forthcoming paper in the \textsl{Journal of
- Statistical Software} and is currently still identical to the published
- paper. Over time, this vignette version may receive minor updates. For
- citations, please refer to the published version.
+ This vignette corresponds to the paper published in the \textsl{Journal of
+ Statistical Software}. It is currently still identical to
+ the published paper. Over time, this vignette version may receive minor
+ updates. For citations, please use the publication \citep{JSS:Rcpp}.
This version corresponds to \pkg{Rcpp} version \Sexpr{rcpp.version} and was
typeset on \Sexpr{now.date}.
@@ -146,55 +129,42 @@
`classic \pkg{Rcpp}' interface. While not described here, this API will
be provided for the foreseeable future via the \pkg{RcppClassic} package.
-Reflecting evolving \Cpp coding standards \citep[see][]{Meyers:2005:EffectiveC++},
+Reflecting evolving \proglang{C++} coding standards \citep[see][]{Meyers:2005:EffectiveC++},
Eddelbuettel and Fran\c{c}ois started a significant redesign of the
code base in 2009. This added numerous new features several of which are described
-%below in section~\ref{sec:new_rcpp} on the \pkg{Rcpp} API
in this article as well as in multiple
vignettes included with the package. This new API is our current focus,
and we intend to both extend and support the API in future development of the
\pkg{Rcpp} package.
-\subsection{Related Work}
+\subsection{Related work}
-Integration of \Cpp and \R has been addressed by several authors; the earliest
+Integration of \proglang{C++} and \proglang{R} has been addressed by several authors; the earliest
published reference is probably \cite{Bates+DebRoy:2001:C++Classes}.
An unpublished paper by \cite{Java+Gaile+Manly:2007:RCpp} expresses several ideas
that are close to some of our approaches, though not yet fully fleshed out.
-%
The \pkg{Rserve} package \citep{Urbanek:2003:Rserve,CRAN:Rserve} acts as a
-socket server for \proglang{R}. On the server side, \pkg{Rserve} translates \R data
+socket server for \proglang{R}. On the server side, \pkg{Rserve} translates \proglang{R} data
structures into a binary serialization format and uses TCP/IP for
-transfer. On the client side, objects are reconstructed as instances of Java
-or \Cpp classes that emulate the structure of \R objects.
+transfer. On the client side, objects are reconstructed as instances of \proglang{Java}
+or \proglang{C++} classes that emulate the structure of \proglang{R} objects.
The packages \pkg{rcppbind} \citep{Liang:2008:rcppbind}, \pkg{RAbstraction}
\citep{Armstrong:2009:RAbstraction} and \pkg{RObjects}
-\citep{Armstrong:2009:RObjects} are all implemented using \Cpp templates.
-%However, neither has matured to the point of a CRAN release and it is
-%unclear how much usage these packages are seeing beyond their own authors.
+\citep{Armstrong:2009:RObjects} are all implemented using \proglang{C++} templates.
None of them have matured to the point of a CRAN release.
-%
\pkg{CXXR} \citep{Runnalls:2009:CXXR} approaches this topic from the other direction:
-Its aim is to completely refactor \R on a stronger \Cpp foundation.
-\pkg{CXXR} is therefore concerned with all aspects of the \R interpreter,
-read-eval-print loop (REPL), and threading; object interchange between \R and \Cpp is but one
+Its aim is to completely refactor \proglang{R} on a stronger \proglang{C++} foundation.
+\pkg{CXXR} is therefore concerned with all aspects of the \proglang{R} interpreter,
+read-eval-print loop (REPL), and threading; object interchange between \proglang{R} and \proglang{C++} is but one
part. A similar approach is discussed by \cite{TempleLang:2009:ModestProposal}
who suggests making low-level internals extensible by package developers in
order to facilitate extending \proglang{R}.
-%
\cite{TempleLang:2009:RGCCTranslationUnit}, using compiler output for
references on the code in order to add bindings and wrappers, offers
a slightly different angle.
-% [DE 12-Feb-2011] The next two paragraphs (Section 1.3) are somewhat blah.
-% We could kill it, or maybe add a quick third paragraph mentioning
-% a) the new API allows for more than just function calls
-% but a good, concise example would help
-% b) Rcpp modules, sugar, ...
-% Or shall we not bother and just leave it? Removing it entirely
-% makes a couple of the later pagebreaks somewhat awful.
-\subsection{Rcpp use cases}
+\subsection[Rcpp use cases]{\pkg{Rcpp} use cases}
\label{sec:classic_rcpp}
The core focus of \pkg{Rcpp} has always been on helping the
@@ -202,14 +172,14 @@
Here, we use `function' in the standard mathematical sense of providing
results (output) given a set of parameters or data (input).
This was
-facilitated from the earliest releases using \Cpp classes for receiving
-various types of \R objects, converting them to \Cpp objects and allowing the
-programmer to return the results to \R with relative ease.
+facilitated from the earliest releases using \proglang{C++} classes for receiving
+various types of \proglang{R} objects, converting them to \proglang{C++} objects and allowing the
+programmer to return the results to \proglang{R} with relative ease.
-This API therefore supports two typical use cases. First, existing \R code
-may be replaced by equivalent \Cpp code in order to reap
+This API therefore supports two typical use cases. First, existing \proglang{R} code
+may be replaced by equivalent \proglang{C++} code in order to reap
performance gains. This case is conceptually easy when there are
-(built- or run-time) dependencies on other \proglang{C} or \Cpp libraries. It typically
+(built- or run-time) dependencies on other \proglang{C} or \proglang{C++} libraries. It typically
involves setting up data and parameters---the right-hand side components of a
function call---before making the call in order to provide the result that is
to be assigned to the left-hand side. Second, \pkg{Rcpp} facilitates calling
@@ -218,40 +188,26 @@
and parameters are passed via \pkg{Rcpp} to a function set-up to call code
from an external library.
-% [DE 12-Feb-2011] Maybe we can add something like this? And then comment out
-% the last four lines of the first para in the next section?
-% Or even the full para ?
-Apart from this `vertical mode' of calling \Cpp from \proglang{R}, additional
+Apart from this `vertical mode' of calling \proglang{C++} from \proglang{R}, additional
features in the new API also support a more `horizontal mode' of directly
calling \pkg{Rcpp} objects. This was motivated by the needs of other
-projects such as \pkg{RInside} \citep{CRAN:RInside} for easy embedding of \R
-in \Cpp applications and \pkg{RProtoBuf} \citep{CRAN:RProtoBuf} to
+projects such as \pkg{RInside} \citep{CRAN:RInside} for easy embedding of \proglang{R}
+in \proglang{C++} applications and \pkg{RProtoBuf} \citep{CRAN:RProtoBuf} to
interface with the Protocol Buffers library. This use will be touched upon
in the next section, but a more detailed discussion is outside the scope of
-this paper. Lastly, the more recent additions `Rcpp modules' and `Rcpp sugar'
+this paper. Lastly, the more recent additions `\pkg{Rcpp} modules' and `\pkg{Rcpp} sugar'
also expand the use cases; see Section~\ref{sec:ongoing} below.
-\section{The Rcpp API}
+\section[The Rcpp API]{The \pkg{Rcpp} API}
\label{sec:new_rcpp}
-% [DE 12-Feb-2011] Moved above
-%The \pkg{Rcpp} API has recently been redesigned and extended,
-%based on the usage experience of several
-%years of \pkg{Rcpp} deployment, %repeated one sentence down needs from other projects,
-%knowledge of the internal \R API, as well as current \Cpp design approaches.
-%The new features in \pkg{Rcpp} were also motivated by the needs of other
-%projects such as \pkg{RInside} \citep{CRAN:RInside} for easy embedding
-%of \R in \Cpp applications and \pkg{RProtoBuf} \citep{CRAN:RProtoBuf}
-%that interfaces with the Protocol Buffers library.
-
\subsection{A first example}
We can illustrate the \pkg{Rcpp} API by revisiting the convolution example
-from the `Writing R Extensions' manual \citep[Chapter 5]{R:Extensions}. Using
+from the `Writing \proglang{R} Extensions' manual \citep[Chapter 5]{R:Extensions}. Using
\pkg{Rcpp}, this function can be written as follows:
-
-\begin{CodeChunk}
-\begin{CodeInput}
+%
+\begin{Code}
#include <Rcpp.h>
RcppExport SEXP convolve3cpp(SEXP a, SEXP b) {
@@ -267,26 +223,8 @@
return xab;
}
-\end{CodeInput}
-\end{CodeChunk}
-
-% We can highlight several aspects. First, only a single header file
-% \code{Rcpp.h} is needed to use the \pkg{Rcpp} API. Second, given two
-% arguments of type \code{SEXP}, a third is returned (as using only
-% \code{SEXP} types for input and output is prescribed by the \code{.Call()}
-% interface of the \R API). Third, both inputs are
-% converted to \Cpp vector types provided by \pkg{Rcpp} (and we have more to say about these
-% conversions below). Fourth, the
-% usefulness of these classes can be seen when we query the vectors directly
-% for their size---using the \code{size()} member function---in order to
-% reserve a new result type of appropriate length,
-% and with the use of the
-% \verb|operator[]| to extract and set individual elements of the vector.
-% Fifth, the computation itself is
-% straightforward embedded looping just as in the original examples in the
-% 'Writing R Extensions' manual \citep{R:Extensions}. Sixth, the return conversion
-% from the \code{NumericVector} to the \code{SEXP} type is also automatic.
-%% Alternatively using enumerate:
+\end{Code}
+%
We can highlight several aspects.
\begin{enumerate}
\item Only a single header file
@@ -296,9 +234,9 @@
\item Given two
arguments of type \code{SEXP}, a third is returned (as using only
\code{SEXP} types for input and output is prescribed by the \code{.Call()}
- interface of the \R API).
+ interface of the \proglang{R} API).
\item Both inputs are
- converted to \Cpp vector types provided by \pkg{Rcpp} (and we have more to say about these
+ converted to \proglang{C++} vector types provided by \pkg{Rcpp} (and we have more to say about these
conversions below).
\item The
usefulness of these classes can be seen when we query the vectors directly
@@ -308,35 +246,35 @@
\verb|operator[]| to extract and set individual elements of the vector.
\item The computation itself is
straightforward embedded looping just as in the original examples in the
- `Writing R Extensions' manual \citep{R:Extensions}.
+ `Writing \proglang{R} Extensions' manual \citep{R:Extensions}.
\item The return conversion
from the \code{NumericVector} to the \code{SEXP} type is also automatic.
\end{enumerate}
We argue that this \pkg{Rcpp}-based usage is much easier to read, write and debug than the
-\proglang{C} macro-based approach supported by \R itself.
+\proglang{C} macro-based approach supported by \proglang{R} itself.
-\subsection{Rcpp class hierarchy}
+\subsection[Rcpp class hierarchy]{\pkg{Rcpp} class hierarchy}
The \code{Rcpp::RObject} class is the basic class of the new \pkg{Rcpp} API.
-An instance of the \code{RObject} class encapsulates an \R object
-(itself represented by the R type \code{SEXP}), exposes methods that are appropriate for all types
+An instance of the \code{RObject} class encapsulates an \proglang{R} object
+(itself represented by the \proglang{R} type \code{SEXP}), exposes methods that are appropriate for all types
of objects and transparently manages garbage collection.
The most important aspect of the \code{RObject} class is that it is
a very thin wrapper around the \code{SEXP} it encapsulates. The
\code{SEXP} is indeed the only data member of an \code{RObject}. The
-\code{RObject} class does not interfere with the way \R manages its
+\code{RObject} class does not interfere with the way \proglang{R} manages its
memory and does not perform copies of the object into a suboptimal
-\Cpp representation. Instead, it merely acts as a proxy to the
+\proglang{C++} representation. Instead, it merely acts as a proxy to the
object it encapsulates so that methods applied to the \code{RObject}
instance are relayed back to the \code{SEXP} in terms of the standard
-\R API.
+\proglang{R} API.
The \code{RObject} class takes advantage of the explicit life cycle of
-\Cpp objects to manage exposure of the underlying \R object to the
+\proglang{C++} objects to manage exposure of the underlying \proglang{R} object to the
garbage collector. The \code{RObject} effectively treats
its underlying \code{SEXP} as a resource.
The constructor of the \code{RObject} class takes
@@ -349,21 +287,21 @@
the protection stack with \code{PROTECT} and \code{UNPROTECT} macros.
The \code{RObject} class defines a set of member functions applicable
-to any \R object, regardless of its type. This ranges from
+to any \proglang{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}) to
handling of slots\footnote{Member functions dealing with slots
-are only applicable to S4 objects; otherwise an exception is thrown.}
+are only applicable to \proglang{S}4 objects; otherwise an exception is thrown.}
(\texttt{hasSlot}, \texttt{slot}).
\subsection{Derived classes}
-Internally, an \R object must have one type amongst the set of
-predefined types, commonly referred to as SEXP types. The `R Internals'
+Internally, an \proglang{R} object must have one type amongst the set of
+predefined types, commonly referred to as SEXP types. The `\proglang{R} Internals'
manual \citep{R:Internals} documents these various types.
-\pkg{Rcpp} associates a dedicated \Cpp class for most SEXP types, and
-therefore only exposes functionality that is relevant to the \R object
+\pkg{Rcpp} associates a dedicated \proglang{C++} class for most SEXP types, and
+therefore only exposes functionality that is relevant to the \proglang{R} object
that it encapsulates.
For example \code{Rcpp::Environment} contains
@@ -373,45 +311,41 @@
\code{GenericVector} (also known as \code{List}) and
\code{ExpressionVector}---expose functionality to extract and set values from the vectors.
-The following sub-sections present typical uses of \pkg{Rcpp} classes in
-comparison with the same code expressed using functions and macros of the \R API.
+The following sections present typical uses of \pkg{Rcpp} classes in
+comparison with the same code expressed using functions and macros of the \proglang{R} API.
\subsection{Numeric vectors}
-The next code snippet is taken from `Writing R Extensions'
+The next code snippet is taken from `Writing \proglang{R} Extensions'
\citep[Section 5.9.1]{R:Extensions}. It allocates a \code{numeric} vector of two elements
and assigns some values to it using the \proglang{R} API.
-
-\begin{CodeChunk}
-\begin{CodeInput}
+%
+\begin{Code}
SEXP ab;
PROTECT(ab = allocVector(REALSXP, 2));
REAL(ab)[0] = 123.45;
REAL(ab)[1] = 67.89;
UNPROTECT(1);
-\end{CodeInput}
-\end{CodeChunk}
-
-Although this is one of the simplest examples in `Writing R Extensions',
+\end{Code}
+%
+Although this is one of the simplest examples in `Writing \proglang{R} Extensions',
it seems verbose and yet it is not obvious at first sight what is happening.
Memory is allocated by \code{allocVector}; we must also supply it with
the type of data (\code{REALSXP}) and the number of elements. Once
allocated, the \code{ab} object must be protected from garbage
collection.
Lastly, the \code{REAL} macro returns a pointer to the
-beginning of the actual array; its indexing does not resemble either \R or
+beginning of the actual array; its indexing does not resemble either \proglang{R} or
\proglang{C++}.
The code can be simplified using the \code{Rcpp::NumericVector} class:
-
-\begin{CodeChunk}
-\begin{CodeInput}
+%
+\begin{Code}
Rcpp::NumericVector ab(2);
ab[0] = 123.45;
ab[1] = 67.89;
-\end{CodeInput}
-\end{CodeChunk}
-
+\end{Code}
+%
The code contains fewer idiomatic decorations. The \code{NumericVector}
constructor is given the number of elements the vector contains (2), which
hides the call to the \code{allocVector} in the original code example. Also hidden is
@@ -419,90 +353,75 @@
\code{NumericVector} inherits from \code{RObject}. Values are assigned to
the first and second elements of the vector as \code{NumericVector} overloads
the \code{operator[]}.
-% (and indexing starts at zero, following common
-% \proglang{C} and \proglang{C++} standards for arrays and vectors).
The snippet can also be written more concisely as a single statement using the \code{create}
static member function of the \code{NumericVector} class:
-
-\begin{CodeChunk}
-\begin{CodeInput}
+%
+\begin{Code}
Rcpp::NumericVector ab = Rcpp::NumericVector::create(123.45, 67.89);
-\end{CodeInput}
-\end{CodeChunk}
+\end{Code}
-% It should be noted that although the copy constructor of the
-% \code{NumericVector} class is used, it does not imply copies of the
-% underlying array, only the \code{SEXP} (\textsl{i.e.}, a simple pointer) is copied.
\subsection{Character vectors}
-A second example deals with character vectors and emulates this \R code:
-
-\begin{CodeChunk}
+A second example deals with character vectors and emulates this \proglang{R} code:
+%
\begin{CodeInput}
R> c("foo", "bar")
\end{CodeInput}
-\end{CodeChunk}
-
-Using the traditional \R API, the vector can be allocated and filled as such:
-
-\begin{CodeChunk}
-\begin{CodeInput}
+%
+Using the traditional \proglang{R} API, the vector can be allocated and filled as such:
+%
+\begin{Code}
SEXP ab;
PROTECT(ab = allocVector(STRSXP, 2));
SET_STRING_ELT( ab, 0, mkChar("foo") );
SET_STRING_ELT( ab, 1, mkChar("bar") );
UNPROTECT(1);
-\end{CodeInput}
-\end{CodeChunk}
-
+\end{Code}
+%
This imposes on the programmer knowledge of \code{PROTECT}, \code{UNPROTECT},
\code{SEXP}, \code{allocVector}, \code{SET\_STRING\_ELT}, and \code{mkChar}.
%
Using the \code{Rcpp::CharacterVector} class, we can express the same
code more concisely:
-
-\begin{CodeChunk}
-\begin{CodeInput}
+%
+\begin{Code}
Rcpp::CharacterVector ab(2);
ab[0] = "foo";
ab[1] = "bar";
-\end{CodeInput}
-\end{CodeChunk}
+\end{Code}
-\section[R and C++ data interchange]{\R and \Cpp data interchange}
+\section[R and C++ data interchange]{\proglang{R} and \proglang{C++} data interchange}
In addition to classes, the \pkg{Rcpp} package contains two
-functions to perform conversion of \Cpp objects to \R objects and back.
+functions to perform conversion of \proglang{C++} objects to \proglang{R} objects and back.
-\subsection[C++ to R: wrap]{\Cpp to \proglang{R}: \code{wrap}}
+\subsection[C++ to R: wrap]{\proglang{C++} to \proglang{R}: \code{wrap}}
-The \Cpp to \R conversion is performed by the \code{Rcpp::wrap} templated
+The \proglang{C++} to \proglang{R} conversion is performed by the \code{Rcpp::wrap} templated
function. It uses advanced template metaprogramming techniques\footnote{A
discussion of template metaprogramming
\citep{Vandevoorde+Josuttis:2003:Templates,Abrahams+Gurtovoy:2004:TemplateMetaprogramming} is beyond the
scope of this article.} to convert a wide and extensible set of types and
-classes to the most appropriate type of \R object. The signature of the
+classes to the most appropriate type of \proglang{R} object. The signature of the
\code{wrap} template is as follows:
-
-\begin{CodeChunk}
-\begin{CodeInput}
+%
+\begin{Code}
template <typename T> SEXP wrap(const T& object);
-\end{CodeInput}
-\end{CodeChunk}
-
+\end{Code}
+%
The templated function takes a reference to a `wrappable'
-object and converts this object into a \code{SEXP}, which is what \R expects.
+object and converts this object into a \code{SEXP}, which is what \proglang{R} expects.
Currently wrappable types are:
\begin{itemize}
-\item primitive types: \code{int}, \code{double}, \code{bool}, ... which are converted
-into the corresponding atomic \R vectors;
-\item \code{std::string} objects which are converted to \R atomic character vectors;
-\item Standard Template Library (STL) containers such as \code{std::vector<T>} or \code{std::list<T>},
+\item primitive types: \code{int}, \code{double}, \code{bool}, \dots which are converted
+into the corresponding atomic \proglang{R} vectors;
+\item \code{std::string} objects which are converted to \proglang{R} atomic character vectors;
+\item Standard Template Library (STL) containers such as \code{std::vector<T>} or \code{std::map<T>},
as long as the template parameter type \code{T} is itself wrappable;
\item STL maps which use \code{std::string} for keys
-(\textsl{e.g.}, \code{std::map<std::string, T>}); as long as
+({e.g.}, \code{std::map<std::string, T>}); as long as
the type \code{T} is wrappable;
\item any type that implements implicit conversion to \code{SEXP} through the
\code{operator SEXP()};
@@ -516,12 +435,10 @@
to third-party types. The \pkg{RcppArmadillo}
\citep*{CRAN:RcppArmadillo} and \pkg{RcppGSL} \citep{CRAN:RcppGSL} packages
feature several examples.
-%
The following segment of code illustrates that the design allows
composition:
-\begin{CodeChunk}
-\begin{CodeInput}
+\begin{Code}
RcppExport SEXP someFunction() {
std::vector<std::map<std::string,int> > v;
std::map<std::string, int> m1;
@@ -537,59 +454,52 @@
v.push_back( m2 );
return Rcpp::wrap( v );
}
-\end{CodeInput}
-\end{CodeChunk}
-
+\end{Code}
+%
In this example, the STL types \verb+vector+ and \verb+map+ are used to
create a list of two named vectors. The member function \verb+push_back+
insert a given element into a vector. This example is equivalent to the
-result of this \R statement:
+result of this \proglang{R} statement:
+%
+\begin{Code}
+list(c(bar = 2L, foo = 1L), c(bar = 2L, baz = 3L, foo = 1L))
+\end{Code}
-\begin{CodeChunk}
- \begin{CodeInput}
-list( c( bar = 2L, foo = 1L) ,
- c( bar = 2L, baz = 3L, foo = 1L) )
- \end{CodeInput}
-\end{CodeChunk}
+\subsection[R to C++: as]{\proglang{R} to \proglang{C++}: \code{as}}
-\subsection[R to C++: as]{\R to \proglang{C++}: \code{as}}
-
-The reverse conversion from an \R object to a \Cpp object is implemented by variations of the
+The reverse conversion from an \proglang{R} object to a \proglang{C++} object is implemented by variations of the
\code{Rcpp::as} template whose signature is:
-
-\begin{CodeChunk}
-\begin{CodeInput}
+%
+\begin{Code}
template <typename T> T as(SEXP x) throw(not_compatible);
-\end{CodeInput}
-\end{CodeChunk}
-
+\end{Code}
+%
It offers less flexibility and currently
-handles conversion of \R objects into primitive types (\textsl{e.g.}, \code{bool}, \code{int}, \code{std::string}, ...),
-STL vectors of primitive types (\textsl{e.g.}, \code{std::vector<bool>},
-\code{std::vector<double>}, ...) and arbitrary types that offer
+handles conversion of \proglang{R} objects into primitive types ({e.g.}, \code{bool}, \code{int}, \code{std::string}, \dots),
+STL vectors of primitive types ({e.g.}, \code{std::vector<bool>},
+\code{std::vector<double>}, \dots) and arbitrary types that offer
a constructor that takes a \code{SEXP}. In addition \code{as} can
-be fully or partially specialized to manage conversion of \R data
+be fully or partially specialized to manage conversion of \proglang{R} data
structures to third-party types as can be seen for example in the
-\pkg{RcppArmadillo} package which eases transfer of \R matrices and vectors to
-the optimised data structures in the Armadillo linear algebra library \citep{Sanderson:2010:Armadillo}.
+\pkg{RcppArmadillo} package which eases transfer of \proglang{R} matrices and vectors to
+the optimised data structures in the \pkg{Armadillo} linear algebra library \citep{Sanderson:2010:Armadillo}.
\subsection{Implicit use of converters}
The converters offered by \code{wrap} and \code{as} provide a very
-useful framework to implement code logic in terms of \Cpp
+useful framework to implement code logic in terms of \proglang{C++}
data structures and then explicitly convert data back to \proglang{R}.
In addition, the converters are also used implicitly
in various places in the \code{Rcpp} API.
Consider the following code that uses the \code{Rcpp::Environment} class to
-interchange data between \Cpp and \proglang{R}. It accesses a vector
+interchange data between \proglang{C++} and \proglang{R}. It accesses a vector
\texttt{x} from the global environment, creates an STL \texttt{map} of string
types and pushes this back to \proglang{R}:
-
-\begin{CodeChunk}
-\begin{CodeInput}
+%
+\begin{Code}
Rcpp::Environment global = Rcpp::Environment::global_env();
std::vector<double> vx = global["x"];
@@ -598,9 +508,8 @@
map["bar"] = "rab";
global["y"] = map;
-\end{CodeInput}
-\end{CodeChunk}
-
+\end{Code}
+%
In the first part of the example, the code extracts a
\code{std::vector<double>} from the global environment. In order to achieve this,
the \code{operator[]} of \code{Environment} uses the proxy pattern
@@ -624,93 +533,84 @@
\section{Function calls}
\label{sec:functions}
-\begin{table}[p]
+\begin{table}[t!]
\begin{minipage}[t]{0.465\linewidth}
\centering{\underline{Environment: Using the \pkg{Rcpp} API}}
- \begin{CodeChunk}
- \begin{CodeInput}
+ \begin{Code}
Environment stats("package:stats");
Function rnorm = stats["rnorm"];
-return rnorm(10, Named("sd", 100.0));
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/rcpp -r 2983
More information about the Rcpp-commits
mailing list