[Rcpp-commits] r4457 - in pkg/Rcpp: inst/doc/Rcpp-FAQ inst/doc/Rcpp-modules vignettes
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Aug 31 21:07:28 CEST 2013
Author: edd
Date: 2013-08-31 21:07:27 +0200 (Sat, 31 Aug 2013)
New Revision: 4457
Added:
pkg/Rcpp/vignettes/Rcpp-FAQ.Rnw
pkg/Rcpp/vignettes/Rcpp-modules.Rnw
Removed:
pkg/Rcpp/inst/doc/Rcpp-FAQ/Rcpp-FAQ.Rnw
pkg/Rcpp/inst/doc/Rcpp-modules/Rcpp-modules.Rnw
Modified:
pkg/Rcpp/vignettes/Rcpp-package.Rnw
Log:
Rcpp-FAQ and Rcpp-modules vignettes moved to vignettes/
Deleted: pkg/Rcpp/inst/doc/Rcpp-FAQ/Rcpp-FAQ.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-FAQ/Rcpp-FAQ.Rnw 2013-08-31 18:54:32 UTC (rev 4456)
+++ pkg/Rcpp/inst/doc/Rcpp-FAQ/Rcpp-FAQ.Rnw 2013-08-31 19:07:27 UTC (rev 4457)
@@ -1,761 +0,0 @@
-\documentclass[10pt]{article}
-%\VignetteIndexEntry{Rcpp-FAQ}
-\usepackage[USletter]{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}}
-\newcommand{\code}[1]{\texttt{#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}
-
-<<echo=FALSE,print=FALSE>>=
-prettyVersion <- packageDescription("Rcpp")$Version
-prettyDate <- format(Sys.Date(), "%B %e, %Y")
-@
-
-\author{Dirk Eddelbuettel \and Romain Fran\c{c}ois}
-\title{Frequently Asked Questions about \pkg{Rcpp}}
-\date{\pkg{Rcpp} version \Sexpr{prettyVersion} as of \Sexpr{prettyDate}}
-
-<<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)
-@
-
-\newcommand{\faq}[1]{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,JSS:Rcpp} package.
-}
-
-\section{Getting started}
-
-\subsection{How do I get started ?}
-
-If you have \pkg{Rcpp} installed, please execute the following command in \proglang{R}
-
-<<eval=FALSE>>=
-vignette( "Rcpp-introduction" )
-@
-
-\noindent to access the vignette which provides a detailed introduction.
-
-If you do not have \pkg{Rcpp} installed, the document should also be available
-whereever you found this document, \textsl{i.e.,} on every mirror of CRAN site.
-
-\subsection{What do I need ?}
-
-Obviously, \proglang{R} must be installed. \pkg{Rcpp} provides a
-\proglang{C++} API as an extension to the \proglang{R} system. As such, it
-is bound by the choices made by \proglang{R} and is also influenced by how
-\proglang{R} is configured.
-
-In general, the standard environment for building a CRAN package from source
-(particularly when it contains \proglang{C} or \proglang{C++} code) is required. This
-means one needs:
-\begin{itemize}
-\item a development environment with a suitable compiler (see
- below), header files and required libraries;
-\item \proglang{R} should be built in a way that permits linking and possibly
- embedding of \proglang{R}; this is typically ensured by the
- \texttt{--enable-shared-lib} option;
-\item standard development tools such as \texttt{make} etc.
-\end{itemize}
-
-
-\subsection{What compiler can I use ?}
-
-On almost all platforms, the GNU Compiler Collection (or \texttt{gcc}, which
-is also the name of its \proglang{C} language compiler) has to be used along
-with the corresponding \texttt{g++} compiler for the \proglang{C++} language.
-A minimal suitable version is a final 4.2.* release; earlier 4.2.* were
-lacking some \proglang{C++} features (and even 4.2.1, still used on OS X, has
-issues).
-
-Generally speaking, and as of early
-2011, the default compilers on all the common platforms are suitable.
-
-Specific per-platform notes:
-\begin{description}
- \item[Windows] users need the \texttt{Rtools} package from the site maintained by
- Duncan Murdoch which contains all the required tools in a single package;
- complete instructions specific to Windows are in the `R Administration'
- manual \citep[Appendix D]{R:Administration}.
- \item[OS X] users, as noted in the `R Administration' manual \citep[Appendix
- C.4]{R:Administration}, need to install the Apple Developer Tools
- (\textsl{e.g.}, \texttt{Xcode}) (as well as \texttt{gfortran} if \proglang{R} or
- Fortran-using packages are to be built); also see \faq{q:OSX} below.
- \item[Linux] user need to install the standard developement packages. Some
- distributions provide helper packages which pull in all the required
- packages; the \texttt{r-base-dev} package on Debian and Ubuntu is an example.
-\end{description}
-
-The \texttt{clang} and \texttt{clang++} compilers from the LLVM project can
-also be used as they are inter-operable with \texttt{gcc} et al. The
-\texttt{clang++} compiler is particularly interesting as it emits much more
-comprehensible error messages than \texttt{g++}.
-
-The Intel \texttt{icc} family has also been used successfully as its output
-files can also be combined with those from \texttt{gcc}.
-
-\subsection{What other packages are useful ?}
-
-Additional packages that we have found useful are
-
-\begin{description}
-\item[\pkg{inline}] which is invaluable for direct compilation, linking and loading
- of short code snippets;
-\item[\pkg{RUnit}] is used for unit testing; the package is recommended and will be needed to re-run
- some of our tests but it is not strictly required;
-\item[\pkg{rbenchmark}] to run simple timing comparisons and benchmarks; it is also
- recommended but not required.
-\end{description}
-
-
-\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 using inline?}
-\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 several 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.
-
-Update: Also see question \ref{using-attributes} below about 'Rcpp
-Attributes' \citep{CRAN:Rcpp:Attributes}.
-
-\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{How do I quickly prototype my code in a package?}
-\label{using-a-package}
-
-The simplest way may be to work directly with a package. Changes to both the
-\proglang{R} and \proglang{C++} code can be compiled and tested from the
-command line via:
-
-<<lang=bash>>=
-$ R CMD INSTALL mypkg && Rscript --default-packages=mypkg -e 'someFunctionToTickle(3.14)'
-@
-
-This first installs the packages, and then uses the command-line tool
-\code{Rscript} (which ships with \code{R}) to load the package, and execute
-the \proglang{R} expression following the \code{-e} switch. Such an
-expression can contain multiple statements separated by semicolons.
-\code{Rscript} is available on all three core operating systems.
-
-On Linux, one can also use \code{r} from the \code{littler} package by Horner
-and Eddelbuettel which is an alternative front end to \proglang{R} designed
-for both \verb|#!| (hashbang) scripting and command-line use. It has slightly
-faster start-up times than \code{Rscript}; and both give a guaranteed clean
-slate as a new session is created.
-
-The example then becomes
-
-<<lang=bash>>=
- $ R CMD INSTALL mypkg && r -l mypkg -e 'someFunctionToTickle(3.14)'
-@
-
-The \code{-l} option calls 'suppressMessages(library(mypkg))' before executing the
-\proglang{R} expression. Several packages can be listed, separated by a comma.
-
-\subsection{But I want to compile my code with R CMD SHLIB !}
-\label{using-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 so, 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.
-
-On the Linux command-line, you can do the following:\newline
-<<lang=bash>>=
-$ export PKG_LIBS=`Rscript -e "Rcpp:::LdFlags()"`
-$ export PKG_CXXFLAGS=`Rscript -e "Rcpp:::CxxFlags()"`
-$ R CMD SHLIB myfile.cpp
-@
-which first defines and exports two relevant environment variables which
-\texttt{R CMD SHLIB} then relies on. On other operating systems, appropriate
-settings may have to be used to define the environment variables.
-
-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.
-
-An alternative, which might work better on Windows is to use the
-unexported function \texttt{Rcpp:::SHLIB} :
-
-<<lang=bash>>=
-$ Rscript -e "Rcpp:::SHLIB('myfile.cpp')"
-@
-
-\subsection{But R CMD SHLIB still does not work !}
-
-We have had reports in the past where build failures occurred when users had
-non-standard code in their \verb|~/.Rprofile| or \texttt{Rprofile.site} (or
-equivalent) files.
-
-If such code emits text on \texttt{stdout}, the frequent and implicit
-invocation of \texttt{Rscript -e "..."} (as in \faq{using-r-cmd-shlib}
-above) to retrieve settings directly from \pkg{Rcpp} will fail.
-
-You may need to uncomment such non-standard code, or protect it by wrapping
-it inside \texttt{if (interactive())}, or possibly try to use \texttt{Rscript
- --vanilla} instead of plain \texttt{Rscript}.
-
-
-\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{I am having problems building Rcpp on OS X, any help ?}
-\label{q:OSX}
-
-OS X is a little more conservative with compiler versions, so it pays to get
-the latest of whatever Apple releases which may already be a little behind
-what is used on Linux or Windows.
-
-At the time of writing this paragraph (in the spring of 2011), \pkg{Rcpp}
-(just like CRAN) supports all OS X releases greater or equal to 10.5.
-However, building \pkg{Rcpp} from source (or building packages using
-\pkg{Rcpp}) also requires a recent-enough version of Xcode. For the
-\textsl{Leopard} release of OS X, the current version is 3.1.4 which can be
-downloaded free of charge from the Apple Developer site. Users may have to
-manually select \code{g++-4.2} via the symbolic link \code{/usr/bin/g++}.
-The \textsl{Snow Leopard} release already comes with Xcode 3.2.x and work as
-is.
-
-\subsection{Does \pkg{Rcpp} work on solaris/suncc ?}
-
-Yes, it generally does. But as we do not have access to such systems, some
-issues persist on the CRAN test systems.
-
-\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 (if those differ from the defaults).
-
-\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.
-
-\subsection{How do I quickly prototype my code using Attributes?}
-\label{using-attributes}
-
-\pkg{Rcpp} version 0.10.0 and later offer a new feature 'Rcpp Attributes'
-which is described in detail in its own vignette
-\citep{CRAN:Rcpp:Attributes}. In short, it offers functions \code{evalCpp},
-\code{cppFunction} and \code{sourceCpp} which extend the functionality of the
-\code{cxxfunction} function.
-
-
-
-\section{Examples}
-
-The following questions were asked on the \texttt{rcpp-devel} mailing list,
-which is generally the best place to ask questions.
-
-\subsection{Can I use templates with \pkg{Rcpp} and \pkg{inline} ? }
-
-\begin{quote}
- \emph{I'm curious whether one can provide a class definition inline in an R
- script and then initialize an instance of the class and call a method on
- the class, all inline in R.}
-\end{quote}
-
-\noindent Most certainly, consider this simple example of a templated class
-which squares its argument:
-
-<<lang=r>>=
-inc <- 'template <typename T>
- class square : public std::unary_function<T,T> {
- public:
- T operator()( T t) const { return t*t ;}
- };
- '
-
-src <- '
- double x = Rcpp::as<double>(xs);
- int i = Rcpp::as<int>(is);
- square<double> sqdbl;
- square<int> sqint;
- return Rcpp::DataFrame::create(Rcpp::Named("x", sqdbl(x)),
- Rcpp::Named("i", sqint(i)));
- '
-fun <- cxxfunction(signature(xs="numeric", is="integer"),
- body=src, include=inc, plugin="Rcpp")
-
-fun(2.2, 3L)
-@
-
-Update: Also see question \ref{using-attributes} above about 'Rcpp
-Attributes' \citep{CRAN:Rcpp:Attributes} and its \code{sourceCpp} function.
-
-\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.
-Also, the \pkg{RcppEigen} package provides an alternative using the
-\href{Eigen}{http://eigen.tuxfamily.org} template library.
-
-
-The following example is adapted from the examples available at the project
-page of Armadillo. It calculates $ 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>>=
-external_highlight( "myfile.cpp", type = "LATEX", doc = FALSE )
-@
-
-<<>>=
-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{Can I use code from the Rmath header and library with \pkg{Rcpp} ?}
-
-\begin{quote}
- \emph{Can I call functions defined in the Rmath header file and the
- standalone math library for R--as for example the random number generators?}
-\end{quote}
-
-\noindent Yes, of course. This math library exports a subset of R, but \pkg{Rcpp} has
-access to much more. Here is another simple example. Note how we have to use
-and instance of the \texttt{RNGScope} class to set and re-set the
-random-number generator. This also illustrates Rcpp sugar as we are using a
-vectorised call to \texttt{rnorm}. Moreover, because the RNG is reset, the
-two calls result in the same random draws. If we wanted to control the draws,
-we could explicitly set the seed after the \texttt{RNGScope} object has been
-instantiated.
-
-<<>>=
-fx <- cxxfunction(signature(),
- 'RNGScope();
- return rnorm(5, 0, 100);',
- plugin="Rcpp")
-fx()
-fx()
-@
-
-\subsection{Can I use NA and Inf with \pkg{Rcpp} ?}
-
-\begin{quote}
- \emph{R knows about NA and Inf. How do I use them from C++?}
-\end{quote}
-
-\noindent Yes, see the following example:
-
-<<>>=
-src <- 'Rcpp::NumericVector v(4);
- v[0] = R_NegInf; // -Inf
- v[1] = NA_REAL; // NA
- v[2] = R_PosInf; // Inf
- v[3] = 42; // see the Hitchhiker Guide
- return Rcpp::wrap(v);'
-fun <- cxxfunction(signature(), src, plugin="Rcpp")
-fun()
-@
-
-
-\subsection{Can I easily multiply matrices ?}
-
-\begin{quote}
- \emph{Can I multiply matrices easily?}
-\end{quote}
-
-\noindent Yes, via the \pkg{RcppArmadillo} package which builds upon \pkg{Rcpp} and the
-wonderful Armadillo library at \url{http://arma.sf.net}:
-
-<<eval=FALSE>>=
-txt <- 'arma::mat Am = Rcpp::as< arma::mat >(A);
- arma::mat Bm = Rcpp::as< arma::mat >(B);
- return Rcpp::wrap( Am * Bm );'
-mmult <- cxxfunction(signature(A="numeric", B="numeric"),
- body=txt, plugin="RcppArmadillo")
-A <- matrix(1:9, 3, 3)
-B <- matrix(9:1, 3, 3)
-C <- mmult(A, B)
-@
-% < < echo=FALSE,print=FALSE > > =
-% A <- matrix(1:9, 3, 3)
-% B <- matrix(9:1, 3, 3)
-% A %*% B
-% @
-
-Armadillo supports a full range of common linear algebra operations.
-
-The \pkg{RcppEigen} package provides an alternative using the
-\href{Eigen}{http://eigen.tuxfamily.org} template library.
-
-\subsection{How do I write a plugin for \pkg{inline} ?}
-
-\begin{quote}
- \emph{How can I create my own plugin for use by the \pkg{inline} package?}
-\end{quote}
-
-\noindent Here is an example which shows how to it using GSL libraries as an
-example. This is merely for demonstration, it is also not perfectly general
-as we do not detect locations first---but it serves as an example:
-
-<<eval=FALSE>>=
-## simple example of seeding RNG and drawing one random number
-gslrng <- '
-int seed = Rcpp::as<int>(par) ;
-gsl_rng_env_setup();
-gsl_rng *r = gsl_rng_alloc (gsl_rng_default);
-gsl_rng_set (r, (unsigned long) seed);
-double v = gsl_rng_get (r);
-gsl_rng_free(r);
-return Rcpp::wrap(v);'
-
-plug <- Rcpp:::Rcpp.plugin.maker(
- include.before = "#include <gsl/gsl_rng.h>",
- libs = paste("-L/usr/local/lib/R/site-library/Rcpp/lib -lRcpp",
- "-Wl,-rpath,/usr/local/lib/R/site-library/Rcpp/lib",
- "-L/usr/lib -lgsl -lgslcblas -lm"))
-registerPlugin("gslDemo", plug )
-fun <- cxxfunction(signature(par="numeric"), gslrng, plugin="gslDemo")
-fun(0)
-@
-%
-
-Here the \pkg{Rcpp} function \code{Rcpp.plugin.maker} is used to create a
-plugin 'plug' which is then registered, and subsequently used by \pkg{inline}.
-
-
-\subsection{How can I pass one additional flag to the compiler?}
-
-\begin{quote}
- \emph{How can I pass another flag to the \code{g++} compiler without writing a new plugin?}
-\end{quote}
-
-The quickest way is to modify the return value from an existing plugin. Here
-we use the default one from \pkg{Rcpp} itself in order to pass the new flag
-\verb|-std=c++0x|. As it does not set the \verb|PKG_CXXFLAGS| variable, we
-simply assign this. For other plugins, one may need to append to the existing
-values instead.
-
-<<eval=FALSE>>=
-myplugin <- getPlugin("Rcpp")
-myplugin$env$PKG_CXXFLAGS <- "-std=c++0x"
-f <- cxxfunction(signature(), settings=myplugin, body='
-+ std::vector<double> x = { 1.0, 2.0, 3.0 }; // fails without -std=c++0x
-+ return Rcpp::wrap(x);
-+ ')
-f()
-@
-
-\subsection{How can I set matrix row and column names ?}
-
-\begin{quote}
- \emph{Ok, I can create a matrix, but how do I set its row and columns names?}
-\end{quote}
-
-Pretty much the same way as in \proglang{R} itself: We define a list with two
-character vectors, one each for row and column names, and assign this to the
-\code{dimnames} attribute:
-
-<<eval=FALSE>>=
-src <- '
- Rcpp::NumericMatrix x(2,2);
- x.fill(42); // or more interesting values
- Rcpp::List dimnms = // two vec. with static names
- Rcpp::List::create(Rcpp::CharacterVector::create("cc", "dd"),
- Rcpp::CharacterVector::create("ee", "ff"));
- // and assign it
- x.attr("dimnames") = dimnms;
- return(x);
-'
-fun <- cxxfunction(signature(), body=src, plugin="Rcpp")
-fun()
-@
-%
-
-\subsection{Why can long long types not be cast correctly?}
-
-That is a good and open question. We rely on the basic \proglang{R} types,
-notably \code{integer} and \code{numeric}. These can be cast to and from
-\proglang{C++} types without problems. But there are corner cases. The
-following example, contributed by a user, shows that we cannot reliably cast
-\code{long} types (on a 64-bit machines).
-
-<<eval=FALSE>>=
-BigInts <- cxxfunction(signature(),
- 'std::vector<long> bigints;
- bigints.push_back(12345678901234567LL);
- bigints.push_back(12345678901234568LL);
- Rprintf("Difference of %ld\\n", 12345678901234568LL - 12345678901234567LL);
- return wrap(bigints);', plugin="Rcpp", includes="#include <vector>")
-
-retval<-BigInts()
-
-# Unique 64-bit integers were cast to identical lower precision numerics
-# behind my back with no warnings or errors whatsoever. Error.
-
-stopifnot(length(unique(retval)) == 2)
-@
-%
-
-While the difference of one is evident at the \proglang{C++} level, it is no
-longer present once cast to \proglang{R}. The 64-bit integer values get cast
-to a floating point types with a 53-bit mantissa. We do not have a good
-suggestion or fix for casting 64-bit integer values: 32-bit integer values
-fit into \code{integer} types, up to 53 bit precision fits into
-\code{numeric} and beyond that truly large integers may have to converted
-(rather crudely) to text and re-parsed. Using a different representation as
-for example from the \href{http://gmplib.org/}{GNU Multiple Precision Arithmetic
- Library} may be an alternative.
-
-\section{Support}
-
-\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.
-
-
-\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{Where can I read old questions and answers ?}
-
-The normal \href{https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/rcpp-devel}{Rcpp-devel}
-mailing list hosting at R-forge contains an archive, which can be
-\href{http://lists.r-forge.r-project.org/mailman/swish.cgi?query=listname=rcpp-devel}{searched via swish}.
-
-Alternatively, one can also use
-\href{http://thread.gmane.org/gmane.comp.lang.r.rcpp/}{Gmane on Rcpp-devel} as well as
-\href{http://www.mail-archive.com/rcpp-devel@lists.r-forge.r-project.org/info.html}{Mail-Archive
- on Rcpp-devel} both of which offer web-based interfaces, including
-searching.
-
-\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{plainnat}
-\bibliography{Rcpp}
-
-\end{document}
-
Deleted: pkg/Rcpp/inst/doc/Rcpp-modules/Rcpp-modules.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-modules/Rcpp-modules.Rnw 2013-08-31 18:54:32 UTC (rev 4456)
+++ pkg/Rcpp/inst/doc/Rcpp-modules/Rcpp-modules.Rnw 2013-08-31 19:07:27 UTC (rev 4457)
@@ -1,1262 +0,0 @@
-\documentclass[10pt]{article}
-%\VignetteIndexEntry{Rcpp-modules}
-\usepackage[USletter]{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{\code}[1]{\texttt{#1}}
-\newcommand{\proglang}[1]{\textsf{#1}}
-\newcommand{\pkg}[1]{{\fontseries{b}\selectfont #1}}
-
-<<echo=FALSE,print=FALSE>>=
-require( inline )
-require( Rcpp )
-prettyVersion <- packageDescription("Rcpp")$Version
-prettyDate <- format(Sys.Date(), "%B %e, %Y")
-@
-
-\author{Dirk Eddelbuettel \and Romain Fran\c{c}ois}
-\title{Exposing \proglang{C++} functions and classes with \pkg{Rcpp} modules}
-\date{\pkg{Rcpp} version \Sexpr{prettyVersion} as of \Sexpr{prettyDate}}
-
-<<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}. \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 \pkg{Boost.Python}
- \proglang{C++} library \citep{Abrahams+Grosse-Kunstleve:2003:Boost.Python}
- which provides similar features for \proglang{Python}.
-}
-
-\section{Motivation}
-
-Exposing \proglang{C++} functionality to \proglang{R} is greatly facilitated
-by the \pkg{Rcpp} package and its underlying \proglang{C++} library
-\citep{CRAN:Rcpp,JSS:Rcpp}. \pkg{Rcpp} smoothes many of the rough edges in
-\proglang{R} and \proglang{C++} integration by replacing the traditional
-\proglang{R} Application Programming Interface (API) described in
-`\textsl{Writing R Extensions}' \citep{R:Extensions} with a consistent set of \proglang{C++}
-classes. The `\textsl{Rcpp-introduction}' vignette \citep{CRAN:Rcpp,JSS:Rcpp} describes the API and
-provides an introduction to using \pkg{Rcpp}.
-
-These \pkg{Rcpp} facilities offer a lot of assistance to the programmer
-wishing to interface \proglang{R} and \proglang{C++}. At the same time, these
-facilities are limited as they operate on a function-by-function basis. The
-programmer has to implement a \Sexpr{link(".Call")} compatible function (to
-conform to the \proglang{R} API) using classes of the \pkg{Rcpp} API as
-described in the next section.
-
-\subsection{Exposing functions using \pkg{Rcpp}}
-
-Exposing existing \proglang{C++} functions to \proglang{R} through \pkg{Rcpp}
-usually involves several steps. One approach is to write an additional wrapper
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/rcpp -r 4457
More information about the Rcpp-commits
mailing list