RcppResultSet: C++ class for sending C++ objects back to R - deprecated API

Description Details Author(s) See Also Examples

Description

RcppResultSet is a C++ class defined in RcppResultSet.h that can assign any number of C++ objects to R in a single named list object as the SEXP return value of a .Call() function call. It is part of the classic API.

The C++ objects can be of different types that are limited to types double, int, string, vectors of double or int (with explicit dimensions), matrices of double or int (with explicit dimensions), STL vectors of double, int or string, STL ‘vector of vectors’ of types double or int (all with implicit dimensions), the internal types RcppDate, RcppDateVector, RcppStringVector, RcppVector of types double or int, RcppMatrix of types double or int as well RcppFrame, a type that can be converted into a data.frame, and the R type SEXP.

Where applicable, the C++ types are automatically converted to the corresponding R types structures around types numeric, integer, or character. The C++ code can all be retrieved in R as elements of a named list object.

The new API has more generic templated functions.

Note that the RcppClassic package has been deprecated since 2010, all new development should use the Rcpp package instead.

Details

Usage of RcppResultSet from C++ is fully defined in RcppResultSet.h. An example for returning data to R at the end of a .Call() call follows.

At the C++ level, the corresponding code to assign these parameter to C++ objects is can be as follows (taken from the C++ source of RcppExample):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
  SEXP rl;
  RcppResultSet rs;
    
  rs.add("date", aDate);	// RcppDate
  rs.add("dateVec", dateVec);	// RcppDateVec
  rs.add("method", method);	// string
  rs.add("tolerance", tol);	// numeric
  rs.add("maxIter", maxIter);	// int
  rs.add("matD", matD);		// RcppMatrix
  rs.add("stlvec", stlvec);	// vector<double> or <int>
  rs.add("stlmat", stlmat);	// vector< vector <double> >
  				//   or <int>
  rs.add("a", a, nrows, ncols);	// double** (or int**) with 
				//   two dimension
  rs.add("v", v, len);		// double* (or int*) with 
				//   one dimension
  rs.add("stringVec", strVec);	// RcppStringVector
  rs.add("strings", svec);	// vector<string>
  rs.add("InputDF", inframe);	// RcppFrame
  rs.add("PreDF", frame);	// RcppFrame

  rl = rs.getReturnList();
  return(rl);
  

As the R level, we assign the returned object a list variables from which we select each list element by its name. lookup is driven by the names givem at the R level, order is not important. It is however important that the types match. Errors are typically caught and an exception is thrown.

The class member function checkNames can be used to verify that the SEXP object passed to the function contains a given set of named object.

Author(s)

Dominick Samperi wrote the initial versions of Rcpp (and RcppTemplate) during 2005 and 2006. Dirk Eddelbuettel made some additions, and became maintainer in 2008. Dirk Eddelbuettel and Romain Francois have been extending Rcpp since 2009.

See Also

RcppExample.

See the RcppExamples-package for examples of the recommended Rcpp API and Rcpp-package for documentation on the recommended API to extend R with C++ code, while the deprecated RcppClassic-package documents the older, deprecated API.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# example from RcppDate
# set up date and datetime vectors
dvec <- Sys.Date() + -2:2
dtvec <- Sys.time() + (-2:2)*0.5

# call the underlying  C++ function
result <- RcppDateExample(dvec, dtvec)

# inspect returned object
result


Search within the RcppClassicExamples package
Search all R packages, documentation and source code

Questions? Problems? Suggestions? or email at ian@mutexlabs.com.

Please suggest features or report bugs with the GitHub issue tracker.

All documentation is copyright its authors; we didn't write any of that.