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
Rcpp-package.Rd
\name{Rcpp-package}
\alias{Rcpp-package}
\alias{Rcpp}
\docType{package}
\title{R / C++ interface}
\description{The \pkg{Rcpp} package provides C++ classes that
greatly facilitate interfacing C or C++ code in \R packages using
the \code{.Call} interface provided by \R.
Detailed information is provided in the vignette \sQuote{RcppAPI} that
can be invoked from \R via \code{vignette("RcppAPI")}.
}
\section{Overview}{
\pkg{Rcpp} provides matching C++ classes for a large number of
basic \R data types. Hence, a package author can keep his data in
normal R data structure without having to worry about translation or
transfer to C++. At the same time, the data structures can be accessed
as easily at the C++ level, and used in the normal manner.
The mapping of data types works in both directions. It is as
straightforward to pass data from R to C++, as it is it return data
from C++ to \R. The following two sections list supported data types.
}
\section{Transfer from R to C++}{
Standard \R datatypes that are understood are
\enumerate{
\item named lists containing numeric (i.e. floating point), integer,
character, logical (i.e. boolean) or Date and Datetime
(i.e. POSIXct) arguments;
\item data frames containing numeric, integer, logical, character,
Date, Datetime or Factor columns;
\item named vectors containing numeric or integer values,
\item vectors and matrices of different values
\item character strings
}
}
\section{Transfer from C++ to R}{
Standard C++ datatypes can be returned to \R in a named list, the most
general data type in \R. Permissible components of the returns list
are the following C++ types:
\enumerate{
\item double (scalar as well as vectors and vectors of vectors),
\item int (scalar as well as vectors and vectors of vectors),
\item string,
\item STL vector types and vector<vector> types of int and double
\item STL vector of strings
\item internal Rcpp types RcppDate, RcppDateVector, RcppDatetime,
RcppDatetimeVector, RcppStringVector, RcppVector of int or double,
RcppMatrix of int or double, RcppFrame}
}
\section{Usage for package building}{
\pkg{Rcpp} provides a header file and a library inside the installed
package in the directory \code{lib}. From within \R, you can compute
the directory location via \code{system.file("lib", "Rcpp.h",
package="Rcpp")}. For Windows, it will be a static library
\sQuote{Rcpp.a}. For Linux and Mac OS X, it will be \sQuote{libRcpp.so}.
To use \code{Rcpp} in another package, you need to include the header
during compilation. This typically requires use of the \code{-I} to
provide the location as in \code{-I/usr/local/lib/R/site-library/Rcpp/lib}.
Similarly, for linking we need to provide the location of the library
via \code{-L} as well as the actual library. An example for Linux
would be \code{-L/usr/local/lib/R/site-library/Rcpp/lib -lRcpp}.
In order to make it more convenient to use \code{Rcpp}, functions
providing these arguments were added. To use these, simply use a file
\code{src/Makevars} such as this (which was taken from the
\code{emdL1} package)
\preformatted{
# compile flag providing header directory containing Rcpp.h
PKG_CXXFLAGS=`Rscript -e 'Rcpp:::CxxFlags()'`
# link flag providing libary as well as path to library, and optionally rpath
PKG_LIBS=`Rscript -e 'Rcpp:::LdFlags()'`
}
Alternatively, one can also encode the test for these variables using
the \code{GNU autoconf} system. The \code{RQuantLib} package
provides an example of that.
Lastly, on Linux, and during development, it can convenient to simply
provide these files via soft links (or copies) from the usual locations like
\sQuote{/usr/local/include} and \sQuote{/usr/local/lib} which
alleviates the need for explicit location flags like \sQuote{-I} or
\sQuote{-L}. Remember to also run \code{ldconfig} after creating the
link for the library. Alternatively, you can hardcode the dynamic
library location using the \code{rpath} linker directive:
Use on Windows is identical to the use in Linux. However only a static
library is provided. The two \code{\link{Rcpp}} functions detailed
above provide the relevant content.
}
\author{Dominick Samperi wrote most of Rcpp during 2005 and 2006. Dirk
Eddelbuettel made some additions, and became maintainer in 2008.}
\keyword{programming}
\keyword{interface}