convert offset date times

Author: oswalpalash

README.md

@@ -731,6 +731,9 @@ returns the shifted calendar date plus an offset-preserving `TimeTz`.
 `OffsetDateTime.formatIso` renders that local date, time, and numeric offset as
 one string in `types.OffsetDateTime.iso_buffer_len` bytes. Exact day-long
 (`+/-24:00`) offsets are accepted consistently and wider offsets remain invalid.
+`OffsetDateTime.toOffset(offset)` converts the same instant to another explicit
+offset while retaining nanosecond precision and shifting the wall-clock date as
+needed.
 
 ### Offline checks
 

docs/FEATURE_MATRIX.md

@@ -20,7 +20,7 @@ coverage; PostgreSQL rows marked live also run against PostgreSQL 16 in CI.
 | Native PostgreSQL driver | Complete | full-open `connect_timeout`; ordered grammar-validated SCRAM attributes/nonces, allocator-bounded salt handling, constant-time raw verifier comparison, and secure secret erasure; endpoint-owning `CancelHandle`; owned notifications; clean pooled listeners; direct and short-lease pooled COPY with owned output; lifecycle-aware command recovery and failure-safe teardown after transport loss | SCRAM ordering/grammar/extension/ambiguity/error/base64/password-erasure and exhaustive allocation-failure tests; cancellation/notification/COPY ownership and OOM tests; loopback drain-loss teardown regression; live post-teardown ownership, clean pool reuse, cancellation/COPY/notification recovery in CI |
 | Prepared statements | Complete | driver-selected `Statement(D)`; reusable ownership-safe SQLite query borrows with busy/deferred-close state and leak-free cache-copy bind scratch; explicit PostgreSQL direct/pool owners; owned prepared-query rows survive statement/pool teardown; consuming pooled-statement recovery when explicit Close fails; reusable named-bind scratch; session-monotonic PostgreSQL names; allocation-free cache teardown; unsigned OID metadata; narrow invalidation recovery | external façade contract; SQLite reuse/OOM/teardown/text-bind-cache/schema-change tests, deterministic PostgreSQL pooled-close-failure lease cleanup, and PostgreSQL protocol/direct/pool/cache/OOM/lifetime tests |
 | Safe parameter binding | Complete | positional/named APIs; two-allocation SQLite named-index resolution with one unbounded shared marker probe and exact OOM errors; single-allocation PostgreSQL Bind packets; typed canonical UUID and explicit ISO date/time/UTC-timestamp binding with optional-null support across direct and batched builder paths; full unsigned 16-bit parameter count; strict protocol C-strings | long-name/allocation-boundary/failure-atomicity, typed-wrapper batch/OOM, temporal-format/state/OOM, byte-parity, NUL, driver, and PostgreSQL live tests |
