[Rcpp-commits] r1202 - in pkg/Rcpp/inst/announce: . html
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed May 12 10:07:36 CEST 2010
Author: romain
Date: 2010-05-12 10:07:35 +0200 (Wed, 12 May 2010)
New Revision: 1202
Added:
pkg/Rcpp/inst/announce/html/
pkg/Rcpp/inst/announce/html/ANNOUNCE-0.8.0.html
Log:
add an html version of the announce, for blogs, etc ...
Added: pkg/Rcpp/inst/announce/html/ANNOUNCE-0.8.0.html
===================================================================
--- pkg/Rcpp/inst/announce/html/ANNOUNCE-0.8.0.html (rev 0)
+++ pkg/Rcpp/inst/announce/html/ANNOUNCE-0.8.0.html 2010-05-12 08:07:35 UTC (rev 1202)
@@ -0,0 +1,346 @@
+
+<h2>Summary</h2>
+
+<p>Version 0.8.0 of the <a href="http://dirk.eddelbuettel.com/code/rcpp.html">Rcpp</a> package was released to CRAN today. This release marks another milestone in the ongoing redesign of the package, and
+underlying C++ library.</p>
+
+
+<h2>Overview</h2>
+
+<p>Rcpp is an R package and C++ library that facilitates integration of C++
+code in R packages. </p>
+
+<p>The package features a set of C++ classes (<strong>Rcpp::IntegerVector,
+Rcpp::Function, Rcpp::Environment, </strong>...) that makes it easier to manipulate R
+objects of matching types (integer vectors, functions, environments, etc
+...).
+</p>
+
+<p>Rcpp takes advantage of C++ language features such as the explicit
+constructor/destructor lifecycle of objects to manage garbage collection
+automatically and transparently. We believe this is a major improvement over
+<strong>PROTECT/UNPROTECT</strong>. When an Rcpp object is created, it protects the underlying
+SEXP so that the garbage collector does not attempt to reclaim the
+memory. This protection is withdrawn when the object goes out of
+scope. Moreover, users generally do not need to manage memory directly (via
+calls to new / delete or malloc / free) as this is done by the Rcpp classes
+or the corresponding STL containers.
+</p>
+
+<h2>API</h2>
+
+<p>Rcpp provides two APIs: an older set of classes we refer to the classic API
+(see below for the section 'Backwards Compatibility) as well as second and
+newer set of classes.
+</p>
+
+<p>Classes of the new Rcpp API belong to the Rcpp namespace. Each class is
+associated to a given SEXP type and exposes an interface that allows
+manipulation of the object that may feel more natural than the usual use of
+macros and functions provided by the R API.
+</p>
+
+<pre>
+----------------------------------------------------------
+SEXP type | Rcpp class
+----------------------------------------------------------
+INTSXP | Rcpp::IntegerVector
+REALSXP | Rcpp::NumericVector
+RAWSXP | Rcpp::RawVector
+LGLSXP | Rcpp::LogicalVector
+CPLXSXP | Rcpp::ComplexVector
+STRSXP | Rcpp::CharacterVector
+VECSXP | Rcpp::List
+EXPRSXP | Rcpp::ExpressionVector
+----------------------------------------------------------
+ENVSXP | Rcpp::Environment
+SYMSXP | Rcpp::Symbol
+----------------------------------------------------------
+CLOSXP |
+BUILTINSXP | Rcpp::Function
+SPECIALSXP |
+----------------------------------------------------------
+LANGSXP | Rcpp::Language
+LISTSXP | Rcpp::Pairlist
+----------------------------------------------------------
+S4SXP | Rcpp::S4
+----------------------------------------------------------
+PROMSXP | Rcpp::Promise
+WEAKREFSXP | Rcpp::WeakReference
+EXTPTRSXP | template <typename T> Rcpp::XPtr
+----------------------------------------------------------
+</pre>
+
+<p>Some SEXP types do not have dedicated Rcpp classes : <strong>NILSXP, DOTSXP,
+ANYSXP, BCODESXP and CHARSXP</strong>. </p>
+
+<p>Still missing are a few convenience classes such as Rcpp::Date or
+Rcpp::Datetime which would map useful and frequently used R data types, but
+which do not have an underlying SEXP type.</p>
+
+
+<h2>Data Interchange</h2>
+
+<p>Data interchange between R and C++ is managed by extensible and powerful yet
+simple mechanisms.</p>
+
+<p>Conversion of a C++ object is managed by the template function <strong>Rcpp::wrap</strong>.
+This function currently manages :
+<ul>
+<li>primitive types : int, double, bool, float, Rbyte, ...</li>
+<li>std::string, const char*</li>
+<li>STL containers such as std::vector<T> and STL maps such as
+ std::mapr< std::string, Tr> provided that the template type T is wrappable </li>
+ <li>any class that can be implicitely converted to SEXP, through operator SEXP()</li>
+</ul>
+</p>
+
+
+<p>Conversion of an R object to a C++ object is managed by the Rcpp::as<T>
+template which can handle:
+<ul>
+<li>primitive types</li>
+<li>std::string, const char* </li>
+<li>STL containers such as std::vector<T></li>
+</ul>
+</p>
+
+<p><strong>Rcpp::wrap</strong> and <strong>Rcpp::as</strong> are often used implicitely. For example, when
+assigning objects to an environment:</p>
+
+
+<pre>
+ // grab the global environment
+ Rcpp::Environment global = Rcpp::Environment::global_env() ;
+ std::deque<bool> z( 3 ); z[0] = false; z[1] = true; z[3] = false ;
+
+ global["x"] = 2 ; // implicit call of wrap<int>
+ global["y"] = "foo"; // implicit call of wrap<char*>
+ global["z"] = z ; // impl. call of wrap<std::deque<bool>>
+
+ int x = global["x"] ; // implicit call of as<int>
+ std::string y = global["y"] // implicit call of as<std::string>
+ std::vector<bool> z1 = global["z"] ; // impl. call of as<std::vector<bool>>
+</pre>
+
+<p>
+Rcpp contains several examples that illustrate wrap and as. The mechanism was
+designed to be extensible. We have developped separate packages to illustrate
+how to extend Rcpp conversion mechanisms to third party types.
+<ul>
+<li>RcppArmadillo : conversion of types from the Armadillo C++ library. </li>
+<li>RcppGSL : conversion of types from the GNU Scientific Library. </li>
+</ul>
+</p>
+
+<p>Rcpp is also used for data interchange by the <a href="http://dirk.eddelbuettel.com/code/rinside.html">RInside</a> package which provides
+and easy way of embedding an R instance inside of C++ programs.</p>
+
+
+<h2>inline use</h2>
+
+<p>Rcpp depends on the <a href="http://cran.r-project.org/web/packages/inline/index.html">inline</a> package by Oleg Sklyar et al. Rcpp then uses the
+'cfunction' provided by inline (with argument Rcpp=TRUE) to compile, link and
+load C++ function from the R session.</p>
+
+<p>As of version 0.8.0 of Rcpp, we also define an R function <strong>cppfunction</strong> that
+acts as a facade function to the <a href="http://finzi.psych.upenn.edu/R/library/inline/html/cfunction.html">inline::cfuntion</strong>, with specialization for
+C++ use.</p>
+
+<p>This allows quick prototyping of compiled code. All our unit tests are based
+on cppfunction and can serve as examples of how to use the mechanism. For example
+this function (from the runit.GenericVector.R unit test file) defines from
+R a C++ (simplified) version of <a href="http://finzi.psych.upenn.edu/R/library/base/html/lapply.html">lapply</a>: </p>
+
+<pre>
+ ## create a compiled function cpp_lapply using cppfunction
+ cpp_lapply <- cppfunction(signature(x = "list", g = "function" ),
+ 'Function fun(g) ;
+ List input(x) ;
+ List output( input.size() ) ;
+ std::transform( input.begin(), input.end(), output.begin(), fun ) ;
+ output.names() = input.names() ;
+ return output ;
+ ')
+ ## call cpp_lapply on the iris data with the R function summary
+ cpp_lapply( iris, summary )
+</pre>
+
+<h2>Using Rcpp in other packages</h2>
+
+<p>Rcpp is designed so that its classes are used from other packages. Using Rcpp
+requires :
+<ul>
+<li>using the header files provided by Rcpp. This is typically done by adding this
+ line in the package DESRIPTION file:
+
+<pre>
+ LinkingTo: Rcpp
+</pre>
+
+ and add the following line in the package code:
+
+<pre>
+ #include <Rcpp.h>
+</pre>
+</li>
+
+<li>linking against the Rcpp dynamic or static library, which is achieved by
+ adding this line to the src/Makevars of the package:
+
+<pre>
+ PKG_LIBS = $(shell $(R_HOME)/bin/Rscript -e "Rcpp:::LdFlags()" )
+</pre>
+
+ and this line to the src/Makevars.win file:
+
+<pre>
+ PKG_LIBS = $(shell Rscript.exe -e "Rcpp:::LdFlags()")
+</pre>
+</li>
+</ul>
+
+<p>Rcpp contains a function <a href="http://finzi.psych.upenn.edu/R/library/Rcpp/html/Rcpp.package.skeleton.html">Rcpp.package.skeleton</a>, modelled after
+<a href="http://finzi.psych.upenn.edu/R/library/utils/html/package.skeleton.html">package.skeleton</a> from the utils package in base r, that creates a skeleton of
+a package using Rcpp, including example code.</p>
+
+
+<h2> C++ exceptions</h2>
+
+<p>C++ exceptions are R contexts are both based on non local jumps (at least
+on the implementation of exceptions in gcc), so care must be ensure
+that one system does not void assumptions of the other. It is therefore
+very strongly recommended that each function using C++ catches
+C++ exceptions. Rcpp offers the function forward_exception_to_r
+to facilitate forwarding the exception to the "R side" as an R condition.
+For example :
+</p>
+
+<pre>
+ SEXP foo( ) {
+ try {
+ // user code here
+ } catch( std::exception& __ex__){
+ forward_exception_to_r( __ex__ ) ;
+ }
+ // return something here
+ }
+</pre>
+
+<p>
+Alternatively, functions can enclose the user code with the macros <strong>BEGIN_RCPP</strong>
+and <strong>END_RCPP</strong>, which provides for a more compact way of programming. The
+function above could be written as follows using the macros:
+
+<pre>
+ SEXP foo( ) {
+ BEGIN_RCPP
+ // user code here
+ END_RCPP
+ // return something here
+ }
+</pre>
+
+<p>The use of <strong>BEGIN_RCPP</strong> and <strong>END_RCPP</strong> is recommended to anticipate future changes of Rcpp. We might for example decide to install dedicated handlers for specific
+exceptions later.</p>
+
+
+<h2>Experimental code generation macros</h2>
+
+<p>Rcpp contains several macros that can generate repetitive 'boiler plate' code:</p>
+
+<pre>
+ RCPP_FUNCTION_0, ..., RCPP_FUNCTION_65
+ RCPP_FUNCTION_VOID_0, ..., RCPP_FUNCTION_VOID_65
+ RCPP_XP_METHOD_0, ..., RCPP_XP_METHOD_65
+ RCPP_XP_METHOD_CAST_0, ..., RCPP_XP_METHOD_CAST_65
+ RCPP_XP_METHOD_VOID_0, ..., RCPP_XP_METHOD_VOID_65
+</pre>
+
+<p>For example: </p>
+
+<pre>
+ RCPP_FUNCTION_2( int, foobar, int x, int y){
+ return x + y ;
+ }
+</pre>
+
+<p>This will create a <a href="http://finzi.psych.upenn.edu/R/library/base/html/Foreign.html">.Call</a> compatible function "foobar" that calls a
+c++ function for which we provide the argument list (int x, int y)
+and the return type (int). The macro also encloses the call
+in BEGIN_RCPP/END_RCPP so that exceptions are properly forwarded to R.</p>
+
+<p>Examples of the other macros are given in the NEWS file.</p>
+
+<p><strong>This feature is still experimenta</strong>l, but is being used in packages
+<a href="http://romainfrancois.blog.free.fr/index.php?category/R-package/highlight">highlight</a> and <a href="http://dirk.eddelbuettel.com/code/rprotobuf.html">RProtoBuf</a></p>
+
+
+<h2>Quality Assurance</h2>
+
+<p>Rcpp uses the <a href="http://sourceforge.net/projects/runit/">RUnit</a> package by Matthias Burger et al and the aforementioned
+<a href="http://cran.r-project.org/web/packages/inline/index.html">inline</a> package by Oleg Sklyar et al to provide unit testing. Rcpp currently
+has over 230 unit test functions with very good coverage of the critical
+parts of the package and library.</p>
+
+<p>Source code for unit test functions are stored in the unitTests directory
+of the installed package and the results are collected in the "Rcpp-unitTests"
+vignette. </p>
+
+<p>The unit tests can be both during the standard R package build and testing
+process, and also when the package is installed. The latter use is helpful
+to ensure that no system components have changed in a way that affect the
+Rcpp package since it has been installed. To run the tests, execute
+<p>
+
+<pre>
+ Rcpp:::test()
+</pre>
+
+<p>where an output directory can be provided as an optional first argument.</p>
+
+
+<h2>Backwards Compatibility</h2>
+
+<p>We believe the new API is now more complete and useful than the previous set
+of classes, which we refer to as the "classic Rcpp API". We would therefore
+recommend to package authors using 'classic' Rcpp to move to the new API.
+However, the classic API is still maintained and will continue to be
+maintained to ensure backwards compatibility for code that uses it.
+</p>
+
+<p>Packages uses the 'Classic API' can use features of the new API selectively
+and in incremental steps. This provides for a non-disruptive upgrade path.</p>
+
+
+<h2>Documentation</h2>
+
+The package contains a vignette which provides a short and succinct
+introduction to the Rcpp package along with several motivating examples.
+Also provided is a vignette containing the regression test summary from
+the time the package was built.
+
+
+<h2>Links</h2>
+
+<ul>
+<li>
+Rcpp main page: <a href="http://dirk.eddelbuettel.com/code/rcpp.html">http://dirk.eddelbuettel.com/code/rcpp.html</a>
+</li>
+<li>R-forge project page: <a href="http://r-forge.r-project.org/projects/rcpp/">http://r-forge.r-project.org/projects/rcpp/</a></li>
+<li>Dirk's blog section about Rcpp: <a href="http://dirk.eddelbuettel.com/blog/code/rcpp/">http://dirk.eddelbuettel.com/blog/code/rcpp/</a></li>
+<li>Romain's blog section about Rcpp: <a href="http://romainfrancois.blog.free.fr/index.php?category/R-package/Rcpp">http://romainfrancois.blog.free.fr/index.php?category/R-package/Rcpp</a></li>
+</ul>
+
+
+<h2> Support</h2>
+
+<p>Questions about Rcpp should be directed to the <a href="https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/rcpp-devel">Rcpp-devel</a> mailing list
+</p>
+
+<pre>
+ -- Dirk Eddelbuettel and Romain Francois
+ Chicago, IL, USA, and Montpellier, France
+ May 2010
+</pre>
+
More information about the Rcpp-commits
mailing list