[Rcpp-commits] r2248 - in pkg/Rcpp/inst/doc: . Rcpp-FAQ Rcpp-extending Rcpp-modules Rcpp-package Rcpp-sugar
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Sep 29 19:29:20 CEST 2010
Author: edd
Date: 2010-09-29 19:29:20 +0200 (Wed, 29 Sep 2010)
New Revision: 2248
Modified:
pkg/Rcpp/inst/doc/Rcpp-FAQ.Rnw
pkg/Rcpp/inst/doc/Rcpp-FAQ/Rcpp-FAQ.Rnw
pkg/Rcpp/inst/doc/Rcpp-extending.Rnw
pkg/Rcpp/inst/doc/Rcpp-extending/Rcpp-extending.Rnw
pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw
pkg/Rcpp/inst/doc/Rcpp-modules.Rnw
pkg/Rcpp/inst/doc/Rcpp-modules/Rcpp-modules.Rnw
pkg/Rcpp/inst/doc/Rcpp-package.Rnw
pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw
pkg/Rcpp/inst/doc/Rcpp-sugar.Rnw
pkg/Rcpp/inst/doc/Rcpp-sugar/Rcpp-sugar.Rnw
pkg/Rcpp/inst/doc/Rcpp.bib
Log:
The grand bibtex / citation clean-up Vol 3: updates all vignettes -- all good now
Modified: pkg/Rcpp/inst/doc/Rcpp-FAQ/Rcpp-FAQ.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-FAQ/Rcpp-FAQ.Rnw 2010-09-29 16:57:53 UTC (rev 2247)
+++ pkg/Rcpp/inst/doc/Rcpp-FAQ/Rcpp-FAQ.Rnw 2010-09-29 17:29:20 UTC (rev 2248)
@@ -106,7 +106,7 @@
\pkg{Rcpp} has been specifically designed to be used by other packages.
Making a package that uses \pkg{Rcpp} depends on the same mechanics that are
involved in making any \proglang{R} package that use compiled code --- so
-reading the \textsl{Writing R Extensions} manual \citep{R:exts} is a required
+reading the \textsl{Writing R Extensions} manual \citep{R:Extensions} is a required
first step.
Further steps, specific to \pkg{Rcpp}, are described in a separate vignette.
@@ -254,8 +254,8 @@
templates. We currently do not plan to go in this direction, but we would
welcome external help. Please send us a design document.
-However, we have developed the \pkg{RcppArmadillo} package that provides a
-bridge between \pkg{Rcpp} and \pkg{Armadillo} \citep{Armadillo}. \pkg{Armadillo}
+However, we have developed the \pkg{RcppArmadillo} package \citep{CRAN:RcppArmadillo} that provides a
+bridge between \pkg{Rcpp} and \pkg{Armadillo} \citep{Sanderson:2010:Armadillo}. \pkg{Armadillo}
supports binary operators on its types in a way that takes full advantage of
expression templates to remove temporaries and allow chaining of
operations. That is a mouthful of words meaning that it makes the code go
Modified: pkg/Rcpp/inst/doc/Rcpp-FAQ.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-FAQ.Rnw 2010-09-29 16:57:53 UTC (rev 2247)
+++ pkg/Rcpp/inst/doc/Rcpp-FAQ.Rnw 2010-09-29 17:29:20 UTC (rev 2248)
@@ -1,4 +1,369 @@
\documentclass[10pt]{article}
%\VignetteIndexEntry{Rcpp-FAQ}
+\usepackage{vmargin}
+\setmargrb{0.75in}{0.75in}{0.75in}{0.75in}
+
+\usepackage{color, alltt}
+\usepackage[authoryear,round,longnamesfirst]{natbib}
+\usepackage[colorlinks]{hyperref}
+\definecolor{link}{rgb}{0,0,0.3} %% next few lines courtesy of RJournal.sty
+\hypersetup{
+ colorlinks,%
+ citecolor=link,%
+ filecolor=link,%
+ linkcolor=link,%
+ urlcolor=link
+}
+
+\newcommand{\proglang}[1]{\textsf{#1}}
+\newcommand{\pkg}[1]{{\fontseries{b}\selectfont #1}}
+
+%% defined as a stop-gap measure til interaction with highlight is sorted out
+\newcommand{\hlboxlessthan}{ \hlnormalsizeboxlessthan}
+\newcommand{\hlboxgreaterthan}{\hlnormalsizeboxgreaterthan}
+\newcommand{\hlboxopenbrace}{ \hlnormalsizeboxopenbrace}
+\newcommand{\hlboxclosebrace}{ \hlnormalsizeboxclosebrace}
+\newcommand{\hlboxbacktick}{ \hlnormalsizeboxbacktick}
+\newcommand{\hlboxunderscore}{ \hlnormalsizeboxunderscore}
+
+\author{Dirk Eddelbuettel \and Romain Fran\c{c}ois}
+\title{Frequently Asked Questions about \pkg{Rcpp}}
+
+<<echo=FALSE>>=
+link <- function( f, package, text = f, root = "http://finzi.psych.upenn.edu/R/library/" ){
+ h <- if( missing(package) ) {
+ as.character( help( f ) )
+ } else {
+ as.character( help( f, package = paste( package, sep = "" ) ) )
+ }
+ if( ! length(h) ){
+ sprintf( "\\\\textbf{%s}", f )
+ } else {
+ rx <- "^.*/([^/]*?)/help/(.*?)$"
+ package <- sub( rx, "\\1", h, perl = TRUE )
+ page <- sub( rx, "\\2", h, perl = TRUE )
+ sprintf( "\\\\href{%s%s/html/%s.html}{\\\\texttt{%s}}", root, package, page, text )
+ }
+}
+linkS4class <- function( cl, package, text = cl, root = "http://finzi.psych.upenn.edu/R/library/" ){
+ link( sprintf("%s-class", cl), package, text, root )
+}
+require(inline)
+# this will be integrated to package highlight later
+ex_highlight <- function( file, external.highlight = TRUE, verbatim = FALSE ){
+ if( verbatim ){
+ writeLines( "\\begin{verbatim}" )
+ writeLines( readLines( file ) )
+ writeLines( "\\end{verbatim}" )
+ } else {
+ tf <- tempfile()
+ if( external.highlight ){
+ cmd <- sprintf( 'highlight --input="%s" --output="%s" -L --pretty-symbols', file, tf )
+ tryCatch( {
+ system( cmd )
+ tex <- readLines( tf )
+ keep <- seq( which( tex == "\\noindent" ), which( tex == "\\normalfont" ) )
+ tex <- c(
+ "\\vspace{1em}\\noindent\\fbox{\\begin{minipage}{0.9\\textwidth}" ,
+ tex[ keep ],
+ "\\end{minipage}}\\vspace{1em}" )
+ writeLines( tex )
+ })
+ } else {
+ r = renderer_latex( minipage = TRUE, doc = FALSE )
+ tex <- highlight( file, renderer = r , output = NULL )
+ writeLines( tex )
+ }
+ }
+ invisible(NULL)
+}
+
+@
+
+\newcommand{\faq}[1]{\textbf{FAQ~\ref{#1}}}
+
\begin{document}
+\maketitle
+
+\abstract{
+ \noindent This document attempts to answer the most Frequently Asked
+ Questions (FAQ) regarding the \pkg{Rcpp} \citep{CRAN:Rcpp} package.
+}
+
+\section{Getting started}
+
+\subsection{How do I get started ?}
+
+<<eval=FALSE>>=
+vignette( "Rcpp-introduction" )
+@
+
+\section{Compiling and Linking}
+
+\subsection{How do I use \pkg{Rcpp} in my package ?}
+\label{make-package}
+
+\pkg{Rcpp} has been specifically designed to be used by other packages.
+Making a package that uses \pkg{Rcpp} depends on the same mechanics that are
+involved in making any \proglang{R} package that use compiled code --- so
+reading the \textsl{Writing R Extensions} manual \citep{R:Extensions} is a required
+first step.
+
+Further steps, specific to \pkg{Rcpp}, are described in a separate vignette.
+
+<<eval=FALSE>>=
+vignette( "Rcpp-package" )
+@
+
+\subsection{How do I quickly prototype my code ?}
+\label{using-inline}
+
+The \pkg{inline} package \citep{CRAN:inline} provides the functions
+\Sexpr{link("cfunction")} and \Sexpr{link("cxxfunction")}. Below is a simple
+function that uses \texttt{accumulate} from the (\proglang{C++}) Standard
+Template Library to sum the elements of a numeric vector.
+
+<<>>=
+fx <- cxxfunction( signature( x = "numeric" ),
+' NumericVector xx(x); return wrap( std::accumulate( xx.begin(), xx.end(), 0.0 ) ) ; '
+, plugin = "Rcpp"
+ )
+res <- fx( seq( 1, 10, by = 0.5 ) )
+res
+<<echo=FALSE>>=
+stopifnot( identical( res, sum( seq( 1, 10, by = 0.5 ) ) ) )
+@
+
+\pkg{Rcpp} uses \pkg{inline} to power its entire unit test suite. Consult the
+\texttt{unitTests} directory of \pkg{Rcpp} for over five hundred further examples.
+
+<<eval=FALSE>>=
+list.files( system.file( "unitTests", package = "Rcpp" ), pattern = "^runit[.]" )
+@
+
+One might want to use code that lives in a \proglang{C++} file instead of writing
+the code in a character string in R. This is easily achieved by using
+\Sexpr{link("readLines")} :
+
+<<eval=FALSE>>=
+fx <- cxxfunction( signature(),
+ paste( readLines( "myfile.cpp"), collapse = "\n" ),
+ plugin = "Rcpp" )
+@
+
+The \texttt{verbose} argument of \Sexpr{link("cxxfunction")} is very
+useful as it shows how \pkg{inline} runs the show.
+
+\subsection{How do I convert my prototyped code to a package?}
+\label{from-inline-to-package}
+
+Since release 0.3.5 of \pkg{inline}, one can combine \faq{using-inline} and
+\faq{make-package}. See \verb|help("package.skeleton-methods")| once
+\pkg{inline} is loaded and use the skeleton-generating functionality to
+transform a prototyped function into the minimal structure of a package.
+After that you can proceed with working on the package in the spirit of
+\faq{make-package}.
+
+\subsection{But I want to compile my code with R CMD SHLIB}
+
+The recommended way is to create a package and follow \faq{make-package}. The
+alternate recommendation is to use \pkg{inline} and follow \faq{using-inline}
+because it takes care of all the details.
+
+However, some people have shown that they prefer not to follow recommended
+guidelines and compile their code using the traditional \texttt{R CMD SHLIB}. To
+do this, we need to help \texttt{SHLIB} and let it know about the header files
+that \pkg{Rcpp} provides and the \proglang{C++} library the code must link
+against.
+
+<<lang=bash>>=
+$ export PKG_LIBS=`Rscript -e "Rcpp:::LdFlags()"`
+$ export PKG_CXXFLAGS=`Rscript -e "Rcpp:::CxxFlags()"`
+$ R CMD SHLIB myfile.cpp
+@
+
+This approach corresponds to the very earliest ways of building programs and
+can still be found in some deprecated documents (as \textit{e.g.} some of
+Dirk's older 'Intro to HPC with R' tutorial slides). It is still not
+recommended as there are tools and automation mechanisms that can do the work
+for you.
+
+
+\subsection{What about \texttt{LinkingTo} ?}
+
+\proglang{R} has only limited support for cross-package linkage.
+
+We now employ the \texttt{LinkingTo} field of the \texttt{DESCRIPTION} file
+of packages using \pkg{Rcpp}. But this only helps in having \proglang{R}
+compute the location of the header files for us.
+
+The actual library location and argument still needs to be provided by the
+user. How to do so has been shown above, and we recommned you use either
+\faq{make-package} or \faq{using-inline} both which use the \pkg{Rcpp}
+function \texttt{Rcpp:::LdFlags()}.
+
+If and when \texttt{LinkingTo} changes and lives up to its name, we will be
+sure to adapt \pkg{Rcpp} as well.
+
+\subsection{Does \pkg{Rcpp} work on windows}
+
+Yes of course. See the Windows binaries provided by CRAN.
+
+
+\subsection{Can I use \pkg{Rcpp} with Visual Studio}
+
+Not a chance.
+
+And that is not because we are meanies but because \proglang{R} and Visual
+Studio simply do not get along. As \pkg{Rcpp} is all about extending
+\proglang{R} with \proglang{C++} interfaces, we are bound by the available
+toolchain. And \proglang{R} simply does not compile with Visual Studio. Go
+complain to its vendor if you are still upset.
+
+\subsection{Does \pkg{Rcpp} work on solaris/suncc}
+
+Yes.
+
+\subsection{Does \pkg{Rcpp} work with Revolution R}
+
+We have not tested it yet. \pkg{Rcpp} might need a few tweaks to work
+with the compilers used by Revolution R.
+
+\subsection{Is it related to CXXR}
+
+CXXR is an ambitious project that aims to totally refactor the \proglang{R}
+interpreter in \proglang{C++}. There are a few similaritites with \pkg{Rcpp}
+but the projects are unrelated.
+
+CXXR and \pkg{Rcpp} both want \proglang{R} to make more use of \proglang{C++}
+but they do it in very different ways.
+
+\section{API}
+
+\subsection{Can I do matrix algebra with \pkg{Rcpp} ? }
+
+\begin{quote}
+ \emph{\pkg{Rcpp} allows element-wise operations on vector and matrices through
+ operator overloading and STL interface, but what if I want to multiply a
+ matrix by a vector, etc ...}
+\end{quote}
+
+\noindent Currently, \pkg{Rcpp} does not provide binary operators to allow operations
+involving entire objects. Adding operators to \pkg{Rcpp} would be a major
+project (if done right) involving advanced techniques such as expression
+templates. We currently do not plan to go in this direction, but we would
+welcome external help. Please send us a design document.
+
+However, we have developed the \pkg{RcppArmadillo} package \citep{CRAN:RcppArmadillo} that provides a
+bridge between \pkg{Rcpp} and \pkg{Armadillo} \citep{Sanderson:2010:Armadillo}. \pkg{Armadillo}
+supports binary operators on its types in a way that takes full advantage of
+expression templates to remove temporaries and allow chaining of
+operations. That is a mouthful of words meaning that it makes the code go
+faster by using fiendishly clever ways available via the so-called template
+meta programming, an advanced \proglang{C++} technique.
+
+The following example is adapted from the examples available at the project
+page of Armadillo. It calculate $ x' \times Y^{-1} \times z$
+
+<<echo=FALSE>>=
+writeLines( '
+ // copy the data to armadillo structures
+ arma::colvec x = Rcpp::as<arma::colvec> (x_);
+ arma::mat Y = Rcpp::as<arma::mat>( Y_ ) ;
+ arma::colvec z = Rcpp::as<arma::colvec>( z_ ) ;
+
+ // calculate the result
+ double result = arma::as_scalar(
+ arma::trans(x) * arma::inv(Y) * z
+ );
+
+ // return it to R
+ return Rcpp::wrap( result );
+', "myfile.cpp" )
+@
+<<echo=FALSE,results=tex>>=
+ex_highlight( "myfile.cpp" )
+@
+
+<<>>=
+fx <- cxxfunction(
+ signature(x_ = "numeric", Y_ = "matrix", z_ = "numeric" ),
+ paste( readLines( "myfile.cpp" ), collapse = "\n" ),
+ plugin = "RcppArmadillo" )
+fx( 1:4, diag( 4 ), 1:4 )
+@
+<<echo=FALSE>>=
+unlink( "myfile.cpp" )
+@
+
+The focus is on the code \verb|arma::trans(x) * arma::inv(Y) * z|, which
+performs the same operation as the R code \verb|t(x) %*% solve(Y) %*% z|,
+although Armadillo turns it into only one operation, which makes it quite fast.
+Armadillo benchmarks against other \proglang{C++} matrix algebra libraries
+are provided on \href{http://arma.sourceforge.net/speed.html}{the Armadillo website}.
+
+It should be noted that code below depends on the version \texttt{0.3.5} of
+\pkg{inline} and the version \texttt{0.2.2} of \pkg{RcppArmadillo}
+
+\subsection{Is the API documented ? }
+
+You bet. We use \proglang{doxygen} to generate html, latex and man page
+documentation from the source. The html documentation is available for
+\href{http://dirk.eddelbuettel.com/code/rcpp/html/index.html}{browsing}, as a
+\href{http://dirk.eddelbuettel.com/code/rcpp/Rcpp_refman.pdf}{very large pdf file},
+and all three formats are also available a zip-archives:
+\href{http://dirk.eddelbuettel.com/code/rcpp/rcpp-doc-html.zip}{html},
+\href{http://dirk.eddelbuettel.com/code/rcpp/rcpp-doc-latex.zip}{latex}, and
+\href{http://dirk.eddelbuettel.com/code/rcpp/rcpp-doc-man.zip}{man}.
+
+\subsection{Does it really work ?}
+
+We take quality seriously and have developped an extensive unit test suite to
+cover many possible uses of the \pkg{Rcpp} API.
+
+We are always on the look for more coverage in our testing. Please let us know
+if something has not been tested enough.
+
+\section{Support}
+
+\subsection{Where can I ask further questions ?}
+
+The
+\href{https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/rcpp-devel}{Rcpp-devel}
+mailing list hosted at R-forge is by far the best place. You may also want
+to look at the list archives to see if your question has been asked before.
+
+\subsection{I like it. How can I help ?}
+\label{helping}
+
+The current list of things to do is available in our \texttt{TODO} file.
+\href{https://r-forge.r-project.org/scm/viewvc.php/pkg/Rcpp/TODO?view=markup&root=rcpp}.
+If you are willing to donate time and have skills in C++, let us know. If you are
+willing to donate money to sponsor improvements, let us know.
+
+You can also spread the word about \pkg{Rcpp}. There are many packages on CRAN
+that use \proglang{C++}, yet are not using \pkg{Rcpp}. You could write a
+review of \pkg{Rcpp} in \href{http://crantastic.org}{crantastic}, blog about
+it or get the word out otherwise.
+
+
+\subsection{I don't like it. How can I help ?}
+
+It is very generous of you to still want to help. Perhaps you can tell us
+what it is that you dislike. We are very open to \emph{constructive} criticism.
+
+\subsection{Can I have commercial support for \pkg{Rcpp} ?}
+
+Sure you can. Just send us an email, and we will be happy to discuss the
+request..
+
+\subsection{I want to learn quickly. Do you provide training courses.}
+
+Yes. Just send us an email.
+
+
+\bibliographystyle{abbrvnat}
+\bibliography{Rcpp}
+
\end{document}
+
Modified: pkg/Rcpp/inst/doc/Rcpp-extending/Rcpp-extending.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-extending/Rcpp-extending.Rnw 2010-09-29 16:57:53 UTC (rev 2247)
+++ pkg/Rcpp/inst/doc/Rcpp-extending/Rcpp-extending.Rnw 2010-09-29 17:29:20 UTC (rev 2248)
@@ -89,10 +89,10 @@
This note provides an overview of the steps programmers should follow to
extend \pkg{Rcpp} \citep{CRAN:Rcpp} for use with their own classes. This document
is based on our experience in extending \pkg{Rcpp} to work with the
- \pkg{Armadillo} \citep{Armadillo} classes, available in the separate package
+ \pkg{Armadillo} \citep{Sanderson:2010:Armadillo} classes, available in the separate package
\pkg{RcppArmadillo} \citep{CRAN:RcppArmadillo}. This document assumes
knowledge of \pkg{Rcpp} as well as some knowledge of \proglang{C++}
- templates \citep{Abrahams+Gurtovoy:2004}.
+ templates \citep{Abrahams+Gurtovoy:2004:TemplateMetaprogramming}.
}
Modified: pkg/Rcpp/inst/doc/Rcpp-extending.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-extending.Rnw 2010-09-29 16:57:53 UTC (rev 2247)
+++ pkg/Rcpp/inst/doc/Rcpp-extending.Rnw 2010-09-29 17:29:20 UTC (rev 2248)
@@ -1,4 +1,369 @@
\documentclass[10pt]{article}
%\VignetteIndexEntry{Rcpp-extending}
+\usepackage{vmargin}
+\setmargrb{0.75in}{0.75in}{0.75in}{0.75in}
+
+\usepackage{color, alltt}
+\usepackage[authoryear,round,longnamesfirst]{natbib}
+\usepackage[colorlinks]{hyperref}
+\definecolor{link}{rgb}{0,0,0.3} %% next few lines courtesy of RJournal.sty
+\hypersetup{
+ colorlinks,%
+ citecolor=link,%
+ filecolor=link,%
+ linkcolor=link,%
+ urlcolor=link
+}
+
+\newcommand{\proglang}[1]{\textsf{#1}}
+\newcommand{\pkg}[1]{{\fontseries{b}\selectfont #1}}
+
+%% defined as a stop-gap measure til interaction with highlight is sorted out
+\newcommand{\hlboxlessthan}{ \hlnormalsizeboxlessthan}
+\newcommand{\hlboxgreaterthan}{\hlnormalsizeboxgreaterthan}
+\newcommand{\hlboxopenbrace}{ \hlnormalsizeboxopenbrace}
+\newcommand{\hlboxclosebrace}{ \hlnormalsizeboxclosebrace}
+\newcommand{\hlboxbacktick}{ \hlnormalsizeboxbacktick}
+\newcommand{\hlboxunderscore}{ \hlnormalsizeboxunderscore}
+
+\author{Dirk Eddelbuettel \and Romain Fran\c{c}ois}
+\title{Extending \pkg{Rcpp}}
+
+<<echo=FALSE>>=
+link <- function( f, package, text = f, root = "http://finzi.psych.upenn.edu/R/library/" ){
+ h <- if( missing(package) ) {
+ as.character( help( f ) )
+ } else {
+ as.character( help( f, package = paste( package, sep = "" ) ) )
+ }
+ if( ! length(h) ){
+ sprintf( "\\\\textbf{%s}", f )
+ } else {
+ rx <- "^.*/([^/]*?)/help/(.*?)$"
+ package <- sub( rx, "\\1", h, perl = TRUE )
+ page <- sub( rx, "\\2", h, perl = TRUE )
+ sprintf( "\\\\href{%s%s/html/%s.html}{\\\\texttt{%s}}", root, package, page, text )
+ }
+}
+linkS4class <- function( cl, package, text = cl, root = "http://finzi.psych.upenn.edu/R/library/" ){
+ link( sprintf("%s-class", cl), package, text, root )
+}
+# this will be integrated to package highlight later
+ex_highlight <- function( file, external.highlight = TRUE, verbatim = FALSE ){
+ if( verbatim ){
+ writeLines( "\\begin{verbatim}" )
+ writeLines( readLines( file ) )
+ writeLines( "\\end{verbatim}" )
+ } else {
+ tf <- tempfile()
+ if( external.highlight ){
+ cmd <- sprintf( 'highlight --input="%s" --output="%s" -L --pretty-symbols', file, tf )
+ tryCatch( {
+ system( cmd )
+ tex <- readLines( tf )
+ keep <- seq( which( tex == "\\noindent" ), which( tex == "\\normalfont" ) )
+ tex <- c(
+ "\\vspace{1em}\\noindent\\fbox{\\begin{minipage}{0.9\\textwidth}" ,
+ tex[ keep ],
+ "\\end{minipage}}\\vspace{1em}" )
+ writeLines( tex )
+ })
+ } else {
+ r = renderer_latex( minipage = TRUE, doc = FALSE )
+ tex <- highlight( file, renderer = r , output = NULL )
+ writeLines( tex )
+ }
+ }
+ invisible(NULL)
+}
+
+require( inline )
+require( Rcpp )
+@
+
\begin{document}
+\maketitle
+
+\abstract{
+ \noindent
+ This note provides an overview of the steps programmers should follow to
+ extend \pkg{Rcpp} \citep{CRAN:Rcpp} for use with their own classes. This document
+ is based on our experience in extending \pkg{Rcpp} to work with the
+ \pkg{Armadillo} \citep{Sanderson:2010:Armadillo} classes, available in the separate package
+ \pkg{RcppArmadillo} \citep{CRAN:RcppArmadillo}. This document assumes
+ knowledge of \pkg{Rcpp} as well as some knowledge of \proglang{C++}
+ templates \citep{Abrahams+Gurtovoy:2004:TemplateMetaprogramming}.
+}
+
+
+\section{Introduction}
+
+\pkg{Rcpp} facilitates data interchange between \proglang{R} and
+\proglang{C++} through the templated functions \texttt{Rcpp::as} (for
+conversion of objects from \proglang{R} to \proglang{C++}) and
+\texttt{Rcpp::wrap} (for conversion from \proglang{C++} to \proglang{R}). In
+other words, we convert between the so-called \proglang{S}-expression
+pointers (in type \texttt{SEXP}) to a templated \proglang{C++} type, and vice
+versa. The corresponding function declarations are as follows:
+
+<<lang=cpp>>=
+// conversion from R to C++
+template <typename T> T as( SEXP m_sexp) throw(not_compatible) ;
+
+// conversion from C++ to R
+template <typename T> SEXP wrap(const T& object) ;
+@
+
+These converters are often used implicitly, as in the following code chunk:
+
+<<echo=FALSE>>=
+code <- '
+// we get a list from R
+List input(input_) ;
+
+// pull std::vector<double> from R list
+// this is achieved through an implicit call to Rcpp::as
+std::vector<double> x = input["x"] ;
+
+// return an R list
+// this is achieved through implicit call to Rcpp::wrap
+return List::create(
+ _["front"] = x.front(),
+ _["back"] = x.back()
+ ) ;
+'
+writeLines( code, "code.cpp" )
+@
+<<echo=FALSE,results=tex>>=
+ex_highlight( "code.cpp" )
+@
+
+<<>>=
+fx <- cxxfunction( signature( input_ = "list"),
+ paste( readLines( "code.cpp" ), collapse = "\n" ),
+ plugin = "Rcpp"
+ )
+input <- list( x = seq(1, 10, by = 0.5) )
+fx( input )
+@
+
+The \pkg{Rcpp} converter function \texttt{Rcpp::as} and \texttt{Rcpp::wrap} have been
+designed to be extensible to user-defined types and third-party types.
+
+\section[Extending Rcpp::wrap]{Extending \texttt{Rcpp::wrap} }
+
+The \pkg{Rcpp::wrap} converter is extensible in essentially two ways : intrusive
+and non-intrusive.
+
+\subsection{Intrusive extension}
+
+When extending \pkg{Rcpp} with your own data type, the recommended way is to
+implement a conversion to \texttt{SEXP}. This lets \texttt{Rcpp::wrap} know
+about the new data type. The template meta programming (or TMP) dispatch is able to
+recognize that a type is convertible to a \texttt{SEXP} and
+\texttt{Rcpp::wrap} will use that conversion.
+
+The caveat is that the type must be declared before the main header
+file \texttt{Rcpp.h} is included.
+
+<<lang=cpp>>=
+#include <RcppCommon.h>
+
+class Foo {
+ public:
+ Foo() ;
+
+ // this operator enables implicit Rcpp::wrap
+ operator SEXP() ;
+}
+
+#include <Rcpp.h>
+@
+
+This is called \emph{intrusive} because the conversion to \texttt{SEXP}
+operator has to be declared within the class.
+
+\subsection{Non-intrusive extension}
+
+It is often desirable to offer automatic conversion to third-party types, over
+which the developer has no control and can therefore not include a conversion
+to \texttt{SEXP} operator in the class definition.
+
+To provide automatic conversion from \proglang{C++} to \proglang{R}, one must
+declare a specialization of the \texttt{Rcpp::wrap} template between the
+includes of \texttt{RcppCommon.h} and \texttt{Rcpp.h}.
+
+<<lang=cpp>>=
+#include <RcppCommon.h>
+
+// third party library that declares class Bar
+#include <foobar.h>
+
+// declaring the specialization
+namespace Rcpp {
+ template <> SEXP wrap( const Bar& ) ;
+}
+
+// this must appear after the specialization,
+// otherwise the specialization will not be seen by Rcpp types
+#include <Rcpp.h>
+@
+
+It should be noted that only the declaration is required. The implementation
+can appear after the \texttt{Rcpp.h} file is included, and therefore take
+full advantage of the \pkg{Rcpp} type system.
+
+\subsection{Templates and partial specialization}
+
+It is perfectly valid to declare a partial specialization for the
+\texttt{Rcpp::wrap} template. The compiler will identify the appropriate
+overload:
+
+<<lang=cpp>>=
+#include <RcppCommon.h>
+
+// third party library that declares template class Bling<T>
+#include <foobar.h>
+
+// declaring the partial specialization
+namespace Rcpp {
+ namespace traits {
+
+ template <typename T> SEXP wrap( const Bling<T>& ) ;
+
+ }
+}
+
+// this must appear after the specialization,
+// otherwise the specialization will not be seen by Rcpp types
+#include <Rcpp.h>
+
+@
+
+
+\section[Extending Rcpp::as]{Extending \texttt{Rcpp::as}}
+
+Conversion from \proglang{R} to \proglang{C++} is also possible
+in both intrusive and non-intrusive ways.
+
+\subsection{Intrusive extension}
+
+As part of its template meta programming dispatch logic, \pkg{Rcpp::as}
+will attempt to use the constructor of the target class taking a \texttt{SEXP}.
+
+<<lang=cpp>>=
+#include <RcppCommon.h>
+
+#include <RcppCommon.h>
+
+class Foo{
+ public:
+ Foo() ;
+
+ // this constructor enables implicit Rcpp::as
+ Foo(SEXP) ;
+}
+
+#include <Rcpp.h>
+
+
+// this must appear after the specialization,
+// otherwise the specialization will not be seen by Rcpp types
+#include <Rcpp.h>
+@
+
+\subsection{Non intrusive extension}
+
+It is also possible to fully specialize \texttt{Rcpp::as} to enable
+non intrusive implicit conversion capabilities.
+
+<<lang=cpp>>=
+#include <RcppCommon.h>
+
+// third party library that declares class Bar
+#include <foobar.h>
+
+// declaring the specialization
+namespace Rcpp {
+ template <> Bar as( SEXP ) throw(not_compatible) ;
+}
+
+// this must appear after the specialization,
+// otherwise the specialization will not be seen by Rcpp types
+#include <Rcpp.h>
+@
+
+\subsection{Templates and partial specialization}
+
+The signature of \texttt{Rcpp::as} does not allow partial specialization.
+When exposing a templated class to \texttt{Rcpp::as}, the programmer must
+specialize the \pkg{Rcpp::traits::Exporter} template class. The TMP dispatch
+will recognize that a specialization of \texttt{Exporter} is available
+and delegate the conversion to this class. \pkg{Rcpp} defines
+the \texttt{Rcpp::traits::Exporter} template class as follows :
+
+<<lang=cpp>>=
+namespace Rcpp {
+ namespace traits {
+
+ template <typename T> class Exporter{
+ public:
+ Exporter( SEXP x ) : t(x){}
+ inline T get(){ return t ; }
+
+ private:
+ T t ;
+ } ;
+ }
+}
+@
+
+This is the reason why the default behavior of \texttt{Rcpp::as} is to
+invoke the constructor of the type \texttt{T} taking a \texttt{SEXP}.
+
+Since partial specialization of class templates is allowed, we can expose
+a set of classes as follows:
+
+<<lang=cpp>>=
+#include <RcppCommon.h>
+
+// third party library that declares template class Bling<T>
+#include <foobar.h>
+
+// declaring the partial specialization
+namespace Rcpp {
+ namespace traits {
+ template <typename T> class Exporter< Bling<T> >;
+ }
+}
+
+// this must appear after the specialization,
+// otherwise the specialization will not be seen by Rcpp types
+#include <Rcpp.h>
+@
+
+Using this approach, the requirements for the \texttt{Exporter< Bling<T> >}
+class are:
+\begin{itemize}
+\item it should have a constructor taking a \texttt{SEXP}
+\item it should have a methods called \texttt{get} that returns an instance
+of the \texttt{Bling<T>} type.
+\end{itemize}
+
+<<echo=FALSE>>=
+unlink( "code.cpp" )
+@
+
+\section{Summary}
+
+The \pkg{Rcpp} package greatly facilitates the transfer of objects between
+\proglang{R} and \proglang{C++}. This note has shown how to extend \pkg{Rcpp}
+to either user-defined or third-party classes via the \texttt{Rcpp::as} and
+\texttt{Rcpp::wrap} template functions. Both intrusive and non-intrusive
+approaches were discussed.
+
+\bibliographystyle{abbrvnat}
+\bibliography{Rcpp}
+
\end{document}
+
Modified: pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw 2010-09-29 16:57:53 UTC (rev 2247)
+++ pkg/Rcpp/inst/doc/Rcpp-introduction.Rnw 2010-09-29 17:29:20 UTC (rev 2248)
@@ -47,7 +47,7 @@
\section{Introduction}
-R is an extensible system. The `Writing R Extensions' manual \citep{R:exts}
+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
@@ -77,7 +77,7 @@
\subsection{Historical Context}
\pkg{Rcpp} first appeared in 2005 as a contribution (by Samperi) to the
-\pkg{RQuantLib} package \citep{cran:rquantlib} before becoming a CRAN package
+\pkg{RQuantLib} package \citep{CRAN:RQuantLib} before becoming 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
@@ -91,7 +91,7 @@
interface. This constitutes the `classic \pkg{Rcpp}' interface
(not described in this article) which will be maintained for the foreseeable future.
-Yet C++ coding standards continued to evolve \citep{meyers:effectivecplusplus}.
+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
@@ -102,32 +102,32 @@
\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
+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{urbanek2003:rserve,cran:Rserve} was another early approach,
+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
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.
+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{runnalls09:cxxr} comes to this topic from the other side:
+\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
-part. A similar approach is discussed by \cite{templelang09:modestproposal}
+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.
%
Another slightly different angle is offered by
-\cite{templelang09:rgcctranslationunit} who uses compiler output for
+\cite{TempleLang:2009:RGCCTranslationUnit} who uses compiler output for
references on the code in order to add bindings and wrappers.
\subsection{Rcpp Use Cases}
@@ -161,8 +161,8 @@
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}
+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.
\subsection{A First Example}
@@ -197,7 +197,7 @@
\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:exts}. Sixth, the return conversion
+'Writing R Extensions' manual \citep{R:Extensions}. Sixth, the return conversion
from the \code{NumericVector} to the \code{SEXP} type is also automatic.
We argue that this \pkg{Rcpp}-based usage is much easier to read, write and debug than the
@@ -248,7 +248,7 @@
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:ints} documents these various types.
+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
that it encapsulates.
@@ -266,7 +266,7 @@
\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
+\citep{R:Extensions}. It creates a \code{numeric} vector of two elements
and assigns some values to it.
\begin{example}
@@ -355,7 +355,7 @@
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/rcpp -r 2248
More information about the Rcpp-commits
mailing list