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