feat: add parse_datetime_tz with UTC normalization

Introduces parse_datetime_tz() which accepts an optional timezone
offset ("+HH:MM", "+HH", "-HH:MM", "-HH", or "Z") and normalizes the
resulting microseconds-since-epoch to UTC by subtracting the offset.
When no offset is present, the behavior matches parse_datetime().

Adds 7 tests covering positive/negative offsets, short "+HH" form
(as returned by PostgreSQL), the ISO-8601 'Z' marker, fractional
seconds combined with an offset, and the no-offset fallback.

Author: renecannao

include/sql_engine/datetime_parse.h

@@ -13,6 +13,14 @@ int32_t parse_date(const char* s);
 // Parse "YYYY-MM-DD HH:MM:SS[.uuuuuu]" to microseconds since epoch.
 int64_t parse_datetime(const char* s);
 
+// Parse a datetime string that MAY include a timezone offset.
+// Accepts: "YYYY-MM-DD HH:MM:SS[.UUUUUU][+HH:MM|+HH|Z|-HH:MM|-HH]"
+// If a timezone offset is present, normalizes the timestamp to UTC
+// (by subtracting the offset).
+// If no timezone is present, behaves identically to parse_datetime().
+// Returns microseconds since UTC epoch 1970-01-01 00:00:00.
+int64_t parse_datetime_tz(const char* s);
+
 // Parse "HH:MM:SS[.uuuuuu]" to microseconds since midnight.
 int64_t parse_time(const char* s);
 

src/sql_engine/datetime_parse.cpp

@@ -106,6 +106,63 @@ int64_t parse_datetime(const char* s) {
     return us;
 }
 
+// Parse an optional timezone offset at position `s`. Advances `s` past the offset.
+// Returns the offset in microseconds (positive for east of UTC, negative for west).
+// Recognized formats: "Z", "+HH", "+HH:MM", "-HH", "-HH:MM" (also without colon).
+// Returns 0 if no offset found (does not advance `s`).
+static int64_t parse_tz_offset_us(const char*& s) {
+    if (!s || !*s) return 0;
+    if (*s == 'Z' || *s == 'z') {
+        ++s;
+        return 0;
+    }
+    if (*s != '+' && *s != '-') return 0;
+    int sign = (*s == '-') ? -1 : 1;
+    ++s;
+    int hours = parse_int(s, 2);
+    int minutes = 0;
+    if (*s == ':') {
+        ++s;
+        minutes = parse_int(s, 2);
+    } else if (*s >= '0' && *s <= '9') {
+        minutes = parse_int(s, 2);
+    }
+    int64_t offset_us = (static_cast<int64_t>(hours) * 3600LL
+                       + static_cast<int64_t>(minutes) * 60LL)
+                      * 1000000LL;
+    return sign * offset_us;
+}
+
+int64_t parse_datetime_tz(const char* s) {
+    if (!s || !*s) return 0;
+    const char* p = s;
+    int year = parse_int(p, 4);
+    if (*p == '-') ++p;
+    int month = parse_int(p, 2);
+    if (*p == '-') ++p;
+    int day = parse_int(p, 2);
+    if (*p == ' ' || *p == 'T') ++p;
+    int hour = parse_int(p, 2);
+    if (*p == ':') ++p;
+    int minute = parse_int(p, 2);
+    if (*p == ':') ++p;
+    int second = parse_int(p, 2);
+    int64_t frac = parse_frac_us(p);
+
+    int32_t days = days_since_epoch(year, month, day);
+    int64_t us = static_cast<int64_t>(days) * 86400LL * 1000000LL
+               + static_cast<int64_t>(hour) * 3600LL * 1000000LL
+               + static_cast<int64_t>(minute) * 60LL * 1000000LL
+               + static_cast<int64_t>(second) * 1000000LL
+               + frac;
+
+    // Parse optional timezone offset and normalize to UTC.
+    // "2024-06-15 14:30:00+05:30" means 14:30 local with offset +05:30.
+    // UTC = local - offset. So for positive offset (east of UTC), subtract.
+    int64_t tz_us = parse_tz_offset_us(p);
+    return us - tz_us;
+}
+
 int64_t parse_time(const char* s) {
     if (!s || !*s) return 0;
     bool negative = false;

tests/test_datetime_format.cpp

@@ -164,3 +164,55 @@ TEST(FormatDatetime, DateBeforeEpoch) {
     size_t n = format_datetime(us, buf, sizeof(buf));
     EXPECT_EQ(std::string(buf, n), "1969-07-20 20:17:40");
 }
+
+// ----- parse_datetime_tz timezone normalization -----
+
+TEST(DatetimeParseTimezoneTest, ParseDatetimeWithPositiveOffset) {
+    // "2024-06-15 14:30:00+05:30" -> normalized to UTC: 09:00:00 same day
+    int64_t us = parse_datetime_tz("2024-06-15 14:30:00+05:30");
+    int64_t expected_us = parse_datetime("2024-06-15 09:00:00");
+    EXPECT_EQ(us, expected_us);
+}
+
+TEST(DatetimeParseTimezoneTest, ParseDatetimeWithNegativeOffset) {
+    // "2024-06-15 14:30:00-08:00" -> UTC: 22:30:00 same day
+    int64_t us = parse_datetime_tz("2024-06-15 14:30:00-08:00");
+    int64_t expected_us = parse_datetime("2024-06-15 22:30:00");
+    EXPECT_EQ(us, expected_us);
+}
+
+TEST(DatetimeParseTimezoneTest, ParseDatetimeWithZOffset) {
+    // 'Z' is ISO-8601 UTC marker
+    int64_t us = parse_datetime_tz("2024-06-15 14:30:00Z");
+    int64_t expected_us = parse_datetime("2024-06-15 14:30:00");
+    EXPECT_EQ(us, expected_us);
+}
+
+TEST(DatetimeParseTimezoneTest, ParseDatetimeWithNoOffsetSameAsPlain) {
+    int64_t us_tz = parse_datetime_tz("2024-06-15 14:30:00");
+    int64_t us_plain = parse_datetime("2024-06-15 14:30:00");
+    EXPECT_EQ(us_tz, us_plain);
+}
+
+TEST(DatetimeParseTimezoneTest, ParseDatetimeWithZeroOffsetEquivalents) {
+    int64_t us1 = parse_datetime_tz("2024-06-15 14:30:00+00:00");
+    int64_t us2 = parse_datetime_tz("2024-06-15 14:30:00+00");
+    int64_t us3 = parse_datetime_tz("2024-06-15 14:30:00Z");
+    EXPECT_EQ(us1, us2);
+    EXPECT_EQ(us2, us3);
+}
+
+TEST(DatetimeParseTimezoneTest, ParseDatetimeWithFractionalAndTZ) {
+    // "2024-06-15 14:30:00.123456+05:30" -> 09:00:00.123456 UTC
+    int64_t us = parse_datetime_tz("2024-06-15 14:30:00.123456+05:30");
+    int64_t expected_us = parse_datetime("2024-06-15 09:00:00.123456");
+    EXPECT_EQ(us, expected_us);
+}
+
+TEST(DatetimeParseTimezoneTest, ParseDatetimeShortOffsetPostgres) {
+    // PostgreSQL often returns just "+05" without minutes
+    // "14:30:00+05" -> 09:30:00 UTC
+    int64_t us = parse_datetime_tz("2024-06-15 14:30:00+05");
+    int64_t expected_us = parse_datetime("2024-06-15 09:30:00");
+    EXPECT_EQ(us, expected_us);
+}