-| Typed row decoding | Complete | `Row.as`, `Row.asName`, `Row.to`, `zsql.decode`; strict allocation-free opt-in ISO temporal parser/formatters with signed/expanded years, BC-era input, second-precision offsets, exact day-long offsets, offset-aware TimeTz plus UTC decomposition, shifted timestamp decomposition, first-class combined OffsetDateTime parsing and formatting, exact named buffer lengths, and wrapper-based row mapping (including UTC-offset normalization or explicit offset policy); allocation-free struct mapping without arbitrary result-width caps; owned PostgreSQL bytea hex/escape decode; single-schema query contract; failure-atomic PostgreSQL result finalization | temporal valid/invalid/precision/full-range/BC/TimeTz/day-boundary/day-offset/offset-decomposition/offset-formatting/offset-date-time-parsing/public-alias/deterministic-round-trip/wrapper-mapping/buffer-boundary tests; QueryBuilder joined-binding exhaustive-OOM tests; malformed/OOM unit tests; forced column-name append/final-transfer failures; wide-result mapping, multi-result recovery, and core/live driver tests |
+| Typed row decoding | Complete | `Row.as`, `Row.asName`, `Row.to`, `zsql.decode`; strict allocation-free opt-in ISO temporal parser/formatters with signed/expanded years, BC-era input, second-precision offsets, exact day-long offsets, offset-aware TimeTz plus UTC decomposition, shifted timestamp decomposition, first-class combined OffsetDateTime parsing/formatting/offset conversion, exact named buffer lengths, and wrapper-based row mapping (including UTC-offset normalization or explicit offset policy); allocation-free struct mapping without arbitrary result-width caps; owned PostgreSQL bytea hex/escape decode; single-schema query contract; failure-atomic PostgreSQL result finalization | temporal valid/invalid/precision/full-range/BC/TimeTz/day-boundary/day-offset/offset-decomposition/offset-conversion/offset-formatting/offset-date-time-parsing/public-alias/deterministic-round-trip/wrapper-mapping/buffer-boundary tests; QueryBuilder joined-binding exhaustive-OOM tests; malformed/OOM unit tests; forced column-name append/final-transfer failures; wide-result mapping, multi-result recovery, and core/live driver tests |
 | Explicit owned rows | Complete | `OwnedRow`, `Row.getOwned`, `zsql.freeOwnedRows`; direct PostgreSQL deep copies without staging arrays; failure-atomic cross-driver `queryAll` append; documented invalidation boundary for borrowed values | exhaustive partial-OOM core/driver and append-growth tests plus external SQLite survival after rows, connection, and database teardown |
 | Connection pooling | Complete | `Pool(D)`, `Lease(D)`, allocator-owned connection configuration, health-aware consuming release, PostgreSQL protocol and SQLite setup/handle teardown outside the accounting mutex, opt-in PostgreSQL `DISCARD ALL` borrower isolation with pipelined restoration and a single asynchronous-event boundary, OOM-safe idle return and owned-result unwind, failed-open capacity wakeup, shutdown draining/wakeup, stats and timeouts | Cross-driver config-clone OOM/deferred-shutdown and deterministic failed-open infinite-waiter tests; SQLite release-OOM/result-unwind/responsive-setup-and-teardown/recovery tests; deterministic PostgreSQL stalled-peer mutex-liveness and stale-reset-notification regressions; PostgreSQL live session-state reset, reset-OOM consumption, release-OOM/result-unwind/shutdown tests |
 | Transactions and savepoints | Complete | authoritative SQLite/raw-SQL and explicit PostgreSQL `transactionOpen` boundaries; nested/idle/aborted states; typed PostgreSQL isolation/access/deferrable options; PostgreSQL `25P02` mapping; prepared-statement transition safety; failed-state savepoint recovery; failed SQLite best-effort rollback retains retryable transaction ownership; cross-driver bounded savepoint IDs; direct and pooled failure-scoped `withSavepoint`; `Tx(D)`, `Savepoint(D)`, `withTx` | SQLite state/rollback-retry/savepoint-exhaustion plus cross-driver savepoint-exhaustion/transaction-view tests plus raw-SQL SQLite transaction-state/pool-reuse tests and deterministic direct/pool scoped-savepoint tests and PostgreSQL direct/pool/live scoped-savepoint and typed-transaction-option tests |

src/core/types.zig

@@ -99,8 +99,7 @@ pub const TimeTz = struct {
             return error.InvalidArguments;
         }
 
-        const day_us = std.math.mul(i64, date.days_since_unix_epoch, 86_400_000_000) catch
-            return error.Overflow;
+        const day_us: i128 = @as(i128, date.days_since_unix_epoch) * 86_400_000_000;
         const local_us: i128 = @intCast(self.nanos_since_midnight / 1_000);
         const offset_us: i128 = @as(i128, self.offset_seconds) * 1_000_000;
         const total_us: i128 = @as(i128, day_us) + local_us - offset_us;
@@ -173,6 +172,43 @@ pub const Timestamp = struct {
             return self.time.utcTimestamp(self.date);
         }
 
