C++ classes for receiving R object in C++ – deprecated API

Share:

Description

RcppVector, RcppMatrix and RcppStringVector are C++ classes that can pass vectors (matrices) of R objects of appropriate types to C++ via the .Call() function interface. They are part of the 'classic' Rcpp API.

The vector and matrix types are templated and can operate on R types intger and numeric.

The RcppVectorView and RcppMatrixView are slighly more lightweight read-only variants.

Member functions are provided to query the dimension of the vector or matrix object, convert it in a corresponding C representation, and also to convert it into a corresponding STL object.

The new API has classes NumericVector, NumericMatrix, CharacterVector (and also an alias StringVector).

The files RcppVectorExample.cpp and RcppMatrixExample.cpp provide examples for both the classic and new APIs.

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

Details

Usage of RcppVector, RcppMatrix and RcppStringVector in C++ is fully defined in the respective header files.

As example, consider a call from R to C++ such as

1
2
3
4
5
6
7
8
9
  # an R example passing one type of each class to a function
  # someFunction in package somePackage
  val <- .Call("someFunction",
               rnorm(100),        # numeric vector
	       sample(1:10, 5, TRUE)  # int vector
	       search(),          # character vector
	       as.matrix(rnorm(100),10,10), # matrix
   	       PACKAGE="somePackage")
  

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
  SEXP someFunction(SEXP nvec, SEXP ivec,
                    SEXP svec, SEXP nmat) {

    RcppVector<double> nv(nvec);  		      
    RcppVector<int>    iv(ivec);
    RcppStringVector   sv(svec);
    RcppMatrix<double> nm(nmat);
  }
  

These C++ objects could then be queried via

1
2
3
    int n = nv.size();
    int d1 = nm.dim1(), d2 = nm.dim2();
  

to retrieve, respectively, vector length and matrix dimensions.

Moreover, the stlVector() and stlMatrix() member functions can be used to convert the objects into STL objects:

1
2
3
    vector<int> ivstl = iv.stlVector();
    vector< vector< double > > = nm.stlMatrix();
  

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
# set up some value
vector <- (seq(1,9))^2

# call the underlying  C++ function
result <- RcppVectorExample(vector)

# inspect returned object
result