[Rcpp-commits] r1128 - in pkg/Rcpp/inst: announce unitTests
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Apr 28 12:29:23 CEST 2010
Author: romain
Date: 2010-04-28 12:29:22 +0200 (Wed, 28 Apr 2010)
New Revision: 1128
Added:
pkg/Rcpp/inst/announce/ANNOUNCE-0.8.0.txt
Modified:
pkg/Rcpp/inst/announce/ANNOUNCE-0.7.0.txt
pkg/Rcpp/inst/unitTests/runit.GenericVector.R
Log:
draft for ANNOUNCE-0.8.0
Modified: pkg/Rcpp/inst/announce/ANNOUNCE-0.7.0.txt
===================================================================
--- pkg/Rcpp/inst/announce/ANNOUNCE-0.7.0.txt 2010-04-28 08:59:46 UTC (rev 1127)
+++ pkg/Rcpp/inst/announce/ANNOUNCE-0.7.0.txt 2010-04-28 10:29:22 UTC (rev 1128)
@@ -1,4 +1,4 @@
-cpp version 0.7.0 went onto CRAN this weekend. The key new features are
+Rcpp version 0.7.0 went onto CRAN this weekend. The key new features are
o inline support, taken from Oleg Sklyar's neat inline package and
adapted/extented to support Rcpp as well as external libraries
Added: pkg/Rcpp/inst/announce/ANNOUNCE-0.8.0.txt
===================================================================
--- pkg/Rcpp/inst/announce/ANNOUNCE-0.8.0.txt (rev 0)
+++ pkg/Rcpp/inst/announce/ANNOUNCE-0.8.0.txt 2010-04-28 10:29:22 UTC (rev 1128)
@@ -0,0 +1,206 @@
+
+Rcpp version 0.8.0 was released to CRAN today. This is a major redesign
+of the package, and underlying c++ library
+
+===== outline =====
+
+Rcpp is an R package and C++ library that facilitates integration of C++
+code in R packages.
+
+The package features a set of C++ classes (Rcpp::IntegerVector, Rcpp::Function,
+Rcpp::Environment, ...) that facilitate manipulation of R objects of matching
+types (integer vectors, functions, environments, etc ...).
+
+Rcpp takes advantage of C++ explicit constructor/destructor lifecycle of
+objects to manage garbage collection automatically and transparently. We
+believe this is a major improvement over PROTECT/UNPROTECT. 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.
+
+===== API =====
+
+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 feels more natural than the usual use of macros and functions
+provided by the R API.
+
+----------------------------------------------------------
+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
+----------------------------------------------------------
+
+Some SEXP types don't have dedicated Rcpp classes : NILSXP, DOTSXP, DOTSXP,
+ANYSXP, BCODESXP and CHARSXP.
+
+
+===== Data interchange =====
+
+Data interchange between R and C++ is managed by extensible
+and powerful yet simple mechanisms.
+
+Conversion of a C++ object is managed by the template function Rcpp::wrap. wrap
+currently manages :
+- primitive types : int, double, bool, float, Rbyte, ...
+- std::string, const char*
+- STL containers such as std::vector<T>, given that the type T is wrappable
+- STL maps such as std::map< std::string, T> given that the type T is wrappable
+- any class that can be implicitely converted to SEXP, through operator SEXP()
+
+Conversion of an R object to a C++ object is managed by the Rcpp::as<T> template
+which can handle:
+- primitive types
+- std::string, const char*
+- STL containers such as std::vector<T>
+
+Rcpp::wrap and Rcpp::as are often used implicitely. For example, when assigning
+objects to an environment:
+
+// 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 ; // implicit 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"] ; // implicit call of as< std::vector<bool> >
+
+
+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.
+- RcppArmadillo : conversion of types from the armadillo c++ library.
+- RcppGSL : conversion of types from the GNU scientific library.
+
+
+===== inline use =====
+
+Rcpp depends on the inline package, and defines an R function cppfunction
+that acts as a facade function to the inline::cfuntion, with specialization
+for C++ use.
+
+This allows quick prototyping of compiled code. Our entire 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 lapply:
+
+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 ;
+ ' )
+cpp_lapply( iris, summary )
+
+
+
+===== Using Rcpp in other package =====
+
+Rcpp is designed so that its classes are used from other packages. Using Rcpp
+requires :
+- using the header files provided by Rcpp. This is typically done by adding this
+ line in the package DESRIPTION file:
+
+LinkingTo: Rcpp
+
+ and add the following line in the package code:
+
+#include <Rcpp.h>
+
+- linking against the Rcpp dynamic or static library, which is achieved by
+ adding this line to the src/Makevars of the package:
+
+PKG_LIBS = $(shell $(R_HOME)/bin/Rscript -e "Rcpp:::LdFlags()" )
+
+ and this line to the src/Makevars.win file:
+
+PKG_LIBS = $(shell Rscript.exe -e "Rcpp:::LdFlags()")
+
+
+Rcpp contains a function Rcpp.package.skeleton, modelled after package.skeleton
+from the utils package, that creates a skeleton of a package using Rcpp,
+including example code.
+
+
+===== C++ exceptions =====
+
+Rcpp forwards exceptions as R conditions using the C++ function
+"forward_exception_to_r". For example :
+
+SEXP foo( ){
+ try{
+ // user code
+ } catch( std::exception& __ex__){
+ forward_exception_to_r( __ex__ ) ;
+ }
+}
+
+Alternatively, functions can enclose the user code with the macros BEGIN_RCPP
+and END_RCPP, which is the recommended way.
+
+SEXP foo( ){
+ BEGIN_RCPP
+ // user code
+ END_RCPP
+}
+
+
+===== Quality Assurance =====
+
+Rcpp uses the packages RUnit and inline to manage unit tests of Rcpp. Rcpp
+currently has over 200 unit test functions with very good coverage.
+
+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.
+
+
+===== Backwards compatibility =====
+
+We believe the new API is much better than the previous set of classes,
+which we now call the "classic Rcpp api", therefore we recommend package
+authors that use 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 used it.
+
+
+===== Links =====
+
+Rcpp main page: http://dirk.eddelbuettel.com/code/rcpp.html
+Dirk's blog section about Rcpp: http://dirk.eddelbuettel.com/blog/code/rcpp/
+Romain's blog section about Rcpp: http://romainfrancois.blog.free.fr/index.php?category/R-package/Rcpp
+
+===== Support =====
+
+Questions about Rcpp should be directed to the Rcpp-devel mailing list
+https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/rcpp-devel
+
Modified: pkg/Rcpp/inst/unitTests/runit.GenericVector.R
===================================================================
--- pkg/Rcpp/inst/unitTests/runit.GenericVector.R 2010-04-28 08:59:46 UTC (rev 1127)
+++ pkg/Rcpp/inst/unitTests/runit.GenericVector.R 2010-04-28 10:29:22 UTC (rev 1128)
@@ -121,7 +121,6 @@
std::transform( input.begin(), input.end(), output.begin(), fun ) ;
output.names() = input.names() ;
return output ;
-
' )
data <- list( x = letters, y = LETTERS, z = 1:4 )
More information about the Rcpp-commits
mailing list