C++ classes for interfacing date and datetime R objects – deprecated API

Share:

Description

RcppDate, RcppDatetime, RcppDateVector and RcppDatetimeVector are C++ classes defined in their respective headers files. They are part of the 'classic' Rcpp API. These classes pass scalars and vectors of R objects of types Date and POSIXct, respectively, to C++ via the .Call() function interface.

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

R objects of type Date, and hence the RcppDate and RcppDateVector objects, are internally represented as an integer counting days since the epoch, i.e. January 1, 1970. Similarly, R objects of type POSIXct and the RcppDatetime and RcppDatetimeVector objects, are internally represented as seconds since the epoch. However, R extends the POSIX standard by using a double leading to microsecond precision in timestamps. This is fully supported by Rcpp as well.

The new API currently has the classes Rcpp::Date, Rcpp::Datetime, Rcpp::DateVector and Rcpp::DatetimeVector which are preferred for new developments, as is the rest of the new API in the Rcpp package while the RcppClassic package has been deprecated since 2010.

Details

Usage of the RcppDate, RcppDatetime (and their vector extensions) in C++ is fully defined in the respective header files RcppDate.h and RcppDatetime.h.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
  # an R example passing one type of each class to a function
  # someFunction in package somePackage
  val <- .Call("someFunction",
               Sys.Date(),      # current date
	           Sys.time(), 	    # current timestamp
	           as.Date("2000-02-25")
	             + 0:5,         # date vector
	           ISOdatetime(1999,12,31,23,59,0)
	             + (0:5)*0.250, # datetime vector
   	           PACKAGE="somePackage")
  

At the C++ level, the corresponding code to assign these parameter to C++ objects is can be as follows::

1
2
3
4
5
6
7
8
9
  SEXP someFunction(SEXP ds, SEXP dts,
                    SEXP dvs, SEXP dtvs) {

    RcppDate           d(ds);  		      
    RcppDatetime       dt(dts);
    RcppDateVector     dv(dvs);
    RcppDatetimeVector dtv(dtvs);
  }
  

Standard accessor functions are defined, see RcppDate.h and RcppDatetime.h for details.

Objects of these types can also be returned via RcppResultSet.

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

RcppResultSet.

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
# 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