Introduce a small GMT time utility module (#1820)

Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>

Author: jviotti

.github/workflows/website-build.yml

@@ -16,6 +16,7 @@ jobs:
       - run: >
           cmake -S . -B ./build
           -DCMAKE_BUILD_TYPE:STRING=Release
+          -DSOURCEMETA_CORE_TIME:BOOL=OFF
           -DSOURCEMETA_CORE_UUID:BOOL=OFF
           -DSOURCEMETA_CORE_GZIP:BOOL=OFF
           -DSOURCEMETA_CORE_REGEX:BOOL=OFF

.github/workflows/website-deploy.yml

@@ -26,6 +26,7 @@ jobs:
       - run: >
           cmake -S . -B ./build
           -DCMAKE_BUILD_TYPE:STRING=Release
+          -DSOURCEMETA_CORE_TIME:BOOL=OFF
           -DSOURCEMETA_CORE_UUID:BOOL=OFF
           -DSOURCEMETA_CORE_GZIP:BOOL=OFF
           -DSOURCEMETA_CORE_REGEX:BOOL=OFF

CMakeLists.txt

@@ -3,6 +3,7 @@ project(core VERSION 0.0.0 LANGUAGES C CXX DESCRIPTION "Sourcemeta Core")
 list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")
 
 # Options
+option(SOURCEMETA_CORE_TIME "Build the Sourcemeta Core time library" ON)
 option(SOURCEMETA_CORE_UUID "Build the Sourcemeta Core UUID library" ON)
 option(SOURCEMETA_CORE_GZIP "Build the Sourcemeta Core GZIP library" ON)
 option(SOURCEMETA_CORE_MD5 "Build the Sourcemeta Core MD5 library" ON)
@@ -50,6 +51,10 @@ if(SOURCEMETA_CORE_INSTALL)
     COMPONENT sourcemeta_${PROJECT_NAME}_dev)
 endif()
 
+if(SOURCEMETA_CORE_TIME)
+  add_subdirectory(src/core/time)
+endif()
+
 if(SOURCEMETA_CORE_UUID)
   add_subdirectory(src/core/uuid)
 endif()
@@ -131,6 +136,10 @@ endif()
 if(SOURCEMETA_CORE_TESTS)
   enable_testing()
 
+  if(SOURCEMETA_CORE_TIME)
+    add_subdirectory(test/time)
+  endif()
+
   if(SOURCEMETA_CORE_UUID)
     add_subdirectory(test/uuid)
   endif()

config.cmake.in

@@ -4,6 +4,7 @@
 list(APPEND SOURCEMETA_CORE_COMPONENTS ${Core_FIND_COMPONENTS})
 list(APPEND SOURCEMETA_CORE_COMPONENTS ${core_FIND_COMPONENTS})
 if(NOT SOURCEMETA_CORE_COMPONENTS)
+  list(APPEND SOURCEMETA_CORE_COMPONENTS time)
   list(APPEND SOURCEMETA_CORE_COMPONENTS uuid)
   list(APPEND SOURCEMETA_CORE_COMPONENTS gzip)
   list(APPEND SOURCEMETA_CORE_COMPONENTS md5)
@@ -20,7 +21,9 @@ endif()
 include(CMakeFindDependencyMacro)
 
 foreach(component ${SOURCEMETA_CORE_COMPONENTS})
-  if(component STREQUAL "uuid")
+  if(component STREQUAL "time")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_time.cmake")
+  elseif(component STREQUAL "uuid")
     include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_uuid.cmake")
   elseif(component STREQUAL "gzip")
     find_dependency(ZLIB CONFIG)

src/core/time/CMakeLists.txt

@@ -0,0 +1,5 @@
+sourcemeta_library(NAMESPACE sourcemeta PROJECT core NAME time SOURCES gmt.cc)
+
+if(SOURCEMETA_CORE_INSTALL)
+  sourcemeta_library_install(NAMESPACE sourcemeta PROJECT core NAME time)
+endif()

src/core/time/gmt.cc

@@ -0,0 +1,53 @@
+#include <sourcemeta/core/time.h>
+
+#include <cassert>   // assert
+#include <ctime>     // std::time_t, std::tm, std::gmtime, std::mktime, timegm
+#include <iomanip>   // std::put_time, std::get_time
+#include <sstream>   // std::ostringstream, std::istringstream
+#include <stdexcept> // std::invalid_argument, std::runtime_error
+
+#if defined(_MSC_VER)
+#include <errno.h>
+#endif
+
+namespace {
+constexpr auto FORMAT_GMT{"%a, %d %b %Y %H:%M:%S GMT"};
+}
+
+namespace sourcemeta::core {
+
+auto to_gmt(const std::chrono::system_clock::time_point time) -> std::string {
+  const std::time_t ctime = std::chrono::system_clock::to_time_t(time);
+#if defined(_MSC_VER)
+  std::tm buffer;
+  if (gmtime_s(&buffer, &ctime) != 0) {
+    throw std::runtime_error("Could not convert time point to GMT");
+  }
+
+  std::tm *parts = &buffer;
+#else
+  std::tm *parts = std::gmtime(&ctime);
+#endif
+  assert(parts);
+  std::ostringstream stream;
+  stream << std::put_time(parts, FORMAT_GMT);
+  return stream.str();
+}
+
+auto from_gmt(const std::string &time)
+    -> std::chrono::system_clock::time_point {
+  std::istringstream stream{time};
+  std::tm parts = {};
+  stream >> std::get_time(&parts, FORMAT_GMT);
+  if (stream.fail()) {
+    throw std::invalid_argument("Invalid GMT timestamp");
+  }
+
+#if defined(_MSC_VER)
+  return std::chrono::system_clock::from_time_t(_mkgmtime(&parts));
+#else
+  return std::chrono::system_clock::from_time_t(timegm(&parts));
+#endif
+}
+
+} // namespace sourcemeta::core