+        /// Render the same instant using another explicit UTC offset. Unlike a
+        /// round trip through microsecond-precision `Timestamp`, this retains
+        /// all nine source nanoseconds.
+        pub fn toOffset(
+            self: Timestamp.OffsetDateTime,
+            offset_seconds: i32,
+        ) !Timestamp.OffsetDateTime {
+            if (self.time.nanos_since_midnight >= 86_400_000_000_000 or
+                self.time.offset_seconds < -86_400 or
+                self.time.offset_seconds > 86_400)
+            {
+                return error.InvalidArguments;
+            }
+            if (offset_seconds < -86_400 or offset_seconds > 86_400) {
+                return error.InvalidArguments;
+            }
+
+            const delta_ns: i128 = @as(i128, offset_seconds) * 1_000_000_000 -
+                @as(i128, self.time.offset_seconds) * 1_000_000_000;
+            const local_ns: i128 = @as(i128, self.date.days_since_unix_epoch) *
+                86_400_000_000_000 +
+                @as(i128, self.time.nanos_since_midnight) + delta_ns;
+            const days_i128 = @divFloor(local_ns, 86_400_000_000_000);
+            const nanos_since_midnight: u64 = @intCast(
+                @mod(local_ns, 86_400_000_000_000),
+            );
+            const days = std.math.cast(i32, days_i128) orelse return error.Overflow;
+
+            return .{
+                .date = .{ .days_since_unix_epoch = days },
+                .time = .{
+                    .nanos_since_midnight = nanos_since_midnight,
+                    .offset_seconds = offset_seconds,
+                },
+            };
+        }
+
         /// Format the shifted local date and timezone-aware time as one ISO
         /// string without allocation.
         pub fn formatIso(self: Timestamp.OffsetDateTime, buffer: []u8) ![]const u8 {
@@ -1190,6 +1226,83 @@ test "OffsetDateTime has a first-class public spelling" {
     try std.testing.expectEqual(Timestamp.OffsetDateTime, OffsetDateTime);
 }
 
+test "convert offset date/times while retaining nanoseconds" {
+    var buffer: [OffsetDateTime.iso_buffer_len]u8 = undefined;
+    const source = try parseIsoOffsetDateTime(
+        "2024-03-10T01:30:00.123456789-02:30",
+    );
+
+    const ahead = try source.toOffset(3_600);
+    try std.testing.expectEqual(@as(i32, 19792), ahead.date.days_since_unix_epoch);
+    try std.testing.expectEqual(
+        @as(u64, 5 * 3_600_000_000_000 + 123_456_789),
+        ahead.time.nanos_since_midnight,
+    );
+    try std.testing.expectEqual(@as(i32, 3_600), ahead.time.offset_seconds);
+    try std.testing.expectEqualStrings(
+        "2024-03-10T05:00:00.123456789+01:00",
+        try ahead.formatIso(&buffer),
+    );
+    try std.testing.expectEqual(
+        try source.utcTimestamp(),
+        try ahead.utcTimestamp(),
+    );
+
+    const behind = try (try parseIsoOffsetDateTime(
+        "2024-03-10T01:30:00.123456789+05:30",
+    )).toOffset(-9_000);
+    try std.testing.expectEqual(@as(i32, 19791), behind.date.days_since_unix_epoch);
+    try std.testing.expectEqual(
+        @as(u64, (17 * 3_600 + 30 * 60) * 1_000_000_000 + 123_456_789),
+        behind.time.nanos_since_midnight,
+    );
+    try std.testing.expectEqual(@as(i32, -9_000), behind.time.offset_seconds);
+
+    try std.testing.expectEqual(source, try source.toOffset(source.time.offset_seconds));
+    try std.testing.expectError(error.InvalidArguments, source.toOffset(86_401));
+}
+
+test "offset conversion covers deterministic temporal extrema" {
+    const offsets = [_]i32{ -86_400, 0, 86_400 };
+
+    for ([_]i64{ std.math.minInt(i64), 0, std.math.maxInt(i64) }) |unix_us| {
+        const timestamp = Timestamp{ .unix_us = unix_us };
+        for (offsets) |old_offset| {
+            const source = try timestamp.toOffsetDateTime(old_offset);
+            for (offsets) |new_offset| {
+                const converted = try source.toOffset(new_offset);
+                try std.testing.expectEqual(
+                    try timestamp.toOffsetDateTime(new_offset),
+                    converted,
+                );
+                try std.testing.expectEqual(timestamp, try converted.utcTimestamp());
+            }
+        }
+    }
+}
+
+test "reject invalid offset date/time conversion state" {
+    const date = try parseIsoDate("2024-03-10");
+    const valid_time = TimeTz{ .nanos_since_midnight = 0, .offset_seconds = 0 };
+    const valid = OffsetDateTime{ .date = date, .time = valid_time };
+    try std.testing.expectError(error.InvalidArguments, valid.toOffset(86_401));
+
+    const invalid_nanos = OffsetDateTime{
+        .date = date,
+        .time = .{
+            .nanos_since_midnight = 86_400_000_000_000,
+            .offset_seconds = 0,
+        },
+    };
+    try std.testing.expectError(error.InvalidArguments, invalid_nanos.toOffset(0));
+
+    const invalid_source_offset = OffsetDateTime{
+        .date = date,
+        .time = .{ .nanos_since_midnight = 0, .offset_seconds = 86_401 },
+    };
+    try std.testing.expectError(error.InvalidArguments, invalid_source_offset.toOffset(0));
+}
+
 test "parse exact day-long timezone offsets" {
     try std.testing.expectEqual(@as(i32, -86_400), (try parseIsoTimeTz("00:00:00-24:00")).offset_seconds);
     try std.testing.expectEqual(@as(i32, 86_400), (try parseIsoTimeTz("00:00:00+24:00")).offset_seconds);