Fix UTC daylight-savings-time offset issue. - authored by @cboulay

294 fix utc dst

Merge pull request #295 from cboulay/294-fix-utc-dst

authored by @cboulay

Author: oruebel

CHANGELOG.md

@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 * Updated nwbinspector validation tests in the CI to: 1) `--ignore=check_subject_exists` and 2) remove dependency on `sanitizer` tests to speed up CI (@oruebel, [#289](https://github.com/NeurodataWithoutBorders/aqnwb/pull/289))
+* Fixed `get_utc_offset_seconds` to correctly account for daylight saving time using platform-specific APIs (`tm_gmtoff` on Unix/macOS; `_get_timezone` + `_get_dstbias` on Windows), preventing `session_start_time` from being written ~1 hour ahead of UTC during DST (@cboulay, [#295](https://github.com/NeurodataWithoutBorders/aqnwb/pull/295))
 
 
 ## [0.3.0] - 2026-02-23

src/Utils.hpp

@@ -64,13 +64,29 @@ inline std::tm to_utc_time(std::time_t time_value)
 /**
  * @brief Get the UTC offset in seconds for a given time_t value.
  * @param time_value The time value to check.
- * @return The offset from UTC in seconds.
+ * @return The offset from UTC in seconds (includes DST when active).
  */
 inline long get_utc_offset_seconds(std::time_t time_value)
 {
+#if defined(__unix__) || defined(__APPLE__)
+  std::tm local_tm = to_local_time(time_value);
+  return local_tm.tm_gmtoff;
+#elif defined(_WIN32)
+  long tz_seconds = 0;
+  _get_timezone(&tz_seconds);
+  std::tm local_tm = to_local_time(time_value);
+  if (local_tm.tm_isdst > 0) {
+    long dstbias = 0;
+    _get_dstbias(&dstbias);
+    tz_seconds += dstbias;
+  }
+  return -tz_seconds;
+#else
+  // Fallback: force utc_tm.tm_isdst to match local so mktime treats both
+  // consistently, avoiding the DST double-count.
   std::tm local_tm = to_local_time(time_value);
   std::tm utc_tm = to_utc_time(time_value);
-
+  utc_tm.tm_isdst = local_tm.tm_isdst;
   std::time_t local_time = std::mktime(&local_tm);
   std::time_t utc_time = std::mktime(&utc_tm);
   if (local_time == static_cast<std::time_t>(-1)
@@ -79,6 +95,7 @@ inline long get_utc_offset_seconds(std::time_t time_value)
     return 0;
   }
   return static_cast<long>(std::difftime(local_time, utc_time));
+#endif
 }
 
 /**

tests/testNWBFile.cpp

@@ -1,3 +1,4 @@
+#include <cstdio>
 #include <numeric>
 #include <unordered_map>
 #include <unordered_set>
@@ -504,6 +505,52 @@ TEST_CASE("testAttributeAndDatasetFields", "[nwb]")
   std::string readSessionStartTime = sessionStartTimeData->values().data[0];
   REQUIRE(readSessionStartTime == sessionStartTime);
 
+  // Mirrors nwbinspector's check_session_start_time_future_date: the
+  // session_start_time written to the file must not be in the future.
+  // The old mktime-based UTC offset was wrong during DST, which caused
+  // the recorded time to be ~1 hour ahead of actual UTC.
+  {
+    std::tm parsed {};
+    int offset_h = 0, offset_m = 0;
+    char offset_sign = '+';
+    // Parse "YYYY-MM-DDTHH:MM:SS.uuuuuu+HH:MM"
+#if defined(_MSC_VER)
+#  pragma warning(push)
+#  pragma warning(disable : 4996)  // sscanf deprecation
+#endif
+    int parsed_fields = std::sscanf(readSessionStartTime.c_str(),
+                                    "%4d-%2d-%2dT%2d:%2d:%2d.%*d%c%2d:%2d",
+                                    &parsed.tm_year,
+                                    &parsed.tm_mon,
+                                    &parsed.tm_mday,
+                                    &parsed.tm_hour,
+                                    &parsed.tm_min,
+                                    &parsed.tm_sec,
+                                    &offset_sign,
+                                    &offset_h,
+                                    &offset_m);
+#if defined(_MSC_VER)
+#  pragma warning(pop)
+#endif
+    REQUIRE(parsed_fields == 9);
+    parsed.tm_year -= 1900;
+    parsed.tm_mon -= 1;
+    parsed.tm_isdst = 0;
+    // Convert struct tm (interpreted as UTC) to time_t
+#if defined(_WIN32)
+    std::time_t utc_epoch = _mkgmtime(&parsed);
+#else
+    std::time_t utc_epoch = timegm(&parsed);
+#endif
+    long offset_total =
+        ((long)offset_h * 3600 + offset_m * 60) * (offset_sign == '-' ? -1 : 1);
+    // Convert local time to UTC by subtracting the offset
+    utc_epoch -= offset_total;
+    auto written_tp = std::chrono::system_clock::from_time_t(utc_epoch);
+    auto now_tp = std::chrono::system_clock::now();
+    REQUIRE(written_tp <= now_tp);
+  }
+
   auto timestampsReferenceTimeData = nwbfile->readTimestampsReferenceTime();
   REQUIRE(timestampsReferenceTimeData->exists());
   REQUIRE(timestampsReferenceTimeData->getStorageObjectType()

tests/testUtilsFunctions.cpp

@@ -156,6 +156,34 @@ TEST_CASE("Test time conversion functions", "[utils]")
     REQUIRE(offset <= 14 * 3600);
   }
 
+  SECTION("get_utc_offset_seconds matches tm_gmtoff")
+  {
+    // Verify the offset matches the OS-reported value (which includes DST).
+    // The old mktime-based implementation got this wrong during DST because
+    // mktime interprets its argument as local time, double-counting DST.
+#if defined(__unix__) || defined(__APPLE__)
+    // tm_gmtoff is a non-standard extension available on Unix/macOS
+    std::tm local_tm {};
+    localtime_r(&now, &local_tm);
+    long expected = local_tm.tm_gmtoff;
+    long actual = AQNWB::detail::get_utc_offset_seconds(now);
+    REQUIRE(actual == expected);
+#elif defined(_WIN32)
+    // On Windows, verify against _get_timezone + _get_dstbias
+    long tz_seconds = 0;
+    _get_timezone(&tz_seconds);
+    std::tm local_tm = AQNWB::detail::to_local_time(now);
+    if (local_tm.tm_isdst > 0) {
+      long dstbias = 0;
+      _get_dstbias(&dstbias);
+      tz_seconds += dstbias;
+    }
+    long expected = -tz_seconds;
+    long actual = AQNWB::detail::get_utc_offset_seconds(now);
+    REQUIRE(actual == expected);
+#endif
+  }
+
   SECTION("format_utc_offset")
   {
     REQUIRE(AQNWB::detail::format_utc_offset(0) == "+00:00");