Mon, 17 May 2010

Rcpp 0.8.0

Romain and I are happy to announce the release of Rcpp version 0.8.0. It has been uploaded to CRAN. A Debian upload is delayed until the now-required inline package is accepted into Debian. The source package is also available from here.

This release brings a number of changes that are detailed below. Of particular interest may be the much more robust treatment of exceptions, the new classes for data frames and formulae, and the availability of the new helper function cppfunction for use with inline. Also of note is the new support for the 'LinkingTo' directive with which packages using Rcpp will get automatic access to the header files.

An announcement email went to the r-packages list (ETH Zuerich, Gmane); Romain also blogged about the release.

The full NEWS entry for this release follows below:

0.8.0   2010-05-17

    o   All Rcpp headers have been moved to the inst/include directory,
	allowing use of 'LinkingTo: Rcpp'. But the Makevars and Makevars.win
	are still needed to link against the user library.

    o   Automatic exception forwarding has been withdrawn because of
	portability issues (as it did not work on the Windows platform).
	Exception forwarding is still possible but is now based on explicit
	code of the form:
	
	  try {
	    // user code
	  } catch( std::exception& __ex__){ 
	    forward_exception_to_r( __ex___ ) ;
	  }
	
	Alternatively, the macro BEGIN_RCPP and END_RCPP can use used to enclose
	code so that it captures exceptions and forward them to R. 
	
	  BEGIN_RCPP
	  // user code
	  END_RCPP
	
    o   new __experimental__ macros 
	
	The macros RCPP_FUNCTION_0, ..., RCPP_FUNCTION_65 to help creating C++
	functions hiding some code repetition: 
	
	  RCPP_FUNCTION_2( int, foobar, int x, int y){
	    return x + y ;
	  }

	The first argument is the output type, the second argument is the 
	name of the function, and the other arguments are arguments of the C++ 
	function. Behind the scenes, the RCPP_FUNCTION_2 macro creates 
	an intermediate function compatible with the .Call interface and handles 
	exceptions
	
	Similarly, the macros RCPP_FUNCTION_VOID_0, ..., RCPP_FUNCTION_VOID_65 
	can be used when the C++ function to create returns void. The generated
	R function will return R_NilValue in this case.
	
	  RCPP_FUNCTION_VOID_2( foobar, std::string foo ){
	    // do something with foo
	  }

	  
	The macro RCPP_XP_FIELD_GET generates a .Call compatible function that
	can be used to access the value of a field of a class handled by an 
	external pointer. For example with a class like this: 
	
	  class Foo{
		public:
			int bar ;
	  }
	
	  RCPP_XP_FIELD_GET( Foo_bar_get, Foo, bar ) ;
	  
	RCPP_XP_FIELD_GET will generate the .Call compatible function called
	Foo_bar_get that can be used to retrieved the value of bar.
	
	
	The macro RCPP_FIELD_SET generates a .Call compatible function that 
	can be used to set the value of a field. For example:
	
	  RCPP_XP_FIELD_SET( Foo_bar_set, Foo, bar ) ;
	
	generates the .Call compatible function called "Foo_bar_set" that 
	can be used to set the value of bar
	
	
	The macro RCPP_XP_FIELD generates both getter and setter. For example
	
	  RCPP_XP_FIELD( Foo_bar, Foo, bar )
	  
	generates the .Call compatible Foo_bar_get and Foo_bar_set using the 
	macros RCPP_XP_FIELD_GET and RCPP_XP_FIELD_SET previously described
	
	  
	The macros RCPP_XP_METHOD_0, ..., RCPP_XP_METHOD_65 faciliate 
	calling a method of an object that is stored in an external pointer. For 
	example: 
	
	  RCPP_XP_METHOD_0( foobar, std::vector , size )
	
	creates the .Call compatible function called foobar that calls the
	size method of the std::vector class. This uses the Rcpp::XPtr<
	std::vector > class.
	
	The macros RCPP_XP_METHOD_CAST_0, ... is similar but the result of
	the method called is first passed to another function before being
	wrapped to a SEXP.  For example, if one wanted the result as a double
	
	   RCPP_XP_METHOD_CAST_0( foobar, std::vector , size, double )
	
	The macros RCPP_XP_METHOD_VOID_0, ... are used when calling the
	method is only used for its side effect.
	
	  RCPP_XP_METHOD_VOID_1( foobar, std::vector, push_back ) 
	
	Assuming xp is an external pointer to a std::vector, this could
	be called like this :
	
	  .Call( "foobar", xp, 2L )
	
    o	Rcpp now depends on inline (>= 0.3.4)
	
    o   A new R function "cppfunction" was added which invokes cfunction from
	inline with focus on Rcpp usage (enforcing .Call, adding the Rcpp
	namespace, set up exception forwarding). cppfunction uses BEGIN_RCPP
	and END_RCPP macros to enclose the user code

    o	new class Rcpp::Formula to help building formulae in C++
    
    o   new class Rcpp::DataFrame to help building data frames in C++
	
    o   Rcpp.package.skeleton gains an argument "example_code" and can now be
	used with an empty list, so that only the skeleton is generated. It
	has also been reworked to show how to use LinkingTo: Rcpp
	
    o   wrap now supports containers of the following types: long, long double,
	unsigned long, short and unsigned short which are silently converted
	to the most acceptable R type.
	
    o	Revert to not double-quote protecting the path on Windows as this
	breaks backticks expansion used n Makevars.win etc
        
    o   Exceptions classes have been moved out of Rcpp classes,
	e.g. Rcpp::RObject::not_a_matrix is now Rcpp::not_a_matrix

As always, even fuller details are in Rcpp Changelog page and the Rcpp page which also leads to the downloads, the browseable doxygen docs and zip files of doxygen output for the standard formats. A local directory has source and documentation too. Questions, comments etc should go to the rcpp-devel mailing list off the R-Forge page

/code/rcpp | permanent link