https://github.com/cran/Rcpp
Tip revision: bdc95043b2849aaa7cb0a3c5dd9d3ba566e72a94 authored by Dirk Eddelbuettel on 08 November 2009, 18:23:53 UTC
version 0.6.7
version 0.6.7
Tip revision: bdc9504
RcppParams.Rd
\name{RcppParams}
\alias{RcppParams}
\alias{RcppParamsExample}
\title{C++ class for receiving (scalar) parameters from R}
\description{
\code{RcppParams} is a C++ class defined in \code{Rcpp.h} that receive
any number of scalar parameters of types in a single named list object
from \R through the \code{.Call()} function.
The parameters can be of different types that are limited to the \R
types \code{numeric}, \code{integer}, \code{character}, \code{logical}
or \code{Date}. These types are mapped into, respectively, the
corresponding C++ types \code{double}, \code{int}, \code{string},
\code{bool} and \code{Date} (a custom class defined by \code{Rcpp}.
}
\usage{
val <- RcppParamsExample(params)
}
\arguments{
\item{params}{A heterogeneous list specifying \code{method} (string),
\code{tolerance} (double), \code{maxIter} (int) and \code{startDate}
(Date in R, RcppDate in C++).}
}
\value{
\code{RcppExample} returns a list containing:
\item{method}{string input paramter}
\item{tolerance}{double input paramter}
\item{maxIter}{int input parameter}
\item{startDate}{Date type with starting date}
\item{params}{input parameter list (this is redundant because we
returned the input parameters above)}
}
\details{
Usage of \code{RcppParams} from \R via \code{.Call()} is as follows:
\preformatted{%
# 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
\preformatted{%
SEXP someFunction(SEXP params) {
RcppParams par(params);
double p = RcppParams.getDoubleValue("pie");
int magic = RcppParams.getIntValue("magicanswer");
string txt = RcppParams.getStringValue("sometext");
bool yn = RcppParams.getBoolValue("yesno");
RcppDate d = RcppParams.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 \code{checkNames} can be used to verify that the
\code{SEXP} object passed to the function contains a given set of
named object.
}
%\references{
% See \code{Rcpp.h} and the package vignette.
%}
\seealso{
\code{RcppExample}, the vignette \dQuote{RcppAPI}.
}
\author{Dominick Samperi wrote most of Rcpp during 2005 and 2006. Dirk
Eddelbuettel made some additions, and became maintainer in 2008.}
\examples{
# 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
}
\keyword{programming}
\keyword{interface}