Implement limited callable API for vroom (#213)

* Implement limited callable API for vroom

* Remove `clock_build()` in favor of using `date.h` tools directly

* Remove indirection around `date::time_zone*`

It seems like the forward declaration of `class time_zone` in `date/tz.h` is enough to allow us to use it as a return value and an argument

* Bump development version for vroom

* Allow runtime errors to be thrown from `clock_locate_zone()`

vroom will possibly call this in parallel, and will catch any runtime errors. However, you cannot throw a cpp11 error, or allocate any R memory, while in a thread.

* Document exported helpers

* Export `clock_get_local_info()` for maximum flexibility

This way the client can choose exactly how to handle nonexistent and ambiguous times, and we don't have to return a custom struct for nonexistent times

* NEWS

Author: DavisVaughan

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: clock
 Title: Date-Time Types and Tools
-Version: 0.1.0.9000
+Version: 0.1.0.9001
 Authors@R: 
     c(person(given = "Davis",
              family = "Vaughan",

NEWS.md

@@ -46,6 +46,8 @@
 
 * Linking against cpp11 0.2.7 is now required to fix a rare memory leak issue.
 
+* Exposed an extremely experimental and limited C++ API for vroom (#322).
+
 # clock 0.1.0
 
 * Added a `NEWS.md` file to track changes to the package.

inst/include/clock/clock.h

@@ -0,0 +1,35 @@
+#ifndef CLOCK_CLOCK_H
+#define CLOCK_CLOCK_H
+
+#include <R_ext/Rdynload.h>
+
+#include <chrono>
+#include <string>
+
+#include <date/date.h>
+#include <date/tz.h>
+
+namespace rclock {
+
+static
+inline
+const date::time_zone*
+locate_zone(const std::string& zone_name) {
+  typedef const date::time_zone* fn_t(const std::string&);
+  static fn_t *fn = (fn_t*) R_GetCCallable("clock", "clock_locate_zone");
+  return fn(zone_name);
+}
+
+static
+inline
+date::local_info
+get_local_info(const date::local_seconds& lt,
+               const date::time_zone* p_time_zone) {
+  typedef date::local_info fn_t(const date::local_seconds&, const date::time_zone*);
+  static fn_t *fn = (fn_t*) R_GetCCallable("clock", "clock_get_local_info");
+  return fn(lt, p_time_zone);
+}
+
+} // namespace rclock
+
+#endif

src/cpp11.cpp

@@ -1139,8 +1139,11 @@ static const R_CallMethodDef CallEntries[] = {
 };
 }
 
+void export_clock_callables(DllInfo* dll);
+
 extern "C" void R_init_clock(DllInfo* dll){
   R_registerRoutines(dll, NULL, CallEntries, NULL, NULL);
   R_useDynamicSymbols(dll, FALSE);
+  export_clock_callables(dll);
   R_forceSymbols(dll, TRUE);
 }

src/exported.cpp

@@ -0,0 +1,39 @@
+#include "clock.h"
+#include <R_ext/Rdynload.h> // For DllInfo on R 3.3
+
+// -----------------------------------------------------------------------------
+
+/*
+ * Look up a time zone by name
+ *
+ * Returns a `time_zone` pointer for use in `clock_get_local_info()`.
+ *
+ * `""` should not be passed through here. If you need to pass through the
+ * system time zone, materialize its value with `Sys.timezone()` first.
+ *
+ * Throws a `std::runtime_error()` with an informative message if the
+ * `zone_name` does not exist in the database.
+ */
+const date::time_zone*
+clock_locate_zone(const std::string& zone_name) {
+  return date::locate_zone(zone_name);
+}
+
+// -----------------------------------------------------------------------------
+
+/*
+ * Pair a local time with a time zone to compute all local time information
+ */
+date::local_info
+clock_get_local_info(const date::local_seconds& lt,
+                     const date::time_zone* p_time_zone) {
+  return p_time_zone->get_info(lt);
+}
+
+// -----------------------------------------------------------------------------
+
+[[cpp11::init]]
+void export_clock_callables(DllInfo* dll){
+  R_RegisterCCallable("clock", "clock_locate_zone",    (DL_FUNC)clock_locate_zone);
+  R_RegisterCCallable("clock", "clock_get_local_info", (DL_FUNC)clock_get_local_info);
+}