[Rcpp-commits] r1476 - pkg/Rcpp/inst/doc/Rcpp-extending

noreply at r-forge.r-project.org noreply at r-forge.r-project.org
Mon Jun 7 16:55:07 CEST 2010


Author: edd
Date: 2010-06-07 16:55:07 +0200 (Mon, 07 Jun 2010)
New Revision: 1476

Modified:
   pkg/Rcpp/inst/doc/Rcpp-extending/Rcpp-extending.Rnw
Log:
some small edits


Modified: pkg/Rcpp/inst/doc/Rcpp-extending/Rcpp-extending.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-extending/Rcpp-extending.Rnw	2010-06-07 14:15:46 UTC (rev 1475)
+++ pkg/Rcpp/inst/doc/Rcpp-extending/Rcpp-extending.Rnw	2010-06-07 14:55:07 UTC (rev 1476)
@@ -78,28 +78,29 @@
 
 \abstract{
   \noindent
-  This note gives an overview of the mechanics programmers should follow to 
-  extend \pkg{Rcpp} \citep{CRAN:Rcpp} with their own classes. This document
-  is based on our experience to extending \pkg{Rcpp} to work with 
+  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 to extending \pkg{Rcpp} to work with the
   Armadillo \citep{Armadillo} classes, available in the separate package
-  \pkg{RcppArmadillo} \citep{CRAN:RcppArmadillo}. This document assumes 
+  \pkg{RcppArmadillo} \citep{CRAN:RcppArmadillo}. This document assumes
   knowledge of \pkg{Rcpp} as well as some knowledge of \proglang{C++}
   templates.
   }
 
-  
+
 \section{Introduction}
 
-\pkg{Rcpp} pilots data interchange between \proglang{R} and \proglang{C++}
-through the templates \texttt{Rcpp::wrap} and \texttt{Rcpp::as} whose 
-declarations are : 
+\pkg{Rcpp} facilitates data interchange between \proglang{R} and \proglang{C++}
+through the templates \texttt{Rcpp::as} (for conversion from \proglang{C++}) and
+\texttt{Rcpp::wrap} (for conversion to \proglang{C++}).
+Their 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) ;
-
-// conversion from R to C++
-template <typename T> T as( SEXP m_sexp) throw(not_compatible) ;
 @
 
 These converters are often used implicitely, as in the following code chunk:
@@ -115,8 +116,8 @@
 
 // return an R list
 // this is achieved through implicit call to Rcpp::wrap
-return List::create( 
-    _["front"] = x.front(), 
+return List::create(
+    _["front"] = x.front(),
     _["back"]  = x.back()
     ) ;
 '
@@ -127,32 +128,32 @@
 @
 
 <<>>=
-fx <- cxxfunction( signature( input_ = "list"), 
-	paste( readLines( "code.cpp" ), collapse = "\n" ), 
+fx <- cxxfunction( signature( input_ = "list"),
+	paste( readLines( "code.cpp" ), collapse = "\n" ),
 	plugin = "Rcpp"
 	)
 input <- list( x = seq(1, 10, by = 0.5) )
 fx( input )
 @
 
-\pkg{Rcpp} converters \texttt{Rcpp::as} and \texttt{Rcpp::wrap} have been 
-designed to be extensible to user defined types and third party types.
+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. 
+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 to 
-let \texttt{Rcpp::wrap} know about them is to implement a conversion to 
-\texttt{SEXP}. The template meta programming dispatch is able to recognize that
-a type is convertible to a \texttt{SEXP} and \texttt{Rcpp::wrap} will use
-that conversion. 
+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 (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. 
+The caveat is that the type must be declared before the main header
+file \texttt{Rcpp.h} is included.
 
 <<lang=cpp>>=
 #include <RcppCommon.h>
@@ -160,7 +161,7 @@
 class Foo{
     public:
         Foo() ;
-        
+
         // this operator enables implicit Rcpp::wrap
         operator SEXP() ;
 }
@@ -169,17 +170,17 @@
 @
 
 This is called \emph{intrusive} because the conversion to \texttt{SEXP}
-operator has to be declared within the class. 
+operator has to be declared within the class.
 
-\subsection{Non intrusive extension}
+\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. 
+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
-\texttt{RcppCommon.h} and \texttt{Rcpp.h} includes. 
+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>
@@ -191,21 +192,21 @@
 namespace Rcpp{
     template <> SEXP wrap( const Bar& ) ;
 }
-                                
-// this must appear after the specialization, 
+
+// 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 
+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: 
+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>
@@ -215,12 +216,12 @@
 
 // declaring the partial specialization
 namespace Rcpp{ namespace traits {
-    
+
     template <typename T> SEXP wrap( const Bling<T>& ) ;
 
 } }
-                                
-// this must appear after the specialization, 
+
+// this must appear after the specialization,
 // otherwise the specialization will not be seen by Rcpp types
 #include <Rcpp.h>
 
@@ -229,13 +230,13 @@
 
 \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. 
+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}. 
+will attempt to use the constructor of the target class taking a \texttt{SEXP}.
 
 <<lang=cpp>>=
 #include <RcppCommon.h>
@@ -245,7 +246,7 @@
 class Foo{
     public:
         Foo() ;
-        
+
         // this constructor enables implicit Rcpp::as
         Foo(SEXP) ;
 }
@@ -253,14 +254,14 @@
 #include <Rcpp.h>
 
 
-// this must appear after the specialization, 
+// 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 
+It is also possible to fully specialize \texttt{Rcpp::as} to enable
 non intrusive implicit conversion capabilities.
 
 <<lang=cpp>>=
@@ -273,19 +274,19 @@
 namespace Rcpp{
     template <> Bar as( SEXP ) throw(not_compatible) ;
 }
-                                
-// this must appear after the specialization, 
+
+// 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 
+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 
+and delegate the conversion to this class. \pkg{Rcpp} defines
 the \texttt{Rcpp::traits::Exporter} template class as follows :
 
 <<lang=cpp>>=
@@ -295,7 +296,7 @@
     public:
         Exporter( SEXP x ) : t(x){}
         inline T get(){ return t ; }
-    
+
     private:
         T t ;
     } ;
@@ -303,7 +304,7 @@
 } }
 @
 
-This is the reason why the default behavior of \texttt{Rcpp::as} is to 
+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
@@ -319,17 +320,17 @@
 namespace Rcpp{ namespace traits {
     template <typename T> class Exporter< Bling<T> >;
 } }
-                                
-// this must appear after the specialization, 
+
+// this must appear after the specialization,
 // otherwise the specialization will not be seen by Rcpp types
 #include <Rcpp.h>
 @
 
-Using this approach, the requirements on the \texttt{Exporter< Bling<T> >}
+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 
+\item it should have a methods called \texttt{get} that returns an instance
 of the \texttt{Bling<T>} type.
 \end{itemize}
 



More information about the Rcpp-commits mailing list