RcppBDT stands for Rcpp Boost Date_Time. It employs what we call Rcpp modules: a mechanism which provides easier ways to expose C++ functions and classes to R (and which bears some resemblance to Boost.Python---see this vignette about Rcpp modules for more details). And thus RcppBDT provides R users with access to (some) Boost Date.Time functionality.
I used Boost Date.Time because
it is widely known, useful and well tested. It can also be used in pure
template mode not requiring linking (if one foregoes string parsing and
formatting which is fine here as we get this from R already; it can be added
via a #define in the header file). With that, the package
is rather portable as it only needs to find the Boost headers. (And no, I
have not yet added a configure option for that.)
Basic usage follows Rcpp modules and provides the C++ class via a Reference
Class in R. That means using a new constructor and assessing functions via
the $ operator. Here is an example:
Not very exiting yet: we create a date, using explicit year, months and date arguments and then format it. Something more useful follows:R> library(RcppBDT) Creating a new generic function for "print" in "RcppBDT" Creating a new generic function for "format" in "RcppBDT" R> d <- new(bdtMod$date, 2011, 1, 18) R> format(d) [1] "2011-01-18" R>
We can use accessors to extracts parts of the date, or use functions to convert the date to different representations such as a modified Julian date. Moreover, given a date, we can apply helper functions such as get me the date of the beginning of the next month.R> d$getDayOfWeek() [1] 2 R> d$getModJulian() [1] 55579 R> d$getFirstOfNextMonth() [1] "2011-02-01" R>
More interesting still are helper functions such as the ones below. Note that this also shows the alternate access method using wrapper functions I added for the package, this may be more familiar to most R users:
This uses some of the constantsR> getNthDayOfWeek(third, Wed, Dec, 2010) [1] "2010-12-15" R> getLastDayOfWeekInMonth(Sat, Dec, 2010) [1] "2010-12-25" R> getFirstDayOfWeekInMonth(Sat, Dec, 2010) [1] "2010-12-04" R> getFirstDayOfWeekAfter(Wed, as.Date("2010-12-31")) [1] "2011-01-05" R>
Jan, Feb,
... , Dec; Sun, Mon, ...,
Sat and first ... fifth
defined in the package; normal integers can also be used. The third Wednesday in a month is also known as the IMM
Date to Finance-heads; the example was borrowed from Whit's
earlier rboostdatetime code on github.
More examples are in the demo available with the package and accessible via
demo(RcppBDT) once you install the package.
As always, feedback would be welcome, both on the usefulness (or lack thereof) of the Boost Date.Time functionality as well as on the Rcpp modules wrapping. Additional Boost Date.Time functionality (durations, times, ...) may be added; contributions would be welcome. The rcpp-devel mailing list off the R-Forge page for Rcpp is the best place to start a discussion.