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
realtimeWall-clock time since the epoch.
realtime_coarseLower-resolution realtime clock.
realtime_alarmAlarm clock.
taiInternational Atomic Time, where the platform has it.
monotonicMonotonic clock, unaffected by wall-clock changes.
monotonic_coarse, monotonic_raw, monotonic_raw_approxCoarse/raw monotonic variants.
boottime, boottime_alarmTime since boot and its alarm clock.
process_cputime_id, thread_cputime_idCPU 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

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