src/core/time/include/sourcemeta/core/time.h

@@ -0,0 +1,84 @@
+#ifndef SOURCEMETA_CORE_TIME_H_
+#define SOURCEMETA_CORE_TIME_H_
+
+#ifndef SOURCEMETA_CORE_TIME_EXPORT
+#include <sourcemeta/core/time_export.h>
+#endif
+
+#include <chrono> // std::chrono::system_clock::time_point
+#include <string> // std::string
+
+/// @defgroup time Time
+/// @brief A growing implementation of time-related utilities for standard such
+/// as RFC 7231 (GMT).
+///
+/// This functionality is included as follows:
+///
+/// ```cpp
+/// #include <sourcemeta/core/time.h>
+/// ```
+
+namespace sourcemeta::core {
+
+/// @ingroup time
+/// Convert a time point into a GMT string. For example:
+///
+/// ```cpp
+/// #include <sourcemeta/core/time.h>
+///
+/// #include <chrono>
+/// #include <ctime>
+/// #include <cassert>
+///
+/// std::tm parts = {};
+/// parts.tm_year = 115;
+/// parts.tm_mon = 9;
+/// parts.tm_mday = 21;
+/// parts.tm_hour = 11;
+/// parts.tm_min = 28;
+/// parts.tm_sec = 0;
+/// parts.tm_isdst = 0;
+///
+/// const auto point{std::chrono::system_clock::from_time_t(timegm(&parts))};
+///
+/// assert(sourcemeta::core::to_gmt(point) ==
+///   "Wed, 21 Oct 2015 11:28:00 GMT");
+/// ```
+///
+/// On Windows, you might need to use `_mkgmtime` instead of `timegm`.
+SOURCEMETA_CORE_TIME_EXPORT
+auto to_gmt(const std::chrono::system_clock::time_point time) -> std::string;
+
+/// @ingroup time
+/// Parse a GMT string into a time point. For example:
+///
+/// ```cpp
+/// #include <sourcemeta/core/time.h>
+///
+/// #include <chrono>
+/// #include <ctime>
+/// #include <cassert>
+///
+/// const auto point{
+///     sourcemeta::core::from_gmt("Wed, 21 Oct 2015 11:28:00 GMT")};
+///
+/// std::tm parts = {};
+/// parts.tm_year = 115;
+/// parts.tm_mon = 9;
+/// parts.tm_mday = 21;
+/// parts.tm_hour = 11;
+/// parts.tm_min = 28;
+/// parts.tm_sec = 0;
+/// parts.tm_isdst = 0;
+/// const auto expected{std::chrono::system_clock::from_time_t(timegm(&parts))};
+///
+/// assert(point = expected);
+/// ```
+///
+/// On Windows, you might need to use `_mkgmtime` instead of `timegm`.
+SOURCEMETA_CORE_TIME_EXPORT
+auto from_gmt(const std::string &time) -> std::chrono::system_clock::time_point;
+
+} // namespace sourcemeta::core
+
+#endif

test/packaging/find_package/CMakeLists.txt

@@ -5,6 +5,7 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 find_package(Core REQUIRED)
 add_executable(core_hello hello.cc)
+target_link_libraries(core_hello PRIVATE sourcemeta::core::time)
 target_link_libraries(core_hello PRIVATE sourcemeta::core::uuid)
 target_link_libraries(core_hello PRIVATE sourcemeta::core::gzip)
 target_link_libraries(core_hello PRIVATE sourcemeta::core::md5)

test/packaging/find_package/hello.cc

@@ -5,6 +5,7 @@
 #include <sourcemeta/core/jsonpointer.h>
 #include <sourcemeta/core/jsonschema.h>
 #include <sourcemeta/core/md5.h>
+#include <sourcemeta/core/time.h>
 #include <sourcemeta/core/uri.h>
 #include <sourcemeta/core/uuid.h>
 #include <sourcemeta/core/yaml.h>

test/time/CMakeLists.txt

@@ -0,0 +1,5 @@
+sourcemeta_googletest(NAMESPACE sourcemeta PROJECT core NAME time
+  SOURCES gmt_test.cc)
+
+target_link_libraries(sourcemeta_core_time_unit
+  PRIVATE sourcemeta::core::time)