[Rcpp-commits] r4456 - in pkg/Rcpp: inst/doc/Rcpp-package inst/doc/Rcpp-quickref vignettes
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Aug 31 20:54:32 CEST 2013
Author: edd
Date: 2013-08-31 20:54:32 +0200 (Sat, 31 Aug 2013)
New Revision: 4456
Added:
pkg/Rcpp/vignettes/Rcpp-package.Rnw
pkg/Rcpp/vignettes/Rcpp-quickref.Rnw
Removed:
pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw
pkg/Rcpp/inst/doc/Rcpp-quickref/Rcpp-quickref.Rnw
Log:
Rcpp-quickref and Rcpp-package vignettes moved to vignettes/
Deleted: pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw 2013-08-31 18:52:29 UTC (rev 4455)
+++ pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw 2013-08-31 18:54:32 UTC (rev 4456)
@@ -1,389 +0,0 @@
-\documentclass[10pt]{article}
-%\VignetteIndexEntry{Rcpp-package}
-\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}}
-
-%% 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{Writing a package that uses \pkg{Rcpp} }
-\date{\pkg{Rcpp} version \Sexpr{prettyVersion} as of \Sexpr{prettyDate}}
-
-<<echo=FALSE>>=
-require( Rcpp )
-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 document provides a short overview of how to use
- \pkg{Rcpp}~\citep{CRAN:Rcpp,JSS:Rcpp} when writing an \proglang{R} package. It
- shows how usage of the function \Sexpr{link("Rcpp.package.skeleton")}
- which creates a complete and self-sufficient example package using
- \pkg{Rcpp}. All components of the directory tree created by
- \Sexpr{link("Rcpp.package.skeleton")} are discussed in detail. This
- document thereby complements the \textsl{Writing R Extensions}
- manual~\citep{R:Extensions} which is the authoritative source on how to extend
- \proglang{R} in general.
-}
-
-\section{Introduction}
-
-\pkg{Rcpp}~\citep{CRAN:Rcpp,JSS:Rcpp} is an extension package for \proglang{R} which
-offers an easy-to-use yet featureful interface between \proglang{C++} and
-\proglang{R}. However, it is somewhat different from a traditional
-\proglang{R} package because its key component is a \proglang{C++} library. A
-client package that wants to make use of the \pkg{Rcpp} features must link
-against the library provided by \pkg{Rcpp}.
-
-It should be noted that \proglang{R} has only limited support for
-\proglang{C(++)}-level dependencies between packages~\citep{R:Extensions}. The
-\texttt{LinkingTo} declaration in the package \texttt{DESCRIPTION} file
-allows the client package to retrieve the headers of the target package (here
-\pkg{Rcpp}), but support for linking against a library is not provided by
-\proglang{R} and has to be added manually.
-
-This document follows the steps of the \Sexpr{link("Rcpp.package.skeleton")}
-function to illustrate a recommended way of using \pkg{Rcpp} from a client
-package. We illustrate this using a simple \proglang{C++} function
-which will be called by an \proglang{R} function.
-
-We strongly encourage the reader to become familiar with the material in the
-\textsl{Writing R Extensions} manual~\citep{R:Extensions}, as well as with other
-documents on \proglang{R} package creation such as \cite{Leisch:2008:Tutorial}. Given
-a basic understanding of how to create \proglang{R} package, the present
-document aims to provide the additional information on how to use \pkg{Rcpp}
-in such add-on packages.
-
-\section{Using \texttt{Rcpp.package.skeleton}}
-
-\subsection{Overview}
-
-\pkg{Rcpp} provides a function \Sexpr{link("Rcpp.package.skeleton")}, modeled
-after the base \proglang{R} function \Sexpr{link("package.skeleton")}, which
-facilitates creation of a skeleton package using \pkg{Rcpp}.
-
-\Sexpr{link("Rcpp.package.skeleton")} has a number of arguments documented on
-its help page (and similar to those of \Sexpr{link("package.skeleton")}). The
-main argument is the first one which provides the name of the package one
-aims to create by invoking the function. An illustration of a call using an
-argument \texttt{mypackage} is provided below.
-
-<<echo=FALSE>>=
-here <- getwd()
-gendir <- tempfile()
-dir.create( gendir )
-setwd( gendir )
-Rcpp.package.skeleton( "mypackage" )
-dir.create( tlib <- tempfile() )
-system( sprintf( 'R CMD INSTALL --library="%s" mypackage ', tlib ) )
-require( "mypackage", lib.loc = tlib )
-setwd(here)
-@
-
-% <<>>=
-% Rcpp.package.skeleton( "mypackage" )
-% writeLines( system( "tree" , intern = TRUE ) )
-% @
-\begin{Hchunk}
-\begin{Hinput}
-\ttfamily\noindent
-\hlprompt{\usebox{\hlboxgreaterthan}{\ }}\hlfunctioncall{Rcpp.package.skeleton}\hlkeyword{(}{\ }\hlstring{"mypackage"}{\ }\hlkeyword{)}\mbox{}
-\normalfont
-
-\end{Hinput}
-
-\begin{Hinput}
-\ttfamily\noindent
-\hlprompt{\usebox{\hlboxgreaterthan}{\ }}\hlfunctioncall{writeLines}\hlkeyword{(}{\ }\hlfunctioncall{system}\hlkeyword{(}{\ }\hlstring{"tree"}\hlkeyword{,}{\ }\hlargument{intern}{\ }\hlargument{=}{\ }\hlnumber{TRUE}{\ }\hlkeyword{)}{\ }\hlkeyword{)}\mbox{}
-\normalfont
-\end{Hinput}
-
-\begin{Houtput}
-\ttfamily\noindent
-.\hspace*{\fill}\\
-\hlstd{}\usebox{\hlboxbacktick}--{\ }mypackage\hspace*{\fill}\\
-\hlstd{}{\ }{\ }{\ }{\ }|--{\ }DESCRIPTION\hspace*{\fill}\\
-\hlstd{}{\ }{\ }{\ }{\ }|--{\ }NAMESPACE\hspace*{\fill}\\
-\hlstd{}{\ }{\ }{\ }{\ }|--{\ }R\hspace*{\fill}\\
-\hlstd{}{\ }{\ }{\ }{\ }|{\ }{\ }{\ }\usebox{\hlboxbacktick}--{\ }rcpp\usebox{\hlboxunderscore}hello\usebox{\hlboxunderscore}world.R\hspace*{\fill}\\
-\hlstd{}{\ }{\ }{\ }{\ }|--{\ }Read-and-delete-me\hspace*{\fill}\\
-\hlstd{}{\ }{\ }{\ }{\ }|--{\ }man\hspace*{\fill}\\
-\hlstd{}{\ }{\ }{\ }{\ }|{\ }{\ }{\ }|--{\ }mypackage-package.Rd\hspace*{\fill}\\
-\hlstd{}{\ }{\ }{\ }{\ }|{\ }{\ }{\ }\usebox{\hlboxbacktick}--{\ }rcpp\usebox{\hlboxunderscore}hello\usebox{\hlboxunderscore}world.Rd\hspace*{\fill}\\
-\hlstd{}{\ }{\ }{\ }{\ }\usebox{\hlboxbacktick}--{\ }src\hspace*{\fill}\\
-\hlstd{}{\ }{\ }{\ }{\ }{\ }{\ }{\ }{\ }|--{\ }Makevars\hspace*{\fill}\\
-\hlstd{}{\ }{\ }{\ }{\ }{\ }{\ }{\ }{\ }|--{\ }Makevars.win\hspace*{\fill}\\
-\hlstd{}{\ }{\ }{\ }{\ }{\ }{\ }{\ }{\ }|--{\ }rcpp\usebox{\hlboxunderscore}hello\usebox{\hlboxunderscore}world.cpp\hspace*{\fill}\\
-\hlstd{}{\ }{\ }{\ }{\ }{\ }{\ }{\ }{\ }\usebox{\hlboxbacktick}--{\ }rcpp\usebox{\hlboxunderscore}hello\usebox{\hlboxunderscore}world.h\hspace*{\fill}\\
-\hlstd{}\hspace*{\fill}\\
-\hlstd{}4{\ }directories,{\ }10{\ }files\hspace*{\fill}\\
-\hlstd{}\mbox{}
-\normalfont
-\end{Houtput}
-\end{Hchunk}
-
-Using \Sexpr{link("Rcpp.package.skeleton")} is by far the simplest approach
-as it fulfills two roles. It creates the complete set of files needed for a
-package, and it also includes the different components needed for using
-\pkg{Rcpp} that we discuss in the following sections.
-
-\subsection{\proglang{R} code}
-
-The skeleton contains an example \proglang{R} function
-\texttt{rcpp\_hello\_world} that uses the \Sexpr{link(".Call")} interface to
-invoke the \proglang{C++} function \texttt{rcpp\_hello\_world} from the
-package \texttt{mypackage}.
-
-<<echo=FALSE,results=tex>>=
-highlight(
- file.path( gendir, "mypackage", "R", "rcpp_hello_world.R" ),
- renderer = renderer_latex( doc = FALSE )
- )
-@
-
-\pkg{Rcpp} uses the \Sexpr{link(".Call")} calling convention as it allows
-transport of actual \proglang{R} objects back and forth between the
-\proglang{R} side and the \proglang{C++} side. \proglang{R} objects
-(\texttt{SEXP}) can be conveniently manipulated using the \pkg{Rcpp} API.
-
-Note that in this example, no arguments were passed from \proglang{R} down to
-the \proglang{C++} layer. Doing so is straightforward (and one of the key
-features of \pkg{Rcpp}) but not central to our discussion of the package
-creation mechanics.
-
-\subsection{\proglang{C++} code}
-
-The \proglang{C++} function is declared in the \texttt{rcpp\_hello\_world.h}
-header file:
-
-<<echo=FALSE,results=tex>>=
-external_highlight(
- file.path( gendir, "mypackage", "src", "rcpp_hello_world.h" ),
- type = "LATEX",
- doc = FALSE
- )
-@
-
-The header includes the \texttt{Rcpp.h} file, which is the only file that
-needs to be included to use \pkg{Rcpp}. The function is then implemented in
-the \texttt{rcpp\_hello\_world.cpp} file
-
-<<echo=FALSE,results=tex>>=
-external_highlight(
- file.path( gendir, "mypackage", "src", "rcpp_hello_world.cpp" ),
- type = "LATEX",
- doc = FALSE
-)
-@
-
-The function creates an \proglang{R} list that contains a
-\Sexpr{link("character")} vector and a \Sexpr{link("numeric")} vector using \pkg{Rcpp}
-classes. At the \proglang{R} level, we will therefore receive a list of
-length two containing these two vectors:
-
-<<>>=
-rcpp_hello_world( )
-@
-
-\subsection{\texttt{DESCRIPTION}}
-
-The skeleton generates an appropriate \texttt{DESCRIPTION} file, using
-both \texttt{Depends:} and \texttt{LinkingTo} for \pkg{Rcpp}:
-
-<<echo=FALSE,results=tex>>=
-local({
- tf <- sprintf( "%s.make", tempfile() )
- file.copy( file.path( gendir, "mypackage", "DESCRIPTION" ), tf )
- external_highlight( tf, type = "LATEX", doc = FALSE )
- unlink( tf )
-})
-@
-
-\Sexpr{link("Rcpp.package.skeleton")} adds the three last lines to the
-\texttt{DESCRIPTION} file generated by \Sexpr{link("package.skeleton")}.
-
-The \texttt{Depends} declaration indicates \proglang{R}-level dependency
-between the client package and \pkg{Rcpp}. The \texttt{LinkingTo} declaration
-indicates that the client package needs to use header files exposed by
-\pkg{Rcpp}.
-
-\subsection{\texttt{Makevars} and \texttt{Makevars.win}}
-
-Unfortunately, the \texttt{LinkingTo} declaration in itself is not
-enough to link to the user \proglang{C++} library of \pkg{Rcpp}. Until more
-explicit support for libraries is added to \proglang{R}, we need to manually
-add the \pkg{Rcpp} library to the \texttt{PKG\_LIBS} variable in the
-\texttt{Makevars} and \texttt{Makevars.win} files. \pkg{Rcpp} provides the
-unexported function \texttt{Rcpp:::LdFlags()} to ease the process:
-
-<<echo=FALSE,results=tex>>=
-local({
- tf <- sprintf( "%s.make", tempfile() )
- file.copy( file.path( gendir, "mypackage", "src", "Makevars" ), tf )
- external_highlight( tf, type = "LATEX", doc = FALSE )
- unlink( tf )
-})
-@
-
-The \texttt{Makevars.win} is the equivalent, targeting windows.
-
-<<echo=FALSE,results=tex>>=
-local({
- tf <- sprintf( "%s.make", tempfile() )
- file.copy( file.path( gendir, "mypackage", "src", "Makevars.win" ), tf )
- external_highlight( tf, type = "LATEX", doc = FALSE )
- unlink( tf )
-})
-@
-
-\subsection{\texttt{NAMESPACE}}
-
-The \Sexpr{link("Rcpp.package.skeleton")} function also creates a file
-\texttt{NAMESPACE}.
-
-<<echo=FALSE,results=tex>>=
-local({
- tf <- sprintf( "%s.make", tempfile() )
- file.copy( file.path( gendir, "mypackage", "NAMESPACE" ), tf )
- external_highlight( tf, type = "LATEX", doc = FALSE )
- unlink( tf )
-})
-@
-
-This file serves two purposes. First, it ensure that the dynamic library
-contained in the package we are creating via
-\Sexpr{link("Rcpp.package.skeleton")} will be loaded and thereby made
-available to the newly created \proglang{R} package. Second, it declares
-which functions should be globally visible from the namespace of this
-package. As a reasonable default, we export all functions.
-
-\subsection{Help files}
-
-Also created is a directory \texttt{man} containing two help files. One is
-for the package itself, the other for the (single) \proglang{R} function
-being provided and exported.
-
-The \textsl{Writing R Extensions} manual~\citep{R:Extensions} provides the complete
-documentation on how to create suitable content for help files.
-
-\subsubsection{\texttt{mypackage-package.Rd}}
-
-The help file \texttt{mypackage-package.Rd} can be used to describe
-the new package.
-
-<<echo=FALSE,results=tex>>=
-local({
- tf <- sprintf( "%s.make", tempfile() )
- file.copy( file.path( gendir, "mypackage", "man", "mypackage-package.Rd" ), tf )
- external_highlight( tf, type = "LATEX", doc = FALSE )
- unlink( tf )
-})
-@
-
-
-\subsubsection{\texttt{rcpp\_hello\_world.Rd}}
-
-The help file \texttt{rcpp\_hello\_world.Rd} serves as documentation for the
-example \proglang{R} function.
-
-<<echo=FALSE,results=tex>>=
-local({
- tf <- sprintf( "%s.make", tempfile() )
- file.copy( file.path( gendir, "mypackage", "man", "rcpp_hello_world.Rd" ), tf )
- external_highlight( tf, type = "LATEX", doc = FALSE )
- unlink( tf )
-})
-@
-
-
-\section{Further examples}
-
-The canonical example of a package that uses \pkg{Rcpp} is the
-\pkg{RcppExamples} \citep{CRAN:RcppExamples} package. \pkg{RcppExamples}
-contains various examples of using \pkg{Rcpp} using both the extended
-(``new'') API and the older (``classic'') API. Hence, the \pkg{RcppExamples}
-package is provided as a template for employing \pkg{Rcpp} in packages.
-
-Other CRAN packages using the \pkg{Rcpp} package are \pkg{RcppArmadillo}
-\citep{CRAN:RcppArmadillo}, \pkg{highlight} \citep{CRAN:highlight},
-and \pkg{minqa} \citep{CRAN:minqa} all of which follow precisely the guidelines
-of this document. Several other packages follow older (but still supported
-and appropriate) instructions. They can serve examples on how to get data to
-and from \proglang{C++} routines, but should not be considered templates for
-how to connect to \pkg{Rcpp}. The full list of packages using \pkg{Rcpp} can
-be found at the \href{http://CRAN.R-project.org/package=Rcpp}{CRAN page} of
-\pkg{Rcpp}.
-
-\section{Other compilers}
-
-Less experienced \proglang{R} users on the Windows platform frequently ask
-about using \pkg{Rcpp} with the Visual Studio toolchain. That is simply not
-possible as \proglang{R} is built with the \pkg{gcc} compiler. Different
-compilers have different linking conventions. These conventions are
-particularly hairy when it comes to using \proglang{C++}. In short, it is
-not possible to simply drop sources (or header files) from \pkg{Rcpp} into a
-\proglang{C++} project built with Visual Studio, and this note makes no
-attempt at claiming otherwise.
-
-\pkg{Rcpp} is fully usable on Windows provided the standard Windows
-toolchain for \proglang{R} is used. See the \textsl{Writing R Extensions}
-manual~\citep{R:Extensions} for details.
-
-\section{Summary}
-
-This document described how to use the \pkg{Rcpp} package for \proglang{R}
-and \proglang{C++} integration when writing an \proglang{R} extension
-package. The use of the \Sexpr{link("Rcpp.package.skeleton")} was shown in
-detail, and references to further examples were provided.
-
-\bibliographystyle{plainnat}
-\bibliography{Rcpp}
-
-\end{document}
-
Deleted: pkg/Rcpp/inst/doc/Rcpp-quickref/Rcpp-quickref.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-quickref/Rcpp-quickref.Rnw 2013-08-31 18:52:29 UTC (rev 4455)
+++ pkg/Rcpp/inst/doc/Rcpp-quickref/Rcpp-quickref.Rnw 2013-08-31 18:54:32 UTC (rev 4456)
@@ -1,379 +0,0 @@
-\documentclass[8pt,twocolumn,a4paper]{article}
-%\VignetteIndexEntry{Rcpp-quickref}
-
-\setlength{\hoffset}{-0.8in}
-\setlength{\voffset}{-0.8in}
-
-\setlength{\marginparwidth}{0pt}
-\setlength{\marginparsep}{0pt}
-\setlength{\oddsidemargin}{0pt}
-\setlength{\headheight}{0pt}
-\setlength{\topmargin}{0pt}
-\setlength{\headsep}{0pt}
-\setlength{\footskip}{0pt}
-\setlength{\textheight}{27cm}
-\setlength{\textwidth}{20cm}
-
-\usepackage[colorlinks]{hyperref}
-
-\newcommand{\pkg}[1]{{\fontseries{b}\selectfont #1}}
-
-<<echo=FALSE,print=FALSE>>=
-options( width= 50)
-library( "Rcpp" )
-prettyVersion <- packageDescription("Rcpp")$Version
-prettyDate <- format(Sys.Date(), "%B %e, %Y")
-@
-
-\author{Romain Fran\c{c}ois \and Dirk Eddelbuettel}
-\title{\pkg{Rcpp} Quick Reference Guide}
-\date{\pkg{Rcpp} version \Sexpr{prettyVersion} as of \Sexpr{prettyDate}}
-
-% \newsavebox{\highlightbox}
-% \renewenvironment{Hchunk}%
-% {%
-% \vspace{0.5em}\noindent\begin{lrbox}{\highlightbox}%
-% \begin{minipage}[b]{.42\textwidth}%
-% }%
-% {%
-% \end{minipage}%
-% \end{lrbox}%
-% \fcolorbox{highlightBorder}{highlightBg}{\usebox{\highlightbox}}%
-% \vspace{0.5em}}%
-
-\begin{document}
-\maketitle
-\thispagestyle{empty}
-
-% without the ~, latex does not want to newline
-% a newline between paragraph and code disconnects them and can orphan heading
-
-\paragraph{Important Notes}~
- \newline
-<<lang=cpp>>=
-// If you experience compiler errors, please check that you have an appropriate version of g++. See `Rcpp-FAQ' for more information.
-
-// Many of the examples here imply the following:
-using namespace Rcpp;
-// The inline package adds this for you. Alternately, use e.g.:
-Rcpp::NumericVector xx(10);
-@
-
-\paragraph{Create simple vectors}~
- \newline
-<<lang=cpp>>=
-SEXP x; std::vector<double> y(10);
-
-// from SEXP
-NumericVector xx(x);
-
-// of a given size (filled with 0)
-NumericVector xx(10);
-// ... with a default for all values
-NumericVector xx(10, 2.0);
-
-// range constructor
-NumericVector xx( y.begin(), y.end() );
-
-// using create
-NumericVector xx = NumericVector::create(
- 1.0, 2.0, 3.0, 4.0 );
-NumericVector yy = NumericVector::create(
- Named["foo"] = 1.0,
- _["bar"] = 2.0 ); // short for Named
-@
-
-\paragraph{Extract and set single elements}~
- \newline
-<<lang=cpp>>=
-// extract single values
-double x0 = xx[0];
-double x1 = xx(1);
-
-double y0 = yy["foo"];
-double y1 = yy["bar"];
-
-// set single values
-xx[0] = 2.1;
-xx(1) = 4.2;
-
-yy["foo"] = 3.0;
-
-// grow the vector
-yy["foobar"] = 10.0;
-@
-
-\paragraph{Using matrices}~
- \newline
-<<lang=cpp>>=
-// Initializing from SEXP,
-// dimensions handled automatically
-SEXP x;
-NumericMatrix xx(x);
-
-// Matrix of 4 rows & 5 columns (filled with 0)
-NumericMatrix xx(4, 5);
-
-// Fill with value
-int xsize = xx.nrow() * xx.ncol();
-for (int i = 0; i < xsize; i++) {
- xx[i] = 7;
-}
-// Same as above, using STL fill
-std::fill(xx.begin(), xx.end(), 8);
-
-// Assign this value to single element
-// (1st row, 2nd col)
-xx(0,1) = 4;
-
-// Reference the second column
-// Changes propagate to xx (same applies for Row)
-NumericMatrix::Column zzcol = xx( _, 1);
-zzcol = zzcol * 2;
-
-// Copy the second column into new object
-NumericVector zz1 = xx( _, 1);
-// Copy the submatrix (top left 3x3) into new object
-NumericMatrix zz2 = xx( Range(0,2), Range(0,2));
-@
-
-\paragraph{Inline}~
- \newline
-<<lang=cpp>>=
-## Note - this is R code. inline allows rapid testing.
-require(inline)
-testfun = cxxfunction(
- signature(x="numeric", i="integer"),
- body = '
- NumericVector xx(x);
- int ii = as<int>(i);
- xx = xx * ii;
- return( xx );
- ', plugin="Rcpp")
-testfun(1:5, 3)
-@
-
-\paragraph{Interface with R}~
- \newline
-<<lang=cpp>>=
-## In R, create a package shell. For details, see the "Writing R Extensions" manual.
-
-Rcpp.package.skeleton("myPackage")
-
-## Add R code to pkg R/ directory. Call C++ function. Do type-checking in R.
-
-myfunR = function(Rx, Ry) {
- ret = .Call("myCfun", Rx, Ry,
- package="myPackage")
- return(ret)
-}
-
-// Add C++ code to pkg src/ directory.
-using namespace Rcpp;
-// Define function as extern with RcppExport
-RcppExport SEXP myCfun( SEXP x, SEXP y) {
- // If R/C++ types match, use pointer to x. Pointer is faster, but changes to xx propagate to R ( xx -> x == Rx).
- NumericVector xx(x);
- // clone is slower and uses extra memory. Safe, R-like.
- NumericVector yy(clone(y));
- xx[0] = yy[0] = -1.5;
- int zz = xx[0];
- // use wrap() to return non-SEXP objects, e.g:
- // return(wrap(zz));
- // Build and return a list
- List ret; ret["x"] = xx; ret["y"] = yy;
- return(ret);
-}
-
-## From shell, above package directory
-R CMD check myPackage ## Optional
-R CMD INSTALL myPackage
-
-## In R:
-require(myPackage)
-aa = 1.5; bb = 1.5; cc = myfunR(aa, bb)
-aa == bb ## FALSE, C++ modifies aa
-aa = 1:2; bb = 1:2; cc = myfunR(aa, bb)
-identical(aa, bb)
-## TRUE, R/C++ types don't match
-@
-
-\paragraph{STL interface}~
- \newline
-<<lang=cpp>>=
-// sum a vector from beginning to end
-double s = std::accumulate(x.begin(),
- x.end(), 0.0);
-// prod of elements from beginning to end
-int p = std::accumulate(vec.begin(),
- vec.end(), 1, std::multiplies<int>());
-// inner_product to compute sum of squares
-double s2 = std::inner_product(res.begin(),
- res.end(), res.begin(), 0.0);
-@
-
-\paragraph{Function}~
- \newline
-<<lang=cpp>>=
-Function rnorm("rnorm");
-rnorm(100, _["mean"] = 10.2, _["sd"] = 3.2 );
-@
-
-\paragraph{Environment}~
- \newline
-<<lang=cpp>>=
-Environment stats("package:stats");
-Environment env( 2 ); // by position
-
-// special environments
-Environment::Rcpp_namespace();
-Environment::base_env();
-Environment::base_namespace();
-Environment::global_env();
-Environment::empty_env();
-
-Function rnorm = stats["rnorm"];
-glob["x"] = "foo";
-glob["y"] = 3;
-std::string x = glob["x"];
-
-glob.assign( "foo" , 3 );
-int foo = glob.get( "foo" );
-int foo = glob.find( "foo" );
-CharacterVector names = glob.ls()
-bool b = glob.exists( "foo" );
-glob.remove( "foo" );
-
-glob.lockBinding("foo");
-glob.unlockBinding("foo");
-bool b = glob.bindingIsLocked("foo");
-bool b = glob.bindingIsActive("foo");
-
-Environment e = stats.parent();
-Environment e = glob.new_child();
-@
-
-\paragraph{Modules}~
- \newline
-<<lang=cpp>>=
-// Warning -- At present, module-based objects do not persist across quit(save="yes")/reload cycles. To be safe, save results to R objects and remove module objects before exiting R.
-
-// To create a module-containing package from R, use:
-Rcpp.package.skeleton("mypackage",module=TRUE)
-// You will need to edit the RcppModules: line of the DESCRIPTION file to match your module name (in this example, from yada to mod_bar).
-
-class Bar {
- public:
- Bar(double x_) :
- x(x_), nread(0), nwrite(0) {}
-
- double get_x( ) {
- nread++; return x;
- }
-
- void set_x( double x_) {
- nwrite++; x = x_;
- }
-
- IntegerVector stats() const {
- return IntegerVector::create(
- _["read"] = nread,
- _["write"] = nwrite);
- }
- private:
- double x; int nread, nwrite;
-};
-
-RCPP_MODULE(mod_bar) {
- class_<Bar>( "Bar" )
- .constructor<double>()
- .property( "x", &Bar::get_x, &Bar::set_x,
- "Docstring for x" )
- .method( "stats", &Bar::stats,
- "Docstring for stats")
-;}
-
-## The following is R code.
-require(mypackage); show(Bar)
-b <- new(Bar, 10); b$x <- 10
-b_persist <- list(stats=b$stats(), x=b$x)
-rm(b)
-@
-
-\newpage
-
-\paragraph{Rcpp sugar}~
- \newline
-<<lang=cpp>>=
-NumericVector x = NumericVector::create(
- -2.0, -1.0, 0.0, 1.0, 2.0 );
-IntegerVector y = IntegerVector::create(
- -2, -1, 0, 1, 2 );
-
-NumericVector xx = abs( x );
-IntegerVector yy = abs( y );
-
-bool b = all( x < 3.0 ).is_true() ;
-bool b = any( y > 2 ).is_true();
-
-NumericVector xx = ceil( x );
-NumericVector xx = ceiling( x );
-NumericVector yy = floor( y );
-NumericVector yy = floor( y );
-
-NumericVector xx = exp( x );
-NumericVector yy = exp( y );
-
-NumericVector xx = head( x, 2 );
-IntegerVector yy = head( y, 2 );
-
-IntegerVector xx = seq_len( 10 );
-IntegerVector yy = seq_along( y );
-
-NumericVector xx = rep( x, 3 );
-NumericVector xx = rep_len( x, 10 );
-NumericVector xx = rep_each( x, 3 );
-
-IntegerVector yy = rev( y );
-@
-
-
-
-\paragraph{Random functions}~
- \newline
-<<lang=cpp>>=
-// Set seed
-RNGScope scope;
-
-// For details see Section 6.7.1--Distribution functions of the `Writing R Extensions' manual. In some cases (e.g. rnorm), distribution-specific arguments can be omitted; when in doubt, specify all dist-specific arguments. The use of doubles rather than integers for dist-specific arguments is recommended. Unless explicitly specified, log=FALSE.
-
-// Equivalent to R calls
-NumericVector xx = runif(20);
-NumericVector xx1 = rnorm(20);
-NumericVector xx1 = rnorm(20, 0);
-NumericVector xx1 = rnorm(20, 0, 1);
-
-// Example vector of quantiles
-NumericVector quants(5);
-for (int i = 0; i < 5; i++) {
- quants[i] = (i-2);
-}
-
-// in R, dnorm(-2:2)
-NumericVector yy = dnorm(quants) ;
-NumericVector yy = dnorm(quants, 0.0, 1.0) ;
-
-// in R, dnorm(-2:2, mean=2, log=TRUE)
-NumericVector yy = dnorm(quants, 2.0, true) ;
-
-// Note - cannot specify sd without mean
-// in R, dnorm(-2:2, mean=0, sd=2, log=TRUE)
-NumericVector yy = dnorm(quants, 0.0, 2.0, true) ;
-
-// To get original R api, use Rf_*
-double zz = Rf_rnorm(0, 2);
-@
-
-
-
-\end{document}
Copied: pkg/Rcpp/vignettes/Rcpp-package.Rnw (from rev 4448, pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw)
===================================================================
--- pkg/Rcpp/vignettes/Rcpp-package.Rnw (rev 0)
+++ pkg/Rcpp/vignettes/Rcpp-package.Rnw 2013-08-31 18:54:32 UTC (rev 4456)
@@ -0,0 +1,389 @@
+\documentclass[10pt]{article}
+%\VignetteIndexEntry{Rcpp-package}
+\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}}
+
+%% 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{Writing a package that uses \pkg{Rcpp} }
+\date{\pkg{Rcpp} version \Sexpr{prettyVersion} as of \Sexpr{prettyDate}}
+
+<<echo=FALSE>>=
+require( Rcpp )
+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 document provides a short overview of how to use
+ \pkg{Rcpp}~\citep{CRAN:Rcpp,JSS:Rcpp} when writing an \proglang{R} package. It
+ shows how usage of the function \Sexpr{link("Rcpp.package.skeleton")}
+ which creates a complete and self-sufficient example package using
+ \pkg{Rcpp}. All components of the directory tree created by
+ \Sexpr{link("Rcpp.package.skeleton")} are discussed in detail. This
+ document thereby complements the \textsl{Writing R Extensions}
+ manual~\citep{R:Extensions} which is the authoritative source on how to extend
+ \proglang{R} in general.
+}
+
+\section{Introduction}
+
+\pkg{Rcpp}~\citep{CRAN:Rcpp,JSS:Rcpp} is an extension package for \proglang{R} which
+offers an easy-to-use yet featureful interface between \proglang{C++} and
+\proglang{R}. However, it is somewhat different from a traditional
+\proglang{R} package because its key component is a \proglang{C++} library. A
+client package that wants to make use of the \pkg{Rcpp} features must link
+against the library provided by \pkg{Rcpp}.
+
+It should be noted that \proglang{R} has only limited support for
+\proglang{C(++)}-level dependencies between packages~\citep{R:Extensions}. The
+\texttt{LinkingTo} declaration in the package \texttt{DESCRIPTION} file
+allows the client package to retrieve the headers of the target package (here
+\pkg{Rcpp}), but support for linking against a library is not provided by
+\proglang{R} and has to be added manually.
+
+This document follows the steps of the \Sexpr{link("Rcpp.package.skeleton")}
+function to illustrate a recommended way of using \pkg{Rcpp} from a client
+package. We illustrate this using a simple \proglang{C++} function
+which will be called by an \proglang{R} function.
+
+We strongly encourage the reader to become familiar with the material in the
+\textsl{Writing R Extensions} manual~\citep{R:Extensions}, as well as with other
+documents on \proglang{R} package creation such as \cite{Leisch:2008:Tutorial}. Given
+a basic understanding of how to create \proglang{R} package, the present
+document aims to provide the additional information on how to use \pkg{Rcpp}
+in such add-on packages.
+
+\section{Using \texttt{Rcpp.package.skeleton}}
+
+\subsection{Overview}
+
+\pkg{Rcpp} provides a function \Sexpr{link("Rcpp.package.skeleton")}, modeled
+after the base \proglang{R} function \Sexpr{link("package.skeleton")}, which
+facilitates creation of a skeleton package using \pkg{Rcpp}.
+
+\Sexpr{link("Rcpp.package.skeleton")} has a number of arguments documented on
+its help page (and similar to those of \Sexpr{link("package.skeleton")}). The
+main argument is the first one which provides the name of the package one
+aims to create by invoking the function. An illustration of a call using an
+argument \texttt{mypackage} is provided below.
+
+<<echo=FALSE>>=
+here <- getwd()
+gendir <- tempfile()
+dir.create( gendir )
+setwd( gendir )
+Rcpp.package.skeleton( "mypackage" )
+dir.create( tlib <- tempfile() )
+system( sprintf( 'R CMD INSTALL --library="%s" mypackage ', tlib ) )
+require( "mypackage", lib.loc = tlib )
+setwd(here)
+@
+
+% <<>>=
+% Rcpp.package.skeleton( "mypackage" )
+% writeLines( system( "tree" , intern = TRUE ) )
+% @
+\begin{Hchunk}
+\begin{Hinput}
+\ttfamily\noindent
+\hlprompt{\usebox{\hlboxgreaterthan}{\ }}\hlfunctioncall{Rcpp.package.skeleton}\hlkeyword{(}{\ }\hlstring{"mypackage"}{\ }\hlkeyword{)}\mbox{}
+\normalfont
+
+\end{Hinput}
+
+\begin{Hinput}
+\ttfamily\noindent
+\hlprompt{\usebox{\hlboxgreaterthan}{\ }}\hlfunctioncall{writeLines}\hlkeyword{(}{\ }\hlfunctioncall{system}\hlkeyword{(}{\ }\hlstring{"tree"}\hlkeyword{,}{\ }\hlargument{intern}{\ }\hlargument{=}{\ }\hlnumber{TRUE}{\ }\hlkeyword{)}{\ }\hlkeyword{)}\mbox{}
+\normalfont
+\end{Hinput}
+
+\begin{Houtput}
+\ttfamily\noindent
+.\hspace*{\fill}\\
+\hlstd{}\usebox{\hlboxbacktick}--{\ }mypackage\hspace*{\fill}\\
+\hlstd{}{\ }{\ }{\ }{\ }|--{\ }DESCRIPTION\hspace*{\fill}\\
+\hlstd{}{\ }{\ }{\ }{\ }|--{\ }NAMESPACE\hspace*{\fill}\\
+\hlstd{}{\ }{\ }{\ }{\ }|--{\ }R\hspace*{\fill}\\
+\hlstd{}{\ }{\ }{\ }{\ }|{\ }{\ }{\ }\usebox{\hlboxbacktick}--{\ }rcpp\usebox{\hlboxunderscore}hello\usebox{\hlboxunderscore}world.R\hspace*{\fill}\\
+\hlstd{}{\ }{\ }{\ }{\ }|--{\ }Read-and-delete-me\hspace*{\fill}\\
+\hlstd{}{\ }{\ }{\ }{\ }|--{\ }man\hspace*{\fill}\\
+\hlstd{}{\ }{\ }{\ }{\ }|{\ }{\ }{\ }|--{\ }mypackage-package.Rd\hspace*{\fill}\\
+\hlstd{}{\ }{\ }{\ }{\ }|{\ }{\ }{\ }\usebox{\hlboxbacktick}--{\ }rcpp\usebox{\hlboxunderscore}hello\usebox{\hlboxunderscore}world.Rd\hspace*{\fill}\\
+\hlstd{}{\ }{\ }{\ }{\ }\usebox{\hlboxbacktick}--{\ }src\hspace*{\fill}\\
+\hlstd{}{\ }{\ }{\ }{\ }{\ }{\ }{\ }{\ }|--{\ }Makevars\hspace*{\fill}\\
+\hlstd{}{\ }{\ }{\ }{\ }{\ }{\ }{\ }{\ }|--{\ }Makevars.win\hspace*{\fill}\\
+\hlstd{}{\ }{\ }{\ }{\ }{\ }{\ }{\ }{\ }|--{\ }rcpp\usebox{\hlboxunderscore}hello\usebox{\hlboxunderscore}world.cpp\hspace*{\fill}\\
+\hlstd{}{\ }{\ }{\ }{\ }{\ }{\ }{\ }{\ }\usebox{\hlboxbacktick}--{\ }rcpp\usebox{\hlboxunderscore}hello\usebox{\hlboxunderscore}world.h\hspace*{\fill}\\
+\hlstd{}\hspace*{\fill}\\
+\hlstd{}4{\ }directories,{\ }10{\ }files\hspace*{\fill}\\
+\hlstd{}\mbox{}
+\normalfont
+\end{Houtput}
+\end{Hchunk}
+
+Using \Sexpr{link("Rcpp.package.skeleton")} is by far the simplest approach
+as it fulfills two roles. It creates the complete set of files needed for a
+package, and it also includes the different components needed for using
+\pkg{Rcpp} that we discuss in the following sections.
+
+\subsection{\proglang{R} code}
+
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/rcpp -r 4456
More information about the Rcpp-commits
mailing list