feat(timezone): add US Eastern and Central ↔ GMT conversions with DST and tests

Author: NewYaroslav

CHANGELOG.md

@@ -20,6 +20,8 @@ All notable changes to this project will be documented in this file.
 - Unified `now_realtime_us()` precision across Windows and Unix by combining realtime anchors with monotonic clocks.
 - Added MQL5 counterparts for recent workday boundary and ISO parsing helpers.
 - Introduced templated NTP client pools, offline/fake testing paths, background runner helpers, and a singleton NTP time service with convenience wrappers.
+- Added US Eastern Time (ET/NY) to GMT (UTC) conversion helpers with DST rules.
+- Added US Central Time (CT) to GMT (UTC) conversion helpers for America/Chicago.
 
 ## [v1.0.4] - 2025-09-20
 - fix ODR violations in headers

include/time_shield/time_zone_conversions.hpp

@@ -4,7 +4,7 @@
 #define _TIME_SHIELD_TIME_ZONE_CONVERSIONS_HPP_INCLUDED
 
 /// \file time_zone_conversions.hpp
-/// \brief Helpers for converting CET/EET timestamps to GMT.
+/// \brief Helpers for converting CET/EET/ET timestamps to GMT (UTC).
 /// \ingroup time_zone_conversions
 
 #include "date_time_struct.hpp"
@@ -95,6 +95,109 @@ namespace time_shield {
         return cet_to_gmt(eet - SEC_PER_HOUR);
     }
 
+    /// \brief Check if local US Eastern time uses DST.
+    /// \param dt Local time in ET.
+    /// \return True if DST applies for the provided local timestamp.
+    inline bool is_us_eastern_dst_local(const DateTimeStruct& dt) {
+        const int SWITCH_HOUR = 2;
+        int start_day = 0;
+        int end_day = 0;
+        int start_month = 0;
+        int end_month = 0;
+
+        if(dt.year >= 2007) {
+            start_month = MAR;
+            end_month = NOV;
+            int first_sunday_march = 1 + (DAYS_PER_WEEK - day_of_week_date(dt.year, MAR, 1)) % DAYS_PER_WEEK;
+            start_day = first_sunday_march + 7;
+            end_day = 1 + (DAYS_PER_WEEK - day_of_week_date(dt.year, NOV, 1)) % DAYS_PER_WEEK;
+        } else {
+            start_month = APR;
+            end_month = OCT;
+            start_day = 1 + (DAYS_PER_WEEK - day_of_week_date(dt.year, APR, 1)) % DAYS_PER_WEEK;
+            end_day = last_sunday_month_day(dt.year, OCT);
+        }
+
+        if(dt.mon > start_month && dt.mon < end_month) {
+            return true;
+        }
+        if(dt.mon < start_month || dt.mon > end_month) {
+            return false;
+        }
+        if(dt.mon == start_month) {
+            if(dt.day > start_day) {
+                return true;
+            }
+            if(dt.day < start_day) {
+                return false;
+            }
+            return dt.hour >= SWITCH_HOUR;
+        }
+        if(dt.mon == end_month) {
+            if(dt.day < end_day) {
+                return true;
+            }
+            if(dt.day > end_day) {
+                return false;
+            }
+            return dt.hour < SWITCH_HOUR;
+        }
+        return false;
+    }
+
+    /// \brief Convert US Eastern Time (New York, EST/EDT) to GMT (UTC).
+    /// \param et Timestamp in seconds in ET.
+    /// \return Timestamp in seconds in GMT (UTC).
+    ///
+    /// GMT in this library uses UTC. DST rules are guaranteed for 1987+;
+    /// earlier years use 1987-2006 rules as a best-effort approximation.
+    inline ts_t et_to_gmt(ts_t et) {
+        DateTimeStruct dt = to_date_time(et);
+        bool is_dst = is_us_eastern_dst_local(dt);
+        return et + SEC_PER_HOUR * (is_dst ? 4 : 5);
+    }
+
+    /// \brief Convert GMT (UTC) to US Eastern Time (New York, EST/EDT).
+    /// \param gmt Timestamp in seconds in GMT (UTC).
+    /// \return Timestamp in seconds in ET.
+    ///
+    /// GMT in this library uses UTC. DST rules are guaranteed for 1987+;
+    /// earlier years use 1987-2006 rules as a best-effort approximation.
+    inline ts_t gmt_to_et(ts_t gmt) {
+        ts_t et_standard = gmt - SEC_PER_HOUR * 5;
+        DateTimeStruct dt_local = to_date_time(et_standard);
+        bool is_dst = is_us_eastern_dst_local(dt_local);
+        return gmt - SEC_PER_HOUR * (is_dst ? 4 : 5);
+    }
+
+    /// \brief Convert New York Time to GMT (UTC).
+    /// \param ny Timestamp in seconds in ET.
+    /// \return Timestamp in seconds in GMT (UTC).
+    inline ts_t ny_to_gmt(ts_t ny) {
+        return et_to_gmt(ny);
+    }
+
+    /// \brief Convert GMT (UTC) to New York Time.
+    /// \param gmt Timestamp in seconds in GMT (UTC).
+    /// \return Timestamp in seconds in ET.
+    inline ts_t gmt_to_ny(ts_t gmt) {
+        return gmt_to_et(gmt);
+    }
+
+    /// \brief Convert US Central Time (America/Chicago, CST/CDT) to GMT (UTC).
+    /// \param ct Timestamp in seconds in CT.
+    /// \return Timestamp in seconds in GMT (UTC).
+    inline ts_t ct_to_gmt(ts_t ct) {
+        return et_to_gmt(ct + SEC_PER_HOUR);
+    }
+
+    /// \brief Convert GMT (UTC) to US Central Time (America/Chicago, CST/CDT).
+    /// \param gmt Timestamp in seconds in GMT (UTC).
+    /// \return Timestamp in seconds in CT.
+    inline ts_t gmt_to_ct(ts_t gmt) {
+        return gmt_to_et(gmt) - SEC_PER_HOUR;
+    }
+
     /// \brief Convert Greenwich Mean Time to Central European Time.
     /// \param gmt Timestamp in seconds in GMT.
     /// \return Timestamp in seconds in CET.

