C++ class for receiving (scalar) parameters from R – deprecated API

Share:

Description

RcppParams is a C++ class defined in Rcpp.h that receive any number of scalar parameters of types in a single named list object from R through the .Call() function.

The parameters can be of different types that are limited to the R types numeric, integer, character, logical or Date. These types are mapped into, respectively, the corresponding C++ types double, int, string, bool and Date (a custom class defined by Rcpp.

RcppParams is part of the old deprecated Rcpp API, and should be replaces by Rcpp::List which is more flexible and can be used for both inputs and outputs. RcppParams is retained for backwards compatibility, but should be avoided in new projects and replaced in old projects.

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

Arguments

params

A heterogeneous list specifying method (string), tolerance (double), maxIter (int) and startDate (Date in R, RcppDate in C++).

Details

Usage of RcppParams from R via .Call() is as follows:

1
2
3
4
5
6
7
  # an R example passing one type of each class to a function
  # someFunction in package somePackage
  val <- .Call("someFunction",
               list(pie=3.1415, magicanswer=42, sometext="foo",
                    yesno=true, today=Sys.date()),
		    PACKAGE="somePackage")
  

At the C++ level, the corresponding code to assign these parameter to C++ objects is

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
  SEXP someFunction(SEXP params) {
    RcppParams par(params);
    double p   = par.getDoubleValue("pie");
    int magic  = par.getIntValue("magicanswer");
    string txt = par.getStringValue("sometext");
    bool yn    = par.getBoolValue("yesno");
    RcppDate d = par.getDateValue("today");
    // some calculations ...
    // some return values ...
  }
  

As the 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.

Value

RcppExample returns a list containing:

method

string input paramter

tolerance

double input paramter

maxIter

int input parameter

startDate

Date type with starting date

params

input parameter list (this is redundant because we returned the input parameters above)

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.

References

Writing R Extensions, available at http:www.r-project.org.

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
11
# set up some value
params <- list(method='BFGS',
               tolerance=1.0e-5,
               maxIter=100,
               startDate=as.Date('2006-7-15'))

# call the underlying  C++ function
result <- RcppParamsExample(params)

# inspect returned object
result