[Rcpp-commits] r2262 - pkg/Rcpp/inst/doc
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Fri Oct 1 07:26:14 CEST 2010
Author: romain
Date: 2010-10-01 07:26:12 +0200 (Fri, 01 Oct 2010)
New Revision: 2262
Modified:
pkg/Rcpp/inst/doc/Rcpp-FAQ.Rnw
pkg/Rcpp/inst/doc/Rcpp-extending.Rnw
pkg/Rcpp/inst/doc/Rcpp-modules.Rnw
pkg/Rcpp/inst/doc/Rcpp-package.Rnw
pkg/Rcpp/inst/doc/Rcpp-sugar.Rnw
Log:
fakes
Modified: pkg/Rcpp/inst/doc/Rcpp-FAQ.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-FAQ.Rnw 2010-09-30 16:34:00 UTC (rev 2261)
+++ pkg/Rcpp/inst/doc/Rcpp-FAQ.Rnw 2010-10-01 05:26:12 UTC (rev 2262)
@@ -1,369 +1,4 @@
\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.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-extending.Rnw 2010-09-30 16:34:00 UTC (rev 2261)
+++ pkg/Rcpp/inst/doc/Rcpp-extending.Rnw 2010-10-01 05:26:12 UTC (rev 2262)
@@ -1,369 +1,4 @@
\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-modules.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-modules.Rnw 2010-09-30 16:34:00 UTC (rev 2261)
+++ pkg/Rcpp/inst/doc/Rcpp-modules.Rnw 2010-10-01 05:26:12 UTC (rev 2262)
@@ -1,662 +1,4 @@
\documentclass[10pt]{article}
%\VignetteIndexEntry{Rcpp-modules}
-\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}}
-
-\author{Dirk Eddelbuettel \and Romain Fran\c{c}ois}
-\title{Exposing \proglang{C++} functions and classes with \pkg{Rcpp} modules}
-
-<<echo=FALSE>>=
-link <- function( f, package, text = f, root = "http://finzi.psych.upenn.edu/R/library/" ){
- 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 )
-}
-@
-
\begin{document}
-\maketitle
-
-\abstract{
- \noindent
- This note discusses \textsl{Rcpp modules} which have been introduced in
- version 0.8.1 of the \pkg{Rcpp} package. \textsl{Rcpp modules} allow programmers to
- expose \proglang{C++} functions and classes to \proglang{R} with relative
- ease. \textsl{Rcpp modules} are inspired from the \texttt{Boost.Python}
- \proglang{C++} library \citep{Abrahams+Grosse-Kunstleve:2003:Boost.Python} which provides the same
- features (and much more) for Python.
-}
-
-\section{Motivation}
-
-Exposing \proglang{C++} functionality to \proglang{R} is greatly facilitated
-by the \pkg{Rcpp} package and underlying \proglang{C++} library
-\citep{CRAN:Rcpp}. \pkg{Rcpp} smoothes many of the rough edges in
-\proglang{R} and \proglang{C++} integration by replacing the traditional
-\proglang{R} API \citep{R:Extensions} with a consistent set of \proglang{C++}
-classes.
-
-However, these facilities are limited to a function by function basis. The
-programmer has to implement a \Sexpr{link(".Call")} compatible function
-using classes of the \pkg{Rcpp} API.
-
-\subsection{Exposing functions}
-
-Exposing existing \proglang{C++} functions to \proglang{R} through \pkg{Rcpp}
-usually involves several steps. One often writes either an additional wrapper
-function that is responsible for converting input objects to the appropriate
-types, calling the actual worker function and converting the results back to
-a suitable type that can be returned to R. Alternatively, one can alter the
-worker function by changes to its signature and return value of the interface
-prescribed by the \texttt{.Call()} function of the \proglang{R} API. The
-return type has to the traditional \texttt{SEXP} from the \proglang{R}
-API. But with \pkg{Rcpp} we can also use one of the many types from the
-\pkg{Rcpp} API that offers implicit conversion to \texttt{SEXP}.
-
-Consider the \texttt{hello} function below:
-
-<<lang=cpp>>=
-const char* hello( std::string who ){
- std::string result( "hello " ) ;
- result += who ;
- return result.c_str() ;
-}
-@
-
-One can expose a such a function using \pkg{Rcpp} converters
-
-<<lang=cpp>>=
-RcppExport SEXP hello_wrapper( SEXP who){
- std::string input = Rcpp::as<std::string>( who )
- const char* result = hello( input ) ;
- return Rcpp::wrap( result );
-}
-@
-
-Here we use the (templated) \pkg{Rcpp} converter \texttt{as()} which can
-transform from a \texttt{SEXP} to a number of different \proglang{C++} and
-\pkg{Rcpp} types. The \pkg{Rcpp} function \texttt{wrap()} offers the opposite
-functionality and converts many known types to a \texttt{SEXP}.
-
-For comparison, the traditionally approach using the \proglang{R} API looks similar
-
-<<lang=cpp>>=
-extern "C" SEXP hello_wrapper( SEXP who){
- std::string input = CHAR(STRING_ELT(input,0)) ;
- const char* result = hello( input ) ;
- return mkString( result );
-}
-@
-
-Either way requires direct involvement from the programmer. This quickly
-becomes a time sink when many functions are involved. \textsl{Rcpp modules}
-provides a much more efficient way to expose the \texttt{hello} function to \proglang{R}.
-
-\subsection{Exposing classes}
-
-Exposing \proglang{C++} classes or structs is even more of a challenge because it
-requires writing glue code for each member function that is to be exposed. Consider the
-simple \texttt{World} class below:
-
-<<lang=cpp>>=
-class World {
-public:
- World() : msg("hello"){}
- void set(std::string msg) { this->msg = msg; }
- std::string greet() { return msg; }
-
-private:
- std::string msg;
-};
-@
-
-We might want a way to create objects of this class, and use the member
-functions \texttt{greet} and \texttt{set} to alter the object. External pointers
-\citep{R:Extensions} are the perfect vessel for this, and using the
-\texttt{Rcpp:::XPtr} template from \pkg{Rcpp} we can expose the class
-by exposing three functions :
-
-<<lang=cpp>>=
-using namespace Rcpp ;
-
-/** create an external pointer to a World object */
-RcppExport SEXP World__new(){
- return Rcpp::XPtr<World>( new World, true ) ;
-}
-
-/** invoke the greet method */
-RcppExport SEXP World__greet( SEXP xp ) {
- Rcpp::XPtr<World> w(xp) ;
- return Rcpp::wrap( w->greet() ) ;
-}
-
-/** invoke the set method */
-RcppExport SEXP World__set( SEXP xp, SEXP msg ){
- Rcpp::XPtr<World> w(xp) ;
- w->set( Rcpp::as<std::string>( msg ) ) ;
- return R_NilValue ;
-}
-@
-
-which can be used from \proglang{R} with some S4 glue code:
-
-<<eval=FALSE>>=
-setClass( "World", representation( pointer = "externalptr" ) )
-
-World_method <- function(name){
- paste( "World", name, sep = "__" )
-}
-
-setMethod( "$", "World", function(x, name ){
- function(...) .Call( World_method(name) , x at pointer, ... )
-} )
-
-w <- new( "World", .Call( World_method( "new" ) ) )
-w$set( "hello world" )
-w$greet()
-@
-
-\pkg{Rcpp} considerably simplifies the code that would be involved for using
-external pointers with the traditional \proglang{R} API. This still involves
-a lot of pattern code that quickly becomes hard to maintain and error prone.
-\textsl{Rcpp modules} offer a much nicer way to expose the \texttt{World}
-class in a way that makes both the internal \proglang{C++} code and the \proglang{R} code easier.
-
-\section{Rcpp modules}
-
-Rcpp modules are inspired from Python modules that are generated by the
-\texttt{Boost.Python} library \citep{Abrahams+Grosse-Kunstleve:2003:Boost.Python}. They provide an easy way
-to expose \proglang{C++} functions and classes to \proglang{R}, grouped
-together in a single entity.
-
-The module is created in a \texttt{cpp} file using the \texttt{RCPP\_MODULE}
-macro, which then contains declarative code of what the module
-exposes to \proglang{R}.
-
-\subsection{Exposing \proglang{C++} functions}
-
-Consider the \texttt{hello} function from the previous section.
-We can expose it to \proglang{R} :
-
-<<lang=cpp>>=
-const char* hello( std::string who ){
- std::string result( "hello " ) ;
- result += who ;
- return result.c_str() ;
-}
-
-RCPP_MODULE(yada){
- using namespace Rcpp ;
- function( "hello", &hello ) ;
-}
-@
-
-The code creates an Rcpp module called \texttt{yada}
-that exposes the \texttt{hello} function. \pkg{Rcpp} automatically
-deduces the conversions that are needed for input and output. This alleviates
-the need for a wrapper function using either \pkg{Rcpp} or the \proglang{R} API.
-
-On the \proglang{R} side, the module is simply retrieved by using the
-\Sexpr{link("Module")} function from \pkg{Rcpp}:
-
-<<eval=FALSE>>=
-require( Rcpp )
-yada <- Module( "yada" )
-yada$hello( "world" )
-@
-
-A module can contain any number of calls to \texttt{function} to register
-many internal functions to \proglang{R}. For example, these 6 functions :
-
-<<lang=cpp>>=
-std::string hello(){
- return "hello" ;
-}
-
-int bar( int x){
- return x*2 ;
-}
-
-double foo( int x, double y){
- return x * y ;
-}
-
-void bla( ){
- Rprintf( "hello\\n" ) ;
-}
-
-void bla1( int x){
- Rprintf( "hello (x = %d)\\n", x ) ;
-}
-
-void bla2( int x, double y){
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/rcpp -r 2262
More information about the Rcpp-commits
mailing list