Ch26.16: Time
1. Two Time Types
| Type | Contents | Use |
|---|---|---|
posix_timespec64 |
tv_sec (signed 64-bit seconds since the Unix epoch) and
tv_nsec (32-bit nanoseconds). |
The machine and syscall representation. |
iso8601_timestamp |
year, month, day, hours,
minutes, seconds, nanoseconds and
timezone. |
The human/calendar representation. |
posix_timespec64 supports arithmetic: addition, subtraction, negation and
division by an integer. The operations normalize nanoseconds, so
1s + 500ms is a valid timespec with tv_nsec == 500000000, not a
raw field addition.
2. Clock Queries
posix_clock_gettime(id) returns a posix_timespec64.
posix_clock_getres(id) returns the clock resolution. Both are hosted APIs;
a freestanding target supplies its own clock.
posix_clock_id |
Meaning |
|---|---|
realtime | Wall-clock time since the epoch. |
realtime_coarse | Lower-resolution realtime clock. |
realtime_alarm | Alarm clock. |
tai | International Atomic Time, where the platform has it. |
monotonic | Monotonic clock, unaffected by wall-clock changes. |
monotonic_coarse, monotonic_raw, monotonic_raw_approx | Coarse/raw monotonic variants. |
boottime, boottime_alarm | Time since boot and its alarm clock. |
process_cputime_id, thread_cputime_id | CPU time of the process or thread. |
auto const now{::fast_io::posix_clock_gettime(::fast_io::posix_clock_id::realtime)};
Not every platform implements every clock. The unsupported ones fail through the herbception channel rather than returning a zero timestamp.
3. UTC and Local Conversion
| Entry | Meaning | Module |
|---|---|---|
utc(timespec) |
Convert a Unix timestamp to an ISO 8601 calendar value in UTC. | fast_io |
local(timespec, dstadj = posix_daylight()) |
Convert to local time; may query the platform timezone. | fast_io |
to_posix_timespec64(iso) |
Convert an ISO 8601 value back to a Unix timestamp. | fast_io |
to_posix_timespec64_ftu64 |
Convert from a fixed-point 64-bit timestamp. | fast_io |
posix_timespec64_to_ftu64 |
Convert to a fixed-point 64-bit timestamp. | fast_io |
posix_daylight() |
Whether local time currently observes daylight saving. | header-side |
timezone_name(dst) |
The platform timezone abbreviation. | header-side |
auto const t{::fast_io::posix_clock_gettime(::fast_io::posix_clock_id::realtime)};
auto const iso{::fast_io::utc(t)};
::fast_io::io::println(iso);
utc is constexpr and pure; local is not, because it
consults the platform timezone and daylight-saving state. Use utc for wire
timestamps and local only for display.
4. Printing and Scanning
iso8601_timestamp is printable and scannable directly. The printed form is
an ISO 8601 calendar string; the scanner accepts the same form.
::fast_io::iso8601_timestamp ts;
::fast_io::io::scan(in, ts);
::fast_io::io::println(ts);
For a Unix timestamp with a chosen fractional precision, wrap a
posix_timespec64 with mnp::fixed:
::fast_io::io::println(::fast_io::mnp::fixed(t, 3)); // seconds.milliseconds
::fast_io::io::println(::fast_io::mnp::comma_fixed(t, 6));
The precision is the number of fractional decimal digits. comma_fixed adds
digit grouping to the integer part.
std::chrono::duration values are printable when the chrono unit header is
included. The supported periods are nanoseconds, microseconds, milliseconds, seconds,
minutes, hours, days, weeks, months and years; the output includes the unit suffix.
5. Timezone Rules
utcnever depends on the process timezone.localasks the platform for the offset and DST state; passdstadjexplicitly when you have already resolved it.timezone_nameis display metadata; do not parse it as a stable identifier.- A timestamp with a non-zero
timezonefield is still an absolute instant plus an offset; converting it back withto_posix_timespec64normalizes it.
6. Module and Header Boundary
The fast_io module exports posix_timespec64,
iso8601_timestamp, utc, local,
to_posix_timespec64, to_posix_timespec64_ftu64 and
posix_timespec64_to_ftu64. The hosted unit adds
posix_clock_id, posix_clock_gettime and
posix_clock_getres. posix_daylight,
timezone_name and the chrono-duration print hooks are header-side.
Key Takeaways
posix_timespec64is the machine timestamp;iso8601_timestampis the calendar value.posix_clock_gettimereturns a normalized timespec; unsupported clocks fail.utcis pure and constexpr;localqueries the platform timezone.- ISO 8601 values are printable and scannable directly.
mnp::fixedandcomma_fixedprint Unix timestamps with a chosen fractional precision.- Chrono durations print with unit suffixes when the chrono unit header is included.
- Use UTC for wire formats and local time only for display.