[Rcpp-commits] r4467 - pkg/Rcpp/vignettes
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Aug 31 22:59:07 CEST 2013
Author: edd
Date: 2013-08-31 22:59:07 +0200 (Sat, 31 Aug 2013)
New Revision: 4467
Modified:
pkg/Rcpp/vignettes/Rcpp-attributes.Rnw
Log:
comment out some by not all highlight definitions which are now also pulled in via the highlight driver
Modified: pkg/Rcpp/vignettes/Rcpp-attributes.Rnw
===================================================================
--- pkg/Rcpp/vignettes/Rcpp-attributes.Rnw 2013-08-31 20:58:23 UTC (rev 4466)
+++ pkg/Rcpp/vignettes/Rcpp-attributes.Rnw 2013-08-31 20:59:07 UTC (rev 4467)
@@ -31,26 +31,26 @@
\date{\pkg{Rcpp} version \Sexpr{prettyVersion} as of \Sexpr{prettyDate}}
-%% highlights macros
-%% Style definition file generated by highlight 2.7, http://www.andre-simon.de/
-% Highlighting theme definition:
-\newcommand{\hlstd}[1]{\textcolor[rgb]{0,0,0}{#1}}
-\newcommand{\hlnum}[1]{\textcolor[rgb]{0,0,0}{#1}}
+%% %% highlights macros
+%% %% Style definition file generated by highlight 2.7, http://www.andre-simon.de/
+%% % Highlighting theme definition:
+%% \newcommand{\hlstd}[1]{\textcolor[rgb]{0,0,0}{#1}}
+%% \newcommand{\hlnum}[1]{\textcolor[rgb]{0,0,0}{#1}}
\newcommand{\hlopt}[1]{\textcolor[rgb]{0,0,0}{#1}}
-\newcommand{\hlesc}[1]{\textcolor[rgb]{0.74,0.55,0.55}{#1}}
-%\newcommand{\hlstr}[1]{\textcolor[rgb]{0.74,0.55,0.55}{#1}}
-\newcommand{\hlstr}[1]{\textcolor[rgb]{0.90,0.15,0.15}{#1}}
-%green: \newcommand{\hlstr}[1]{\textcolor[rgb]{0.13,0.67,0.13}{#1}} % 0.74 -> % 0.90; 0.55 -> 0.25
-\newcommand{\hldstr}[1]{\textcolor[rgb]{0.74,0.55,0.55}{#1}}
-\newcommand{\hlslc}[1]{\textcolor[rgb]{0.67,0.13,0.13}{#1}}
-\newcommand{\hlcom}[1]{\textcolor[rgb]{0.67,0.13,0.13}{#1}}
-\newcommand{\hldir}[1]{\textcolor[rgb]{0,0,0}{#1}}
-\newcommand{\hlsym}[1]{\textcolor[rgb]{0,0,0}{#1}}
-\newcommand{\hlline}[1]{\textcolor[rgb]{0.33,0.33,0.33}{#1}}
-\newcommand{\hlkwa}[1]{\textcolor[rgb]{0.61,0.13,0.93}{\bf{#1}}}
-\newcommand{\hlkwb}[1]{\textcolor[rgb]{0.13,0.54,0.13}{#1}}
-\newcommand{\hlkwc}[1]{\textcolor[rgb]{0,0,1}{#1}}
-\newcommand{\hlkwd}[1]{\textcolor[rgb]{0,0,0}{#1}}
+%% \newcommand{\hlesc}[1]{\textcolor[rgb]{0.74,0.55,0.55}{#1}}
+%% %\newcommand{\hlstr}[1]{\textcolor[rgb]{0.74,0.55,0.55}{#1}}
+%% \newcommand{\hlstr}[1]{\textcolor[rgb]{0.90,0.15,0.15}{#1}}
+%% %green: \newcommand{\hlstr}[1]{\textcolor[rgb]{0.13,0.67,0.13}{#1}} % 0.74 -> % 0.90; 0.55 -> 0.25
+%% \newcommand{\hldstr}[1]{\textcolor[rgb]{0.74,0.55,0.55}{#1}}
+%% \newcommand{\hlslc}[1]{\textcolor[rgb]{0.67,0.13,0.13}{#1}}
+%% \newcommand{\hlcom}[1]{\textcolor[rgb]{0.67,0.13,0.13}{#1}}
+%% \newcommand{\hldir}[1]{\textcolor[rgb]{0,0,0}{#1}}
+%% \newcommand{\hlsym}[1]{\textcolor[rgb]{0,0,0}{#1}}
+%% \newcommand{\hlline}[1]{\textcolor[rgb]{0.33,0.33,0.33}{#1}}
+%% \newcommand{\hlkwa}[1]{\textcolor[rgb]{0.61,0.13,0.93}{\bf{#1}}}
+%% \newcommand{\hlkwb}[1]{\textcolor[rgb]{0.13,0.54,0.13}{#1}}
+%% \newcommand{\hlkwc}[1]{\textcolor[rgb]{0,0,1}{#1}}
+%% \newcommand{\hlkwd}[1]{\textcolor[rgb]{0,0,0}{#1}}
\definecolor{bgcolor}{rgb}{1,1,1}
\newcommand{\hlppc}[1]{\textcolor[rgb]{0,0.51,0}{#1}}
@@ -84,7 +84,7 @@
functions as callable from \proglang{R} and automatically generating the code
required to invoke them. Attributes are intended to facilitate both interactive use
of \proglang{C++} within \proglang{R} sessions as well as to support \proglang{R}
- package development. The implementation of attributes is based on previous
+ package development. The implementation of attributes is based on previous
work in the \pkg{inline} package \citep{CRAN:inline}.
}
@@ -128,12 +128,12 @@
Attributes can also be used for package development via the
\texttt{compileAttributes} function, which automatically generates
-\texttt{extern "C"} and \texttt{.Call} wrappers for \proglang{C++}
+\texttt{extern "C"} and \texttt{.Call} wrappers for \proglang{C++}
functions within pacakges.
\section{Using Attributes}
-Attributes are annotations that are added to C++ source files to provide
+Attributes are annotations that are added to C++ source files to provide
additional information to the compiler. \pkg{Rcpp} supports attributes
to indicate that C++ functions should be made available as R functions,
as well as to optionally specify additional build dependencies for source files.
@@ -219,7 +219,7 @@
We can now write \proglang{C++} functions using built-in \proglang{C++} types
and \pkg{Rcpp} wrapper types and then source them just as we would an
-\proglang{R} script.
+\proglang{R} script.
The \texttt{sourceCpp} function performs caching based on the last
modified date of the source file so as long as the source file does not
@@ -233,7 +233,7 @@
% \begin{verbatim}
% DataFrame readData(
-% CharacterVector file,
+% CharacterVector file,
% CharacterVector colNames = CharacterVector::create(),
% std::string commentChar = "#",
% bool header = true)
@@ -265,7 +265,7 @@
\normalsize
\end{kframe}
-Note that C++ rules for default arguments still apply: they must occur
+Note that C++ rules for default arguments still apply: they must occur
consecutively at the end of the function signature and (unlike R) can't rely
on the values of other arguments.
@@ -275,18 +275,18 @@
\begin{itemize}
\item
String literals delimited by quotes (e.g. \texttt{"foo"})
-\item
+\item
Decimal numeric values (e.g. \texttt{10} or \texttt{4.5})
\item
- Pre-defined constants including \texttt{true}, \texttt{false},
+ Pre-defined constants including \texttt{true}, \texttt{false},
\texttt{R\_NilValue}, \texttt{NA\_STRING}, \texttt{NA\_INTEGER},
\texttt{NA\_REAL}, and \texttt{NA\_LOGICAL}.
\item
- Selected vector types (\texttt{CharacterVector}, \texttt{IntegerVector},
+ Selected vector types (\texttt{CharacterVector}, \texttt{IntegerVector},
and \texttt{NumericVector}) instantiated using the \texttt{::create}
static member function.
-\item
- \texttt{Matrix} types instantiated using the \texttt{rows},
+\item
+ \texttt{Matrix} types instantiated using the \texttt{rows},
\texttt{cols} constructor.
\end{itemize}
@@ -344,15 +344,15 @@
a common source file that can be executed using single call to \texttt{sourceCpp}.
To embed chunks of \proglang{R} code within a \proglang{C++}
-source file you include the \proglang{R} code within a block comment that
+source file you include the \proglang{R} code within a block comment that
has the prefix of \texttt{/*** R}. For example:
% \begin{verbatim}
% /*** R
-%
+%
% # Call the fibonacci function defined in C++
% fibonacci(10)
-%
+%
% */
% \end{verbatim}
\begin{kframe}
@@ -378,7 +378,7 @@
\subsection{Modifying Function Names}
You can change the name of an exported function as it appears to \proglang{R} by
-adding a name parameter to \texttt{Rcpp::export}. For example:
+adding a name parameter to \texttt{Rcpp::export}. For example:
% \begin{verbatim}
% // [[Rcpp::export(".convolveCpp")]]
@@ -395,7 +395,7 @@
\end{kframe}
Note that in this case since the specified name is prefaced by a \code{.} the exported R
-function will be hidden.
+function will be hidden.
\subsection{Function Requirements}
@@ -407,24 +407,24 @@
Be defined in the global namespace (i.e. not within a C++ namespace declaration)
\item
Have a return type that is either void or compatible with \texttt{Rcpp::wrap}
- and parameter types that are compatible with \texttt{Rcpp::as} (see sections
+ and parameter types that are compatible with \texttt{Rcpp::as} (see sections
3.1 and 3.2 of the `\textsl{Rcpp-introduction}' vignette for more details).
\item
Use fully qualified type names for the return value and all parameters.
- Rcpp types may however appear without a namespace qualifier (i.e.
+ Rcpp types may however appear without a namespace qualifier (i.e.
\texttt{DataFrame} is okay as a type name but \texttt{std::string} must be
- specified fully).
+ specified fully).
\end{itemize}
\subsection{Random Number Generation}
\proglang{R} functions implemented in \proglang{C} or \proglang{C++} need
-to be careful to surround use of internal random number geneneration routines
-(e.g. \texttt{unif\_rand}) with calls to \texttt{GetRNGstate} and
-\texttt{PutRNGstate}.
+to be careful to surround use of internal random number geneneration routines
+(e.g. \texttt{unif\_rand}) with calls to \texttt{GetRNGstate} and
+\texttt{PutRNGstate}.
-Within \pkg{Rcpp}, this is typically done using the \texttt{RNGScope} class.
-However, this is not necessary for \proglang{C++} functions exported using
+Within \pkg{Rcpp}, this is typically done using the \texttt{RNGScope} class.
+However, this is not necessary for \proglang{C++} functions exported using
attributes because an \texttt{RNGScope} is established for them automatically.
Note that \pkg{Rcpp} implements \texttt{RNGScope} using a counter, so it's
still safe to execute code that may establish it's own \texttt{RNGScope} (such
@@ -517,7 +517,7 @@
Note that while the \texttt{Rcpp::depends} attribute establishes dependencies
for \texttt{sourceCpp}, it's important to note that if you include the same
-source file in an \proglang{R} package these dependencies must still be
+source file in an \proglang{R} package these dependencies must still be
listed in the \texttt{Depends} and \texttt{LinkingTo} fields of the package
\texttt{DESCRIPTION} file.
@@ -527,10 +527,10 @@
Maintaining C++ code in it's own source file provides several benefits including
the ability to use \proglang{C++} aware text-editing tools and straightforward
mapping of compilation errors to lines in the source file. However, it's also
-possible to do inline declaration and execution of C++ code.
+possible to do inline declaration and execution of C++ code.
There are several ways to accomplish this, including passing a code
-string to \texttt{sourceCpp} or using the shorter-form \texttt{cppFunction}
+string to \texttt{sourceCpp} or using the shorter-form \texttt{cppFunction}
or \texttt{evalCpp} functions. For example:
% \begin{verbatim}
@@ -600,11 +600,11 @@
\subsection{Package Creation}
-To create a package that is based on \pkg{Rcpp} you should follow the
+To create a package that is based on \pkg{Rcpp} you should follow the
guidelines in the `\textsl{Rcpp-package}' vignette. For a new package this
is most conveniently done using the \texttt{Rcpp.package.skeleton} function.
-To generate a new package with a simple hello, world function that uses
+To generate a new package with a simple hello, world function that uses
attributes you can do the following:
% \begin{verbatim}
@@ -641,7 +641,7 @@
Once you've migrated \proglang{C++} code into a package, the dependencies for
source files are derived from the \texttt{Depends} and \texttt{LinkingTo} fields
in the package \texttt{DESCRIPTION} file rather than the \texttt{Rcpp::depends}
-attribute. For every package you import C++ code from (including \pkg{Rcpp})
+attribute. For every package you import C++ code from (including \pkg{Rcpp})
you need to add these entries.
For example, if your package depends on \pkg{Rcpp} and \pkg{RcppArmadillo}
@@ -664,7 +664,7 @@
\subsection{Exporting R Functions}
Within interactive sessions you call the \texttt{sourceCpp} function
-on individual files to export \proglang{C++} functions into the global
+on individual files to export \proglang{C++} functions into the global
environment. However, for packages you call a single utility function to
export all \proglang{C++} functions within the package.
@@ -696,13 +696,13 @@
the \texttt{extern "C"} functions defined in \texttt{RcppExports.cpp}.
\end{itemize}
-You should re-run \texttt{compileAttributes} whenever functions are added,
+You should re-run \texttt{compileAttributes} whenever functions are added,
removed, or have their signatures changed.
The \texttt{compileAttributes} function deals only with exporting
-\proglang{C++} functions to \proglang{R}. If you want the functions to
-additionally be publicly available from your package's namespace another
-step may be required. Specifically, if your package \texttt{NAMESPACE} file
+\proglang{C++} functions to \proglang{R}. If you want the functions to
+additionally be publicly available from your package's namespace another
+step may be required. Specifically, if your package \texttt{NAMESPACE} file
does not use a pattern to export functions then you should add an explicit
entry to \texttt{NAMESPACE} for each R function you want publicly available.
@@ -767,10 +767,10 @@
\proglang{R} functions. However, the \proglang{R} package system also provides
a mechanism to allow the exporting of \proglang{C} and \proglang{C++}
interfaces using package header files. This is based on the
-\texttt{R\_RegisterCCallable} and \texttt{R\_GetCCallable} functions described in
+\texttt{R\_RegisterCCallable} and \texttt{R\_GetCCallable} functions described in
`\textsl{Writing R Extensions}' \citep{R:Extensions}.
-\proglang{C++} interfaces to a package are published within the
+\proglang{C++} interfaces to a package are published within the
top level \texttt{include} directory of the package (which within the package
source directory is located at \texttt{inst/include}). The \proglang{R} build
system automatically adds the required \texttt{include} directories for all
@@ -779,12 +779,12 @@
\subsubsection{Interfaces Attribute}
-The \texttt{Rcpp::interfaces} attribute can be used to automatically
+The \texttt{Rcpp::interfaces} attribute can be used to automatically
generate a header-only interface to your \proglang{C++} functions
within the \texttt{include} directory of your package.
The \texttt{Rcpp::interfaces} attribute is specified on a per-source
-file basis, and indicates which interfaces (\proglang{R}, \proglang{C++},
+file basis, and indicates which interfaces (\proglang{R}, \proglang{C++},
or both) should be provided for exported functions within the file.
For example, the following specifies that both R and \proglang{C++} interfaces
@@ -809,7 +809,7 @@
\subsubsection{Generated Code}
If you request a \texttt{cpp} interface for a source file then
-\texttt{compileAttributes} generates the following header files
+\texttt{compileAttributes} generates the following header files
(substituting \emph{Package} with the name of the package code is being
generated for):
@@ -827,14 +827,14 @@
\normalsize
\end{kframe}
-The \texttt{Package\_RcppExports.h} file has inline definitions for all
+The \texttt{Package\_RcppExports.h} file has inline definitions for all
exported \proglang{C++} functions that enable calling them using the
-\texttt{R\_GetCCallable} mechanism.
+\texttt{R\_GetCCallable} mechanism.
The \texttt{Package.h} file does nothing other than include the
-\texttt{Package\_RcppExports.h} header. This is done so
+\texttt{Package\_RcppExports.h} header. This is done so
that package authors can replace the \texttt{Package.h} header with
-a custom one and still be able to include the automatically generated exports
+a custom one and still be able to include the automatically generated exports
(details on doing this are provided in the next section).
The exported functions are defined within a \proglang{C++} namespace that matches
@@ -869,23 +869,23 @@
\subsubsection{Including Additional Code}
You might wish to use the \texttt{Rcpp::interfaces} attribute to generate
-a part of your package's \proglang{C++} interface but also provide
-additional custom \proglang{C++} code. In this case you
-should replace the generated \texttt{Package.h} file with one of your own.
+a part of your package's \proglang{C++} interface but also provide
+additional custom \proglang{C++} code. In this case you
+should replace the generated \texttt{Package.h} file with one of your own.
Note that the way \pkg{Rcpp} distinguishes user verses generated files is by checking
for the presence a special token in the file (if it's present then it's known
to be generated and thus safe to overwrite). You'll see this token at the top
-of the generated \texttt{Package.h} file, be sure to remove it if you want
+of the generated \texttt{Package.h} file, be sure to remove it if you want
to provide a custom header.
-Once you've established a custom package header file, you need only include the
-\texttt{Package\_RcppExports.h} file within your header to make available
+Once you've established a custom package header file, you need only include the
+\texttt{Package\_RcppExports.h} file within your header to make available
the automatically generated code alongside your own.
-If you need to include code from your custom header files within the
+If you need to include code from your custom header files within the
compilation of your package source files, you will also need to add the
-following entry to \texttt{Makevars} and \texttt{Makevars.win} (both are
+following entry to \texttt{Makevars} and \texttt{Makevars.win} (both are
in the \texttt{src} directory of your package):
% \begin{verbatim}
More information about the Rcpp-commits
mailing list