[Rcpp-commits] r854 - pkg/Rcpp/inst/doc
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sun Mar 7 17:34:35 CET 2010
Author: edd
Date: 2010-03-07 17:34:35 +0100 (Sun, 07 Mar 2010)
New Revision: 854
Added:
pkg/Rcpp/inst/doc/RJournal.sty
pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw
Log:
adding Rcpp-introduction.Rnw as the current version of the RJ paper
Added: pkg/Rcpp/inst/doc/RJournal.sty
===================================================================
--- pkg/Rcpp/inst/doc/RJournal.sty (rev 0)
+++ pkg/Rcpp/inst/doc/RJournal.sty 2010-03-07 16:34:35 UTC (rev 854)
@@ -0,0 +1,232 @@
+%%
+%% This is file `RJournal.sty',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% RJournal.dtx (with options: `package')
+%%
+\def\fileversion{v0.6}
+\def\filename{RJournal}
+\def\filedate{2009/05/05}
+\def\docdate {2009/05/05}
+%%
+%% Package `RJournal' to use with LaTeX2e
+%% Copyright (C) 2009 by the R Foundation
+%% Please report errors to KH or FL
+%%
+%% %% -*- LaTeX -*-
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesPackage{\filename}[\filedate\space\fileversion\space
+ RJournal package]
+\typeout{Package: `\filename\space\fileversion \@spaces <\filedate>'}
+\typeout{English documentation as of <\docdate>}
+\RequirePackage{ifthen}
+\newboolean{RJ at driver}
+\DeclareOption{driver}{\setboolean{RJ at driver}{true}}
+\DeclareOption*{\PackageWarning{\filename}{Unknown option
+ `\CurrentOption'}}
+\ProcessOptions\relax
+\ifthenelse{\boolean{RJ at driver}}{}{
+\RequirePackage{tikz}
+\RequirePackage{multicol,graphicx,color,fancyhdr}
+\RequirePackage{hyperref}
+\RequirePackage{amsmath}
+\definecolor{link}{rgb}{0,0,0.3}
+\hypersetup{
+ colorlinks,%
+ citecolor=link,%
+ filecolor=link,%
+ linkcolor=link,%
+ urlcolor=link
+}
+\IfFileExists{upquote.sty}{\RequirePackage{upquote}}{}
+\newcommand{\volume}[1]{\def\RJ at volume{#1}}
+\newcommand{\volnumber}[1]{\def\RJ at number{#1}}
+\renewcommand{\date}[1]{\def\RJ at date{#1}}
+\setcounter{secnumdepth}{-1}
+\renewcommand{\author}[1]{\def\RJ at author{#1}}
+\renewcommand{\title}[1]{\def\RJ at title{#1}}
+\newcommand{\subtitle}[1]{\def\RJ at subtitle{#1}}
+\newcommand{\sectionhead}[1]{\def\RJ at sectionhead{#1}}
+\newenvironment{article}{%
+ \author{}\title{}\subtitle{}}{\end{multicols}}
+\renewcommand{\maketitle}{
+ \begin{multicols}{2}[\chapter{\RJ at title}\refstepcounter{chapter}][3cm]
+ \ifx\empty\RJ at subtitle\else\noindent\textbf{\RJ at subtitle}
+ \par\nobreak\addvspace{\baselineskip}\fi
+ \ifx\empty\RJ at author\else\noindent\textit{\RJ at author}
+ \par\nobreak\addvspace{\baselineskip}\fi
+ \@afterindentfalse\@nobreaktrue\@afterheading}
+\renewcommand{\abstract}[1]{\begin{center}\begin{minipage}{0.92\linewidth}
+ \textbf{Abstract } #1 \end{minipage}\end{center} \subsubsection{} \vspace{-12pt}}
+\renewcommand\chapter{\secdef\RJ at chapter\@schapter}
+\providecommand{\nohyphens}{%
+ \hyphenpenalty=10000\exhyphenpenalty=10000\relax}
+\newcommand{\RJ at chapter}{%
+ \edef\name at of@eq{equation.\@arabic{\c at chapter}}%
+ \renewcommand{\@seccntformat}[1]{}%
+ \@startsection{chapter}{0}{0mm}{%
+ -2\baselineskip \@plus -\baselineskip \@minus -.2ex}{\p@}{%
+ \normalfont\Huge\bfseries\raggedright}%
+}
+\renewcommand*\l at chapter{\@dottedtocline{0}{0pt}{1em}}
+\def\@schapter#1{\section*#1}
+\renewenvironment{figure}[1][]{%
+ \def\@captype{figure}
+ \noindent
+ \begin{minipage}{\columnwidth}}{%
+ \end{minipage}\par\addvspace{\baselineskip}}
+\numberwithin{equation}{chapter}
+\renewcommand{\theequation}{\@arabic\c at equation}
+\renewcommand{\thefigure}{\@arabic\c at figure}
+\renewcommand{\thetable}{\@arabic\c at table}
+\renewcommand{\contentsname}{Contents}
+\renewcommand\tableofcontents{%
+\begin{center}
+\vspace{1cm}
+\begin{tikzpicture}
+\node[right,text width=15.5cm, draw=black, rounded corners=20pt,
+fill=white,inner sep=2em, very thick]
+{
+ \begin{minipage}[t][16.5cm][c]{1.0\linewidth}
+ \section*{\contentsname}
+ {
+ \@starttoc{toc}
+ }
+ \end{minipage}
+};
+
+\end{tikzpicture}
+\end{center}}
+\renewcommand{\titlepage}{%
+ \noindent
+ \begin{center}
+ \fontsize{60pt}{60pt}\selectfont
+The \raisebox{-8pt}{\includegraphics[height=77pt]{Rlogo-4}}\hspace{10pt}
+ Journal
+ \end{center}
+{\large\hfill Volume \RJ at volume/\RJ at number, \RJ at date\qquad}
+\\[-.5\baselineskip]
+ \rule{\textwidth}{1pt}
+\begin{center}
+{\Large A peer-reviewed, open-access publication of the R Foundation\\
+for Statistical Computing}
+\end{center}
+ \fancyhf{}
+ \fancyhead[LO,RE]{\textsc{\RJ at sectionhead}}
+ \fancyhead[RO,LE]{\thepage}
+ \fancyfoot[L]{The R Journal Vol. \RJ at volume/\RJ at number, \RJ at date}
+ \fancyfoot[R]{ISSN 2073-4859}
+ \thispagestyle{empty}
+\setcounter{tocdepth}{0}
+\tableofcontents
+\setcounter{tocdepth}{2}
+\clearpage
+}
+\newcommand{\startRnews}{%
+ \newpage\noindent
+ \begin{center}
+ \fontsize{15mm}{1mm}\selectfont
+ \includegraphics[height=15mm]{Rlogo}\hspace{7mm}
+ News
+ \end{center}
+ \rule{\textwidth}{.5pt}
+ \vspace{1cm}
+ \addcontentsline{toc}{chapter}{R News}
+}
+
+\setlength{\textheight}{250mm}
+\setlength{\topmargin}{-10mm}
+\setlength{\textwidth}{17cm}
+\setlength{\oddsidemargin}{-6mm}
+\setlength{\evensidemargin}{-6mm}
+\setlength{\columnseprule}{.1pt}
+\setlength{\columnsep}{20pt}
+%% sf & almost european \\
+\RequirePackage{pslatex}
+\RequirePackage{palatino,mathpazo}
+\RequirePackage[T1]{fontenc}
+\definecolor{Red}{rgb}{0.7,0,0}
+\definecolor{Blue}{rgb}{0,0,0.8}
+\definecolor{hellgrau}{rgb}{0.55,0.55,0.55}
+\newcommand{\R}{R}
+\newcommand{\address}[1]{\addvspace{\baselineskip}\noindent\emph{#1}}
+\newcommand{\email}[1]{\href{mailto:#1}{\normalfont\texttt{#1}}}
+\newsavebox{\RJ at box}
+\newlength{\RJ at len}
+\newenvironment{bottombox}{%
+ \begin{figure*}[b]
+ \begin{center}
+ \noindent
+ \begin{lrbox}{\RJ at box}
+ \begin{minipage}{0.99\textwidth}}{%
+ \end{minipage}
+ \end{lrbox}
+ \addtolength{\RJ at len}{\fboxsep}
+ \addtolength{\RJ at len}{\fboxrule}
+ \hspace*{-\RJ at len}\fbox{\usebox{\RJ at box}}
+ \end{center}
+ \end{figure*}}
+\RequirePackage{verbatim}
+\def\boxedverbatim{%
+ \def\verbatim at processline{%
+ {\setbox0=\hbox{\the\verbatim at line}%
+ \hsize=\wd0 \the\verbatim at line\par}}%
+ \@minipagetrue
+ \@tempswatrue
+ \setbox0=\vbox
+ \bgroup\small\verbatim
+}
+\def\endboxedverbatim{%
+ \endverbatim
+ \unskip\setbox0=\lastbox
+ \egroup
+ \fbox{\box0}
+}
+\pagestyle{fancy}
+} % \ifthenelse{\boolean{RJ at driver}}
+\newcommand\code{\bgroup\@codex}
+\def\@codex#1{\texorpdfstring%
+{{\normalfont\ttfamily\hyphenchar\font=-1 #1}}%
+{#1}\egroup}
+\newcommand{\kbd}[1]{{\normalfont\texttt{#1}}}
+\newcommand{\key}[1]{{\normalfont\texttt{\uppercase{#1}}}}
+\newcommand\samp{`\bgroup\@noligs\@sampx}
+\def\@sampx#1{{\normalfont\texttt{#1}}\egroup'}
+\newcommand{\var}[1]{{\normalfont\textsl{#1}}}
+\let\env=\code
+\newcommand{\file}[1]{{`\normalfont\textsf{#1}'}}
+\let\command=\code
+\let\option=\samp
+\newcommand{\dfn}[1]{{\normalfont\textsl{#1}}}
+\newcommand{\acronym}[1]{#1}
+\newcommand{\strong}[1]{\texorpdfstring%
+{{\normalfont\fontseries{b}\selectfont #1}}%
+{#1}}
+\let\pkg=\strong
+\RequirePackage{alltt}
+\newenvironment{example}{\begin{alltt}}{\end{alltt}}
+\newenvironment{smallexample}{\begin{alltt}\small}{\end{alltt}}
+\newenvironment{display}{\list{}{}\item\relax}{\endlist}
+\newenvironment{smallverbatim}{\small\verbatim}{\endverbatim}
+\RequirePackage{fancyvrb}
+\DefineVerbatimEnvironment{Sinput}{Verbatim}{fontsize=\small}
+\DefineVerbatimEnvironment{Soutput}{Verbatim}{fontsize=\small}
+\DefineVerbatimEnvironment{Scode}{Verbatim}{fontsize=\small}
+\DefineVerbatimEnvironment{Sin}{Verbatim}{fontsize=\small}
+\DefineVerbatimEnvironment{Sout}{Verbatim}{fontsize=\small}
+%\newenvironment{Schunk}{}{}
+\providecommand{\operatorname}[1]{%
+ \mathop{\operator at font#1}\nolimits}
+\renewcommand{\P}{%
+ \mathop{\operator at font I\hspace{-1.5pt}P\hspace{.13pt}}}
+\newcommand{\E}{%
+ \mathop{\operator at font I\hspace{-1.5pt}E\hspace{.13pt}}}
+\newcommand{\VAR}{\operatorname{var}}
+\newcommand{\COV}{\operatorname{cov}}
+\newcommand{\COR}{\operatorname{cor}}
+\RequirePackage{amsfonts}
+\endinput
+%%
+%% End of file `RJournal.sty'.
Added: pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw (rev 0)
+++ pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw 2010-03-07 16:34:35 UTC (rev 854)
@@ -0,0 +1,1022 @@
+\documentclass[a4paper]{report}
+%\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{RJournal}
+
+\RequirePackage{ae,mathpple} % ae as a default font pkg works with Sweave
+\RequirePackage[T1]{fontenc}
+
+\begin{document}
+
+\SweaveOpts{engine=R,eps=FALSE}
+
+%% do not edit, for illustration only
+\fancyhf{}
+\fancyhead[LO,RE]{\textsc{Submitted Article currently under Review}}
+\fancyhead[RO,LE]{\thepage}
+%\fancyfoot[L]{The R Journal Vol. X/Y, Month, Year}
+%\fancyfoot[R]{ISSN 2073-4859}
+
+\begin{article}
+ %\input{EddelbuettelFrancois} %% pull in EddelbuettelFrancois.tex
+
+\title{Rcpp: Seamless R and C++ integration}
+\author{by Dirk Eddelbuettel and Romain Fran\c{c}ois}
+
+\maketitle
+
+\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.}
+
+\section{Introduction}
+
+R is an extensible system. The `Writing R Extensions' manual \citep{R:exts}
+describes in detail how to augment R with compiled code,
+focussing 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.
+%
+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
+a short review of other approaches and give some historical
+background on the development of \pkg{Rcpp}.
+
+The current version of \pkg{Rcpp} combines two distinct
+APIs. The first---which we call `classic \pkg{Rcpp} API'---exists since
+the first version of \pkg{Rcpp}. The second API, enclosed in the
+\code{Rcpp} C++ namespace, is a newer codebase which we started to develop
+more recently. This article
+highlights some of the key design and implementation choices:
+lightweight encapsulation of R objects in C++ classes, automatic
+garbage collection strategy, code inlining, data interchange between
+R and 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
+the package, both as explicit examples and as part of the numerous unit tests.
+
+\subsection{Historical Context}
+
+\pkg{Rcpp} first appeared in 2005 as a contribution to the \pkg{RQuantLib}
+package \citep{eddelbuettelkhan09:rquantlib} before becoming a CRAN
+package in early 2006. Several releases followed in quick succession; all of
+these were under the name \pkg{Rcpp}. The package was then renamed to
+\pkg{RcppTemplate} and several more releases followed during 2006 under the
+new name. However, no new releases or updates were made during 2007, 2008
+and most of 2009.
+
+Given the continued use of the package, it was revitalized. New
+releases, using the initial name \pkg{Rcpp}, started in November 2008. These
+already included an improved build and distribution process, additional
+documentation, and new functionality---while retaining the existing
+interface. This constitutes the `classic \pkg{Rcpp}' interface (described in
+the next section) which will be maintained for the foreseeable future.
+
+Yet C++ coding standards continued to evolve \citep{meyers:effectivecplusplus}.
+So starting in 2009 the codebase was significantly extended and numerous new
+features were added. Several of these are described below in the section on
+the `new \pkg{Rcpp}' interface. This new API is our current focus, and we
+intend to both extend and support it going forward.
+
+\subsection{Comparison}
+
+Integration of C++ and R has been addressed by several authors; the earliest
+published reference is probably \cite{batesdebroy01:cppclasses}.
+An unpublished paper by \cite{javagailemanly07:r_cpp} expresses several ideas
+that are close to some of our approaches, though not yet fully fleshed out.
+%
+The \pkg{Rserve} package \citep{cran:Rserve} was another early approach,
+going back to 2002. 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.
+
+The packages \pkg{rcppbind} \citep{liang08:rcppbind}, \pkg{RAbstraction}
+\citep{armstrong09:RAbstraction} and \pkg{RObjects}
+\citep{armstrong09: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.
+%
+CXXR \citep{runnalls09:cxxr} comes to this topic from the other side:
+its aim is to completely refactor R on a stronger C++ foundation.
+CXXR is therefore concerned with all aspects of the R interpreter,
+REPL loop, threading---and object interchange between R and C++ is but one
+part. A similar approach is discussed by \cite{templelang09:modestproposal}
+who suggests making low-level internals extensible by package developers in
+order to facilitate extending \R.
+%
+Another slightly different angle is offered by
+\cite{templelang09:rgcctranslationunit} who uses compiler output for
+references on the code in order to add bindings and wrappers.
+%
+Lastly, the \pkg{RcppTemplate} package \citep{samperi09:rcpptemplate}
+recently introduced a few new ideas yet decided to break with the
+`classic \pkg{Rcpp}' API.
+
+A critical comparison of these packages that addresses relevant aspects such
+API features, performance, usability and documentation would be a welcome
+addition to the literature, but is beyond the scope of this article.
+
+\section{Classic Rcpp API}
+\label{sec:classic_rcpp}
+
+The core focus of \pkg{Rcpp}---particularly for the earlier API described in
+this section---has always been on allowing the programmer to add C++-based
+functions. We use this term 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 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 use.
+
+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
+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
+and parameters are passed via \pkg{Rcpp} to a function set-up to call code
+from an external library.
+
+An illustration can be provided using the time-tested example of a
+convolution of two vectors. This example is shown in sections 5.2 (for the
+\code{.C()} interface) and 5.9 (for the \code{.Call()} interface) of 'Writing
+R Extensions' \citep{R:exts}. We have rewritten it here using classes of the
+classic \pkg{Rcpp} API:
+
+\begin{example}
+#include <Rcpp.h>
+
+RcppExport SEXP convolve2cpp(SEXP a,SEXP b) \{
+ RcppVector<double> xa(a);
+ RcppVector<double> xb(b);
+ int nab = xa.size() + xb.size() - 1;
+
+ RcppVector<double> xab(nab);
+ for (int i = 0; i < nab; i++) xab(i) = 0.0;
+
+ for (int i = 0; i < xa.size(); i++)
+ for (int j = 0; j < xb.size(); j++)
+ xab(i + j) += xa(i) * xb(j);
+
+ RcppResultSet rs;
+ rs.add("ab", xab);
+ return rs.getReturnList();
+\}
+\end{example}
+
+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
+\code{SEXP} types, a third is returned.
+Third, both inputs are converted to templated\footnote{C++ templates
+allow functions or classes to be written somewhat independently from the
+template parameter. The actual class is instantiated by the compiler
+by replacing occurences of the templated parameter(s).}
+C++ vector types, here a standard \code{double}
+type is used to create a vector of doubles from the template type.
+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 whereas use based
+on C arrays would have required additional parameters for the length of
+vectors $a$ and $b$, leaving open the possibility of mismatches between the
+actual length and the length reported by the programmer.
+Fifth, the computation itself is straightforward embedded looping just as in the
+original examples in the 'Writing R Extensions' manual \citep{R:exts}.
+Sixth, a return type (\code{RcppResultSet}) is prepared as a named
+object which is then
+converted to a list object that is returned. We should note that the
+\code{RcppResultSet} supports the return of numerous (named) objects which can
+also be of different types.
+
+We argue that this usage is already much easier to read, write and debug than the
+C macro-based approach supported by R itself. Possible performance issues and
+other potential limitations will be discussed throughout the article and
+reviewed at the end.
+
+\section{New \pkg{Rcpp} API}
+\label{sec:new_rcpp}
+
+More recently, the \pkg{Rcpp} API has been dramatically extended, leading to a
+complete redesign, 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.
+This redesign of \code{Rcpp} was also motivated by the needs of other
+projects such as \code{RInside} \citep{cran:rinside} for easy embedding
+of R in a C++ applications and \code{RProtoBuf} \citep{cran:rprotobuf}
+that interfaces with the protocol buffers library.
+
+\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
+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, does not perform copies of the object into a suboptimal
+C++ representation, but instead 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.
+
+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
+its underlying \code{SEXP} as a resource.
+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.
+
+By assuming the entire responsibility of garbage collection, \code{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}) and
+handling of slots\footnote{The member functions that deal with slots
+are only applicable on 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
+predefined types, commonly referred to as SEXP types. R internals
+\citep{R:ints} documents these various types.
+\pkg{Rcpp} associates a dedicated C++ class for most SEXP types,
+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} 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 of the R API.
+
+\subsection{Numeric vectors}
+
+The following code snippet is taken from Writing R extensions
+\citep{R:exts}. It creates a \code{numeric} vector of two elements
+and assigns some values to it.
+
+\begin{example}
+SEXP ab;
+PROTECT(ab = allocVector(REALSXP, 2));
+REAL(ab)[0] = 123.45;
+REAL(ab)[1] = 67.89;
+UNPROTECT(1);
+\end{example}
+
+Although this is one of the simplest examples in Writing R extensions,
+it seems verbose and it is not obvious at first sight to understand 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\footnote{Since the garbage collection can be triggered at any time, not
+protecting an object means its memory might be reclaimed too soon.}.
+Lastly, the \code{REAL} macro returns a pointer to the
+beginning of the actual array; its indexing does not resemble either R or
+C++.
+
+Using the \code{Rcpp::NumericVector} class, the code can be rewritten:
+
+\begin{example}
+Rcpp::NumericVector ab(2) ;
+ab[0] = 123.45;
+ab[1] = 67.89;
+\end{example}
+
+The code contains fewer idiomatic decorations. The \code{NumericVector}
+constructor is given the number of elements the vector contains (2), this
+hides a call to the \code{allocVector} we saw previously. 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[]}.
+
+With the most recent compilers (e.g. GNU g++ >= 4.4) which already implement
+parts of the next C++ standard (C++0x) currently being drafted, the preceding
+code may even be reduced to this:
+
+\begin{example}
+Rcpp::NumericVector ab = \{123.45, 67.89\};
+\end{example}
+
+\subsection{Character vectors}
+
+A second example deals with character vectors and emulates this R code
+
+\begin{example}
+> c("foo", "bar")
+\end{example}
+
+Using the traditional R API, the vector can be allocated and filled as such:
+
+\begin{example}
+SEXP ab;
+PROTECT(ab = allocVector(STRSXP, 2));
+SET_STRING_ELT( ab, 0, mkChar("foo") );
+SET_STRING_ELT( ab, 1, mkChar("bar") );
+UNPROTECT(1);
+\end{example}
+
+This imposes on the programmer knowledge of \code{PROTECT}, \code{UNPROTECT},
+\code{SEXP}, \code{allocVector}, \code{SET\_STRING\_ELT}, \code{mkChar}.
+
+Using the \pkg{Rcpp::CharacterVector} class, we can express the same
+code more concisely:
+
+\begin{example}
+CharacterVector ab(2) ;
+ab[0] = "foo" ;
+ab[1] = "bar" ;
+\end{example}
+
+\section{R and C++ data interchange}
+
+In addition to classes, the \pkg{Rcpp} package contains two
+functions to perform conversion of C++ objects to R objects and back.
+
+\subsection{C++ to R : wrap}
+
+The C++ to R conversion is performed by the \code{Rcpp::wrap} templated
+function. It uses advanced template meta programming techniques\footnote{A
+ discussion of template meta programming 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 \code{wrap} template
+is:
+
+\begin{example}
+template <typename T>
+SEXP wrap(const T& object) ;
+\end{example}
+
+The templated function takes a reference to a `wrappable`
+object and converts this object into a \code{SEXP}, which is what R expects.
+Currently wrappable types are :
+\begin{itemize}
+\item primitive types, \code{int}, \code{double}, ... which are converted
+into the corresponding atomic R vectors;
+\item \code{std::string} which are converted to R atomic character vectors;
+\item STL containers such as \code{std::vector<T>} or \code{std::list<T>},
+as long as the template parameter type \code{T} is itself wrappable;
+\item STL maps which use \code{std::string} for keys
+(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()};
+\item any type for which the \code{wrap} template is partially or fully
+specialized.
+\end{itemize}
+One example for the specialisation of the templated \code{wrap} function is
+provided in \pkg{RInside} \citep{cran:rinside} by \code{vector< vector<
+ double > >} and \code{vector< vector< int > >} which are used for
+representing numeric matrices.
+
+Wrappability of an object type is resolved at compile time using
+modern techniques of template meta programming and class traits.
+
+The following code snippet illustrates that the design allows
+composition:
+
+\begin{example}
+std::vector< std::map<std::string,int> > v;
+std::map< std::string, int > m1;
+std::map< std::string, int > m2;
+
+m1["foo"] = 1; m1["bar"] = 2;
+m2["foo"] = 1; m2["bar"] = 2; m2["baz"] = 3;
+
+v.push_back( m1) ;
+v.push_back( m2) ;
+Rcpp::wrap( v ) ;
+\end{example}
+
+The code creates a list of two named vectors, equal to the
+result of this R statement:
+
+\begin{example}
+list( c( bar = 2L, foo = 1L) ,
+ c( bar = 2L, baz = 3L, foo = 1L) )
+\end{example}
+
+\subsection{R to C++ : as}
+
+The reversed conversion is implemented by variations of the
+\code{Rcpp::as} template. It offers less flexibility and currently
+handles conversion of R objects into primitive types (bool, int, std::string, ...),
+STL vectors of primitive types (\code{std::vector<bool>},
+\code{std::vector<double>}, etc ...) 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
+structures to third-party types.
+
+\subsection{Implicit use of converters}
+
+The converters offered by \code{wrap} and \code{as} provide a very
+useful framework to implement the logic of the code in terms of C++
+data structures and then explicitly convert data back to 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 C++ and R.
+
+\begin{example}
+# assuming the global environment contains
+# a variable 'x' that is a numeric vector
+Rcpp::Environment global =
+\ \ \ \ Rcpp::Environment::global_env()
+
+# extract a std::vector<double> from
+# the global environment
+std::vector<double> vx = global["x"] ;
+
+# create a map<string,string>
+std::map<std::string,std::string> map ;
+map["foo"] = "oof" ;
+map["bar"] = "rab" ;
+
+# push the STL map to R
+global["y"] = map ;
+\end{example}
+
+In the first part of the example, the code extracts a
+\code{std::vector<double>} from the global environment. This is
+achieved by the templated \code{operator[]} of \code{Environment}
+that first extracts the requested object from the environment as a \code{SEXP},
+and then outsources to \code{Rcpp::as} the creation of the
+requested type.
+
+In the second part of the example, the \code{operator[]}
+delegates to wrap the production of an R object based on the
+type that is passed in (\code{std::map<std::string,std::string>}),
+and then assigns the object to the requested name.
+
+The same mechanism is used throughout the API. Examples include access/modification
+of object attributes, slots, elements of generic vectors (lists),
+function arguments, nodes of dotted pair lists and language calls and more.
+
+\section{Function calls}
+
+\begin{table*}[t]
+ \begin{minipage}[t]{0.465\linewidth}
+ \centering{\underline{Environment: Using the \pkg{Rcpp} API}}
+ \begin{example}
+Environment stats("package:stats");
+Function rnorm = stats["rnorm"];
+return rnorm(10, Named("sd", 100.0));
+ \end{example}
+ \end{minipage}
+ \begin{minipage}{0.06\linewidth}
+ \phantom{XXX}
+ \end{minipage}
+ \begin{minipage}[t]{0.465\linewidth}
+ \centering{\underline{Environment: Using the R API}}
+ \begin{example}
+SEXP stats = PROTECT(
+\ \ R_FindNamespace( mkString("stats")));
+SEXP rnorm = PROTECT(
+\ \ findVarInFrame( stats, install("rnorm")));
+SEXP call = PROTECT(
+\ \ LCONS( rnorm,
+\ \ \ \ CONS(ScalarInteger(10),
+\ \ \ \ \ \ CONS(ScalarReal(100.0),R_NilValue))));
+SET_TAG( CDDR(call), install("sd") );
+SEXP res = PROTECT(eval(call, R_GlobalEnv));
+UNPROTECT(4) ;
+return res ;
+ \end{example}
+ \end{minipage}
+
+
+ \begin{minipage}[t]{0.465\linewidth}
+ \centering{\underline{Language: Using the \pkg{Rcpp} API}}
+ \begin{example}
+Language call("rnorm",10,Named("sd",100.0));
+return call.eval();
+ \end{example}
+ \end{minipage}
+ \begin{minipage}{0.06\linewidth}
+ \phantom{XXX}
+ \end{minipage}
+ \begin{minipage}[t]{0.465\linewidth}
+ \centering{\underline{Language: Using the R API}}
+ \begin{example}
+SEXP call = PROTECT(
+\ \ LCONS( install("rnorm"),
+\ \ \ \ CONS(ScalarInteger(10),
+\ \ \ \ \ \ CONS(ScalarReal(100.0),R_NilValue))));
+SET_TAG( CDDR(call), install("sd") ) ;
+SEXP res = PROTECT(eval(call, R_GlobalEnv));
+UNPROTECT(2) ;
+return res ;
+ \end{example}
+ \end{minipage}
+ \caption{\pkg{Rcpp} versus the R API: Four ways of calling \code{rnorm(10L, sd=100)} in C / C++.
+ We have removed the \code{Rcpp::} prefix from the
+ examples for readability; this corresponds to adding a statement
+ \texttt{using namespace Rcpp;} in the code}
+ \label{fig:rnormCode}
+\end{table*}
+
+The next example shows how to use \pkg{Rcpp} to emulate the R code
+\code{rnorm(10L, sd=100.0)}.
+%
+As shown in table~\ref{fig:rnormCode}, the code can be expressed in several
+ways in either \pkg{Rcpp} or the standard R API. The first version shows the
+use of the \code{Environment} and \code{Function} classes by
+\pkg{Rcpp}.
+The second version shows the use of the \code{Language} class, which
+manage calls (LANGSXP).
+For comparison, we also show both versions using the standard R API.
+
+This example illustrates that the \pkg{Rcpp} API permits us to work with code
+that is easier to read, write and maintain. More examples are available as
+part of the documentation included in the \pkg{Rcpp} package, as well as
+among its over one hundred and ninety unit tests.
+
+
+\section{Using code `inline'}
+\label{sec:inline}
+
+Extending R with compiled code also needs to address how to reliably compile,
+link and load the code. While using a package is preferable in the long run,
+it may be too involved for for quick explorations. An alternative is
+provided by the \pkg{inline} package \citep{cran:inline} which compiles,
+links and loads a C, C++ or Fortran function---directly from the R prompt
+using a simple function \code{cfunction}. It was recently extended to work
+with \pkg{Rcpp} by allowing for the use of additional header files and
+libraries. This works particularly well with the \pkg{Rcpp} package where
+headers and the library are automatically found if the appropriate option
+\code{Rcpp} to \texttt{cfunction} is set to \code{TRUE}.
+
+The use of \pkg{inline} is possible as \pkg{Rcpp} can be installed and
+updated just like any other R package using \textsl{e.g.} the
+\code{install.packages()} function for initial installation as well as
+\code{update.packages()} for upgrades. So even though R / C++ interfacing
+would otherwise require source code, the \pkg{Rcpp} library is always provided
+ready for use as a pre-built library through the CRAN package
+mechanism.\footnote{This presumes a platform for which pre-built binaries are
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/rcpp -r 854
More information about the Rcpp-commits
mailing list