zig

commit 5f1392247d8bb0c6355f2986ff6fbf09a0885b6f (tree)
parent ed7f2588e409b6d154f4a08bd0029ef1e7beb06b
Author: Carl Åstholm <carl@astholm.se>
Date:   Wed,  5 Nov 2025 00:51:09 +0100

io: Redefine `Clock.real` to return timestamps relative to the POSIX/Unix epoch

`Clock.real` being defined to return timestamps relative to an
implementation-specific epoch means that there's currently no way for
the user to translate returned timestamps to actual calendar dates
without digging into implementation details of any particular `Io`
implementation. Redefining it to return timestamps relative to
1970-01-01T00:00:00Z fixes this problem.

There are other ways to solve this, such as adding a new vtable function
for returning the implementation-specific epoch, but in terms of
complexity this redefinition is by far the simplest solution and only
amounts to a simple 96-bit integer addition's worth of overhead on OSes
like Windows that use non-POSIX/Unix epochs.

Diffstat:
M
lib/std/Io.zig
 | 
9
++++++---

1 file changed, 6 insertions(+), 3 deletions(-)
diff --git a/lib/std/Io.zig b/lib/std/Io.zig
@@ -734,7 +734,7 @@ pub const Clock = enum {
     /// A settable system-wide clock that measures real (i.e. wall-clock)
     /// time. This clock is affected by discontinuous jumps in the system
     /// time (e.g., if the system administrator manually changes the
-    /// clock), and by frequency adjust‐ ments performed by NTP and similar
+    /// clock), and by frequency adjustments performed by NTP and similar
     /// applications.
     ///
     /// This clock normally counts the number of seconds since 1970-01-01
@@ -742,8 +742,11 @@ pub const Clock = enum {
     /// leap seconds; near a leap second it is typically adjusted by NTP to
     /// stay roughly in sync with UTC.
     ///
-    /// The epoch is implementation-defined. For example NTFS/Windows uses
-    /// 1601-01-01.
+    /// Timestamps returned by implementations of this clock represent time
+    /// elapsed since 1970-01-01T00:00:00Z, the POSIX/Unix epoch, ignoring
+    /// leap seconds. This is colloquially known as "Unix time". If the
+    /// underlying OS uses a different epoch for native timestamps (e.g.,
+    /// Windows, which uses 1601-01-01) they are translated accordingly.
     real,
     /// A nonsettable system-wide clock that represents time since some
     /// unspecified point in the past.