[Rcpp-commits] r2939 - in pkg/Rcpp: . inst inst/doc
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sun Apr 3 19:17:09 CEST 2011
Author: edd
Date: 2011-04-03 19:17:09 +0200 (Sun, 03 Apr 2011)
New Revision: 2939
Added:
pkg/Rcpp/inst/CITATION
pkg/Rcpp/inst/doc/jss.bst
Modified:
pkg/Rcpp/.Rbuildignore
pkg/Rcpp/ChangeLog
pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw
Log:
Added JSS version of Rcpp-introduction vignette (in 'nojss' mode)
Added an 'if nojss' section at the end of the introduction discussing the difference between the published (static) version and the vignette which may get updates
Added jss.bst to support Bibtex style used
Added CITATION file (but that is a little soon -- so added to .Rbuildignore too
Modified: pkg/Rcpp/.Rbuildignore
===================================================================
--- pkg/Rcpp/.Rbuildignore 2011-04-02 21:12:29 UTC (rev 2938)
+++ pkg/Rcpp/.Rbuildignore 2011-04-03 17:17:09 UTC (rev 2939)
@@ -3,3 +3,4 @@
inst/doc/latex
inst/doc/man
build
+inst/CITATION
Modified: pkg/Rcpp/ChangeLog
===================================================================
--- pkg/Rcpp/ChangeLog 2011-04-02 21:12:29 UTC (rev 2938)
+++ pkg/Rcpp/ChangeLog 2011-04-03 17:17:09 UTC (rev 2939)
@@ -1,10 +1,18 @@
-2011-04-02 Dirk Eddelbuettel <edd at debian.org>
+2011-04-xx Dirk Eddelbuettel <edd at debian.org>
* DESCRIPTION: Release 0.9.3
* inst/NEWS: Release 0.9.3
* inst/include/Rcpp/config.h: Release 0.9.3
* debian/*: Similarly updated for new release to Debian
+2011-04-03 Dirk Eddelbuettel <edd at debian.org>
+
+ * inst/doc/Rcpp-introduction.Rnw: Updated to forthcoming JSS paper
+
+ * inst/CITATION: Added citation() support using forthcoming paper
+
+2011-04-02 Dirk Eddelbuettel <edd at debian.org>
+
* cleanup: Also clean in inst/unitTest/testRcppModule/src/
* inst/include/RcppCommon.h: Define new variable for g++ < 4.6.0
Added: pkg/Rcpp/inst/CITATION
===================================================================
--- pkg/Rcpp/inst/CITATION (rev 0)
+++ pkg/Rcpp/inst/CITATION 2011-04-03 17:17:09 UTC (rev 2939)
@@ -0,0 +1,19 @@
+citHeader("To cite Rcpp in publications use:")
+
+citEntry(entry="Article",
+ title = "Rcpp: Seamless R and C++ Integration",
+ author = personList(as.person("Dirk Eddelbuettel"),
+ as.person("Romain Francois")),
+ journal = "Journal of Statistical Software",
+ year = "forthcoming",
+ volume = "XX",
+ number = "YY,
+ pages = "aa--bb",
+ url = "http://www.jstatsoft.org/vXX/iYY/",
+
+ textVersion =
+ paste("Dirk Eddelbuettel and Romain Francois (2011).",
+ "Rcpp: Seamless R and C++ Integration.",
+ "Journal of Statistical Software, xx(yy), aa-bb.",
+ "URL http://www.jstatsoft.org/vXX/iYY/")
+)
Modified: pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw 2011-04-02 21:12:29 UTC (rev 2938)
+++ pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw 2011-04-03 17:17:09 UTC (rev 2939)
@@ -1,176 +1,260 @@
-\documentclass[a4paper]{report}
+%% 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{a4wide,graphicx,color}
-\usepackage[authoryear,round,longnamesfirst]{natbib}
-\bibliographystyle{abbrvnat}
-
\usepackage{booktabs} % fancier \hrule
-\usepackage{float} % float 'here' -- but not with multicol?
-\restylefloat{figure}
+\usepackage{flafter} % for table 2
-\usepackage{RJournal}
+\newcommand{\R}{\proglang{R}\ } % NB forces a space so not good before % fullstop etc.
+\newcommand{\Cpp}{\proglang{C++}\ }
-\RequirePackage{ae,mathpple} % ae as a default font pkg works with Sweave
-\RequirePackage[T1]{fontenc}
+\author{Dirk Eddelbuettel\\Debian Project \And Romain Fran\c{c}ois\\R Enthusiasts}
+\title{Rcpp: Seamless \R and \Cpp Integration}
-\begin{document}
+\Plainauthor{Dirk Eddelbuettel, Romain Fran\c{c}ois} % , Second Author} %% comma-separated
+\Plaintitle{Rcpp: Seamless R and C++ Integration}
+\Shorttitle{Rcpp: Seamless R and C++ Integration}
-\SweaveOpts{engine=R,eps=FALSE}
+\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
+ simple, flexible and extensible concepts which include broad support for
+ \Cpp Standard Template Library idioms. \Cpp 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}.
+}
-%% do not edit, for illustration only
-\fancyhf{}
-\fancyhead[LO,RE]{\textsc{Revised Article currently under Review}}
-\fancyhead[RO,LE]{\thepage}
-%\fancyfoot[L]{The R Journal Vol. X/Y, Month, Year}
-%\fancyfoot[R]{ISSN 2073-4859}
+\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
-\begin{article}
- %\input{EddelbuettelFrancois} %% pull in EddelbuettelFrancois.tex
+%% 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}
-\title{Rcpp: Seamless R and C++ integration}
-\author{by Dirk Eddelbuettel and Romain Fran\c{c}ois}
+\Address{
+ Dirk Eddelbuettel \\
+ Debian Project \\
+ River Forest, IL, USA\\
+ %% Telephone: +43/1/31336-5053
+ %% Fax: +43/1/31336-734
+ E-mail: \email{edd at debian.org}\\
+ URL: \url{http://dirk.eddelbuettel.com}\\
-\maketitle
+ % Can we add a second author ?
+ Romain Fran\c{c}ois\\
+ Professional 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}
+}
-\abstract{The \pkg{Rcpp} package simplifies integrating C++ code with R. It
- provides a consistent C++ class hierarchy that maps various types of R
- objects (vectors, functions, environments, ...) to dedicated C++
- classes. Object interchange between R and C++ is managed by
- simple, flexible and extensible concepts which include broad support for
- C++ STL idioms. C++ code can be compiled, linked and loaded on the fly.
- Flexible error and exception code handling is provided. \pkg{Rcpp}
- substantially lowers the barrier for programmers wanting to combine
- C++ code with R.}
+%% need no \usepackage{Sweave.sty}
-\section{Introduction}
+% ------------------------------------------------------------------------
-R is an extensible system. The `Writing R Extensions' manual \citep{R:Extensions}
-describes in detail how to augment R with compiled code,
-focusing mostly on the C language. The R API described in `Writing R Extensions' is
-based on a set of functions and macros operating on \code{SEXP}, the internal
-representation of R objects.
+\begin{document}
+
+%\SweaveOpts{engine=R,eps=FALSE}
+
+<<prelim,echo=FALSE,print=FALSE>>=
+library(Rcpp)
+rcpp.version <- packageDescription("Rcpp")$Version
+rcpp.date <- packageDescription("Rcpp")$Date
+now.date <- strftime(Sys.Date(), "%B %d, %Y")
+@
%
+
+
+\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,
+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
+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.
+%
In this article, we discuss the functionality of the \pkg{Rcpp}
-package, which simplifies the usage of C++ code
-in R. Combining R and C++ is not a new idea, so we start with
+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
a short review of other approaches and give some historical
background on the development of \pkg{Rcpp}.
-The \pkg{Rcpp} package combines two distinct
-APIs. The first---which we call `classic \pkg{Rcpp} API'---exists since
-the first version of \pkg{Rcpp}. While still contained in the package to
-ensure compatibility, its use is otherwise deprecated. All new development should
-use the richer second API. It is enclosed in the \pkg{Rcpp} C++
-namespace, and corresponds to the redesigned code base.
+% [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
+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
+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 C++ classes, automatic
-garbage collection strategy, code inlining, data interchange between R and
-C++ and error handling.
+the new API: Lightweight encapsulation of \R objects in \Cpp classes, automatic
+garbage collection strategy, code inlining, data interchange between \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 \R API. Many more examples are available within
the package, both as explicit examples and as part of the numerous unit tests.
-\subsection{Historical Context}
+\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.
-\pkg{Rcpp} first appeared in 2005 as a contribution (by Samperi) to the
-\pkg{RQuantLib} package \citep{CRAN:RQuantLib} before becoming a CRAN package
+ This version corresponds to \pkg{Rcpp} version \Sexpr{rcpp.version} and was
+ typeset on \Sexpr{now.date}.
+\fi
+\makeatother
+
+
+\subsection{Historical context}
+
+\pkg{Rcpp} first appeared in 2005 as a contribution (by Dominick Samperi) to the
+\pkg{RQuantLib} package \citep{CRAN:RQuantLib} and became a CRAN package
in early 2006. Several releases (all by Samperi) followed in quick succession
under the name \pkg{Rcpp}. The package was then renamed to
\pkg{RcppTemplate}; several more releases followed during 2006 under the new
-name. However, no new releases were made during 2007, 2008 or most of
-2009. Following a few updates in late 2009, it has since been withdrawn from CRAN.
+name. However, no further releases were made during 2007, 2008 or most of
+2009. Following a few updates in late 2009, it was withdrawn from CRAN.
Given the continued use of the package, Eddelbuettel decided to revitalize it. New
releases, using the initial name \pkg{Rcpp}, started in November 2008. These
-already included an improved build and distribution process, additional
+included an improved build and distribution process, additional
documentation, and new functionality---while retaining the existing
-interface. This constitutes the `classic \pkg{Rcpp}' interface
-(not described in this article) which will be maintained for the foreseeable future.
+`classic \pkg{Rcpp}' interface. While not described here, this API will
+be provided for the foreseeable future via the \pkg{RcppClassic} package.
-Yet C++ coding standards continued to evolve \citep{Meyers:2005:EffectiveC++}.
-In 2009, Eddelbuettel and Fran\c{c}ois started a significant redesign of the
-code base which added numerous new features. Several of these are described
-below in the section on the \pkg{Rcpp} API interface, as well as in the
-eight vignettes included with the package. This new API is our current focus,
-and we intend to both extend and support it in future development of the
-package.
+Reflecting evolving \Cpp 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{Comparison}
+\subsection{Related Work}
-Integration of C++ and R has been addressed by several authors; the earliest
+Integration of \Cpp and \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} was another early approach,
-going back to 2002. On the server side, \pkg{Rserve} translates R data
+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
structures into a binary serialization format and uses TCP/IP for
transfer. On the client side, objects are reconstructed as instances of Java
-or C++ classes that emulate the structure of R objects.
+or \Cpp classes that emulate the structure of \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 C++ 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.
-
-\pkg{CXXR} \citep{Runnalls:2009:CXXR} comes to this topic from the other side:
-its aim is to completely refactor R on a stronger C++ foundation.
-\pkg{CXXR} is therefore concerned with all aspects of the R interpreter,
-REPL, threading---and object interchange between R and C++ is but one
+\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.
+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
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 \R.
+order to facilitate extending \proglang{R}.
%
-Another slightly different angle is offered by
-\cite{TempleLang:2009:RGCCTranslationUnit} who uses compiler output for
-references on the code in order to add bindings and wrappers.
+\cite{TempleLang:2009:RGCCTranslationUnit}, using compiler output for
+references on the code in order to add bindings and wrappers, offers
+a slightly different angle.
-\subsection{Rcpp Use Cases}
+% [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}
\label{sec:classic_rcpp}
-The core focus of \pkg{Rcpp} has always been on allowing the
-programmer to add C++-based functions.
+The core focus of \pkg{Rcpp} has always been on helping the
+programmer to more easily add \proglang{C++}-based functions.
Here, we use `function' in the standard mathematical sense of providing
-results (output) given a set of parameters or data (input).
+results (output) given a set of parameters or data (input).
This was
-facilitated from the earliest releases using C++ classes for receiving
-various types of R objects, converting them to C++ objects and allowing the
-programmer to return the results to R with relative ease.
+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.
-This API therefore supports two typical use cases. First, one can think of
-replacing existing R code with equivalent C++ code in order to reap
-performance gains. This case is conceptually easy as there may not be
-(built- or run-time) dependencies on other C or C++ libraries. It typically
+This API therefore supports two typical use cases. First, existing \R code
+may be replaced by equivalent \Cpp 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
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
-functions provided by other libraries. The use resembles the first case: data
+functions provided by other libraries. The use resembles the first case but
+with an additional level of abstraction: data
and parameters are passed via \pkg{Rcpp} to a function set-up to call code
-from an external library.
+from an external library.
-\section{The \pkg{Rcpp} API}
+% [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
+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
+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'
+also expand the use cases; see Section~\ref{sec:ongoing} below.
+
+\section{The Rcpp API}
\label{sec:new_rcpp}
-More recently, the \pkg{Rcpp} API has been redesigned and extended,
-based on the usage experience of several
-years of \pkg{Rcpp} deployment, needs from other projects, knowledge
-of the internal R API, as well as current C++ 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 C++ applications and \pkg{RProtoBuf} \citep{CRAN:RProtoBuf}
-that interfaces with the Protocol Buffers library.
+% [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}
+\subsection{A first example}
-\begin{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
+\pkg{Rcpp}, this function can be written as follows:
+
+\begin{CodeChunk}
+\begin{CodeInput}
#include <Rcpp.h>
-RcppExport SEXP convolve3cpp(SEXP a, SEXP b) \{
+RcppExport SEXP convolve3cpp(SEXP a, SEXP b) {
Rcpp::NumericVector xa(a);
Rcpp::NumericVector xb(b);
int n_xa = xa.size(), n_xb = xb.size();
@@ -178,404 +262,507 @@
Rcpp::NumericVector xab(nab);
for (int i = 0; i < n_xa; i++)
- for (int j = 0; j < n_xb; j++)
+ for (int j = 0; j < n_xb; j++)
xab[i + j] += xa[i] * xb[j];
return xab;
-\}
-\end{example}
+}
+\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. Third, both inputs are
-converted to C++ 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.
+% 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:
+We can highlight several aspects.
+\begin{enumerate}
+\item Only a single header file
+ \code{Rcpp.h} is needed to use the \pkg{Rcpp} API.
+\item \code{RcppExport} is a convenience macro helping with calling a
+ \proglang{C} function from \proglang{C++}.
+\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).
+\item Both inputs are
+ converted to \Cpp 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
+ 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.
+\item The computation itself is
+ straightforward embedded looping just as in the original examples in the
+ `Writing 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
-C macro-based approach supported by R itself.
+\proglang{C} macro-based approach supported by \R itself.
-\subsection{Rcpp Class hierarchy}
+\subsection{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
-(\code{SEXP}), exposes methods that are appropriate for all types
+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
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
-memory and does not perform copies of the object into a suboptimal
-C++ representation. Instead, it merely acts as a proxy to the
+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
+memory and does not perform copies of the object into a suboptimal
+\Cpp 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.
+\R API.
-The \code{RObject} class takes advantage of the explicit life cycle of
-C++ objects to manage exposure of the underlying R object to the
-garbage collector. The \code{RObject} effectively treats
+The \code{RObject} class takes advantage of the explicit life cycle of
+\Cpp objects to manage exposure of the underlying \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
+The constructor of the \code{RObject} class takes
the necessary measures to guarantee that the underlying \code{SEXP}
is protected from the garbage collector, and the destructor
-assumes the responsibility to withdraw that protection.
+assumes the responsibility to withdraw that protection.
By assuming the entire responsibility of garbage collection, \pkg{Rcpp}
relieves the programmer from writing boiler plate code to manage
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
-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{The member functions that deal with slots
-are only applicable to S4 objects; otherwise an exception is thrown.}
+to any \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.}
(\texttt{hasSlot}, \texttt{slot}).
\subsection{Derived classes}
-Internally, an R object must have one type amongst the set of
+Internally, an \R object must have one type amongst the set of
predefined types, commonly referred to as SEXP types. The `R Internals'
-manual \citep{R:Internals} documents these various types.
-\pkg{Rcpp} associates a dedicated C++ class for most SEXP types, and
-therefore only exposes functionality that is relevant to the R object
+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
that it encapsulates.
-For example \code{Rcpp::Environment} contains
-member functions to manage objects in the associated environment.
-Similarly, classes related to vectors---\code{IntegerVector}, \code{NumericVector},
-\code{RawVector}, \code{LogicalVector}, \code{CharacterVector},
-\code{GenericVector} (also known as \code{List}) and
+For example \code{Rcpp::Environment} contains
+member functions to manage objects in the associated environment.
+Similarly, classes related to vectors---\code{IntegerVector}, \code{NumericVector},
+\code{RawVector}, \code{LogicalVector}, \code{CharacterVector},
+\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.
+comparison with the same code expressed using functions and macros of the \R API.
\subsection{Numeric vectors}
-The following code snippet is taken from Writing R extensions
-\citep{R:Extensions}. It creates a \code{numeric} vector of two elements
-and assigns some values to it.
+The next code snippet is taken from `Writing 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{example}
+\begin{CodeChunk}
+\begin{CodeInput}
SEXP ab;
PROTECT(ab = allocVector(REALSXP, 2));
REAL(ab)[0] = 123.45;
REAL(ab)[1] = 67.89;
UNPROTECT(1);
-\end{example}
+\end{CodeInput}
+\end{CodeChunk}
-Although this is one of the simplest examples in Writing R extensions,
-it seems verbose and it is not obvious at first sight what is happening.
+Although this is one of the simplest examples in `Writing 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
-C++.
+beginning of the actual array; its indexing does not resemble either \R or
+\proglang{C++}.
-Using the \code{Rcpp::NumericVector} class, the code can be rewritten:
+The code can be simplified using the \code{Rcpp::NumericVector} class:
-\begin{example}
+\begin{CodeChunk}
+\begin{CodeInput}
Rcpp::NumericVector ab(2);
ab[0] = 123.45;
ab[1] = 67.89;
-\end{example}
+\end{CodeInput}
+\end{CodeChunk}
The code contains fewer idiomatic decorations. The \code{NumericVector}
constructor is given the number of elements the vector contains (2), which
-hides a call to the \code{allocVector} we saw previously. Also hidden is
+hides the call to the \code{allocVector} in the original code example. Also hidden is
protection of the object from garbage collection, which is a behavior that
\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 using the \code{create}
-static member function of the \code{NumericVector} class:
+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{example}
-Rcpp::NumericVector ab =
- Rcpp::NumericVector::create(123.45, 67.89);
-\end{example}
+\begin{CodeChunk}
+\begin{CodeInput}
+Rcpp::NumericVector ab = Rcpp::NumericVector::create(123.45, 67.89);
+\end{CodeInput}
+\end{CodeChunk}
-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.
+% 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
+A second example deals with character vectors and emulates this \R code:
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/rcpp -r 2939
More information about the Rcpp-commits
mailing list