tests/time_zone_conversion_test.cpp

@@ -11,6 +11,16 @@
 int main() {
     using namespace time_shield;
 
+    const int SWITCH_HOUR = 2;
+
+    auto first_sunday_month_day = [](int year, int month) {
+        return 1 + (DAYS_PER_WEEK - day_of_week_date(year, month, 1)) % DAYS_PER_WEEK;
+    };
+
+    auto second_sunday_month_day = [&](int year, int month) {
+        return first_sunday_month_day(year, month) + 7;
+    };
+
     ts_t cet_winter = to_timestamp(2023, 1, 1, 12, 0, 0);
     ts_t gmt_winter = cet_to_gmt(cet_winter);
     assert(gmt_winter == to_timestamp(2023, 1, 1, 11, 0, 0));
@@ -35,6 +45,52 @@ int main() {
     ts_t gmt_eet_summer = eet_to_gmt(eet_summer);
     assert(gmt_eet_summer == to_timestamp(2023, 7, 1, 9, 0, 0));
 
+    int spring_day_2024 = second_sunday_month_day(2024, MAR);
+    ts_t et_before_spring = to_timestamp(2024, int(MAR), spring_day_2024, 1, 59, 59);
+    ts_t gmt_before_spring = et_to_gmt(et_before_spring);
+    assert(gmt_before_spring == to_timestamp(2024, int(MAR), spring_day_2024, 6, 59, 59));
+
+    ts_t gmt_spring_switch = to_timestamp(2024, int(MAR), spring_day_2024, 7, 0, 0);
+    ts_t et_after_spring = gmt_to_et(gmt_spring_switch);
+    assert(et_after_spring == to_timestamp(2024, int(MAR), spring_day_2024, 3, 0, 0));
+
+    int fall_day_2024 = first_sunday_month_day(2024, NOV);
+    ts_t gmt_fall_before = to_timestamp(2024, int(NOV), fall_day_2024, 6, 59, 59);
+    ts_t et_fall_before = gmt_to_et(gmt_fall_before);
+    assert(gmt_fall_before - et_fall_before == SEC_PER_HOUR * 4);
+
+    ts_t gmt_fall_after = to_timestamp(2024, int(NOV), fall_day_2024, 7, 0, 0);
+    ts_t et_fall_after = gmt_to_et(gmt_fall_after);
+    assert(gmt_fall_after - et_fall_after == SEC_PER_HOUR * 5);
+
+    int spring_day_2006 = first_sunday_month_day(2006, APR);
+    ts_t et_before_2006 = to_timestamp(2006, int(APR), spring_day_2006, 1, 59, 59);
+    ts_t gmt_before_2006 = et_to_gmt(et_before_2006);
+    assert(gmt_before_2006 == to_timestamp(2006, int(APR), spring_day_2006, 6, 59, 59));
+
+    ts_t et_after_2006 = to_timestamp(2006, int(APR), spring_day_2006, SWITCH_HOUR, 0, 0);
+    ts_t gmt_after_2006 = et_to_gmt(et_after_2006);
+    assert(gmt_after_2006 == to_timestamp(2006, int(APR), spring_day_2006, 6, 0, 0));
+
+    int fall_day_2006 = last_sunday_month_day(2006, OCT);
+    ts_t et_fall_2006_before = to_timestamp(2006, int(OCT), fall_day_2006, 1, 59, 59);
+    ts_t gmt_fall_2006_before = et_to_gmt(et_fall_2006_before);
+    assert(gmt_fall_2006_before == to_timestamp(2006, int(OCT), fall_day_2006, 5, 59, 59));
+
+    ts_t et_fall_2006_after = to_timestamp(2006, int(OCT), fall_day_2006, SWITCH_HOUR, 0, 0);
+    ts_t gmt_fall_2006_after = et_to_gmt(et_fall_2006_after);
+    assert(gmt_fall_2006_after == to_timestamp(2006, int(OCT), fall_day_2006, 7, 0, 0));
+
+    ts_t et_round_trip_winter = to_timestamp(2024, 1, 15, 12, 0, 0);
+    ts_t et_round_trip_summer = to_timestamp(2024, 7, 15, 12, 0, 0);
+    assert(et_round_trip_winter == gmt_to_et(et_to_gmt(et_round_trip_winter)));
+    assert(et_round_trip_summer == gmt_to_et(et_to_gmt(et_round_trip_summer)));
+
+    ts_t gmt_round_trip_winter = to_timestamp(2024, 1, 15, 17, 0, 0);
+    ts_t gmt_round_trip_summer = to_timestamp(2024, 7, 15, 16, 0, 0);
+    assert(gmt_round_trip_winter == et_to_gmt(gmt_to_et(gmt_round_trip_winter)));
+    assert(gmt_round_trip_summer == et_to_gmt(gmt_to_et(gmt_round_trip_summer)));
+
     for(int year : {2021, 2022, 2023, 2024}) {
         int day = last_sunday_month_day(year, OCT);
 
@@ -77,6 +133,30 @@ int main() {
     (void)gmt_eet_winter;
     (void)eet_summer;
     (void)gmt_eet_summer;
+    (void)spring_day_2024;
+    (void)et_before_spring;
+    (void)gmt_before_spring;
+    (void)gmt_spring_switch;
+    (void)et_after_spring;
+    (void)fall_day_2024;
+    (void)gmt_fall_before;
+    (void)et_fall_before;
+    (void)gmt_fall_after;
+    (void)et_fall_after;
+    (void)spring_day_2006;
+    (void)et_before_2006;
+    (void)gmt_before_2006;
+    (void)et_after_2006;
+    (void)gmt_after_2006;
+    (void)fall_day_2006;
+    (void)et_fall_2006_before;
+    (void)gmt_fall_2006_before;
+    (void)et_fall_2006_after;
+    (void)gmt_fall_2006_after;
+    (void)et_round_trip_winter;
+    (void)et_round_trip_summer;
+    (void)gmt_round_trip_winter;
+    (void)gmt_round_trip_summer;
 
     return 0;
 }

tests/time_zone_conversions_us_test.cpp

@@ -0,0 +1,93 @@
+#include <time_shield/time_zone_conversions.hpp>
+#include <time_shield/time_conversions.hpp>
+#include <cassert>
+
+/// \brief Tests US ET/CT conversions to UTC including DST transitions.
+int main() {
+    using namespace time_shield;
+
+    auto first_sunday_month_day = [](int year, int month) {
+        return 1 + (DAYS_PER_WEEK - day_of_week_date(year, month, 1)) % DAYS_PER_WEEK;
+    };
+
+    auto second_sunday_month_day = [&](int year, int month) {
+        return first_sunday_month_day(year, month) + 7;
+    };
+
+    ts_t ct_standard = to_timestamp(2024, 1, 15, 12, 0, 0);
+    ts_t gmt_ct_standard = ct_to_gmt(ct_standard);
+    assert(gmt_ct_standard == to_timestamp(2024, 1, 15, 18, 0, 0));
+
+    ts_t et_standard = to_timestamp(2024, 1, 15, 12, 0, 0);
+    ts_t gmt_et_standard = et_to_gmt(et_standard);
+    assert(gmt_et_standard == to_timestamp(2024, 1, 15, 17, 0, 0));
+
+    ts_t ct_summer = to_timestamp(2024, 7, 15, 12, 0, 0);
+    ts_t gmt_ct_summer = ct_to_gmt(ct_summer);
+    assert(gmt_ct_summer == to_timestamp(2024, 7, 15, 17, 0, 0));
+
+    ts_t et_summer = to_timestamp(2024, 7, 15, 12, 0, 0);
+    ts_t gmt_et_summer = et_to_gmt(et_summer);
+    assert(gmt_et_summer == to_timestamp(2024, 7, 15, 16, 0, 0));
+
+    ts_t ct_wrap_check = to_timestamp(2024, 6, 10, 9, 0, 0);
+    assert(ct_to_gmt(ct_wrap_check) == et_to_gmt(ct_wrap_check + SEC_PER_HOUR));
+
+    ts_t gmt_wrap_check = to_timestamp(2024, 6, 10, 15, 0, 0);
+    assert(gmt_to_ct(gmt_wrap_check) == gmt_to_et(gmt_wrap_check) - SEC_PER_HOUR);
+
+    int spring_day_2024 = second_sunday_month_day(2024, MAR);
+    ts_t et_before_spring = to_timestamp(2024, int(MAR), spring_day_2024, 1, 59, 59);
+    ts_t gmt_et_before_spring = et_to_gmt(et_before_spring);
+    assert(gmt_et_before_spring == to_timestamp(2024, int(MAR), spring_day_2024, 6, 59, 59));
+
+    ts_t et_after_spring = to_timestamp(2024, int(MAR), spring_day_2024, 3, 0, 0);
+    ts_t gmt_et_after_spring = et_to_gmt(et_after_spring);
+    assert(gmt_et_after_spring == to_timestamp(2024, int(MAR), spring_day_2024, 7, 0, 0));
+
+    ts_t ct_before_spring = to_timestamp(2024, int(MAR), spring_day_2024, 1, 59, 59);
+    ts_t gmt_before_spring = ct_to_gmt(ct_before_spring);
+    assert(gmt_before_spring == to_timestamp(2024, int(MAR), spring_day_2024, 6, 59, 59));
+
+    ts_t ct_after_spring = to_timestamp(2024, int(MAR), spring_day_2024, 3, 0, 0);
+    ts_t gmt_after_spring = ct_to_gmt(ct_after_spring);
+    assert(gmt_after_spring == to_timestamp(2024, int(MAR), spring_day_2024, 8, 0, 0));
+
+    int fall_day_2024 = first_sunday_month_day(2024, NOV);
+    ts_t et_repeat_hour = to_timestamp(2024, int(NOV), fall_day_2024, 1, 30, 0);
+    ts_t gmt_et_repeat_hour = et_to_gmt(et_repeat_hour);
+    assert(gmt_et_repeat_hour == to_timestamp(2024, int(NOV), fall_day_2024, 5, 30, 0));
+
+    ts_t ct_repeat_hour = to_timestamp(2024, int(NOV), fall_day_2024, 1, 30, 0);
+    ts_t gmt_repeat_hour = ct_to_gmt(ct_repeat_hour);
+    assert(gmt_repeat_hour == to_timestamp(2024, int(NOV), fall_day_2024, 7, 30, 0));
+
+    ts_t ct_after_fall = to_timestamp(2024, int(NOV), fall_day_2024, 2, 0, 0);
+    ts_t gmt_after_fall = ct_to_gmt(ct_after_fall);
+    assert(gmt_after_fall == to_timestamp(2024, int(NOV), fall_day_2024, 8, 0, 0));
+
+    (void)gmt_ct_standard;
+    (void)gmt_et_standard;
+    (void)gmt_ct_summer;
+    (void)gmt_et_summer;
+    (void)ct_wrap_check;
+    (void)gmt_wrap_check;
+    (void)spring_day_2024;
+    (void)et_before_spring;
+    (void)gmt_et_before_spring;
+    (void)et_after_spring;
+    (void)gmt_et_after_spring;
+    (void)ct_before_spring;
+    (void)gmt_before_spring;
+    (void)ct_after_spring;
+    (void)gmt_after_spring;
+    (void)fall_day_2024;
+    (void)et_repeat_hour;
+    (void)gmt_et_repeat_hour;
+    (void)ct_repeat_hour;
+    (void)gmt_repeat_hour;
+    (void)ct_after_fall;
+    (void)gmt_after_fall;
+
+    return 0;
+}