23 General utilities library [utilities]

23.17 Time utilities [time]

23.17.7 Clocks [time.clock]

23.17.7.1 Class system_­clock [time.clock.system]

23.17.7.1.1 Overview [time.clock.system.overview]

namespace std::chrono {
  class system_clock {
  public:
    using rep        = see below;
    using period     = ratio<unspecified, unspecified>;
    using duration   = chrono::duration<rep, period>;
    using time_point = chrono::time_point<system_clock>;
    static constexpr bool is_steady = unspecified;

    static time_point now() noexcept;

    // mapping to/from C type time_­t
    static time_t      to_time_t  (const time_point& t) noexcept;
    static time_point  from_time_t(time_t t) noexcept;
  };
}
Objects of type system_­clock represent wall clock time from the system-wide realtime clock.
Objects of type sys_­time<Duration> measure time since (and before) 1970-01-01 00:00:00 UTC excluding leap seconds.
This measure is commonly referred to as Unix time.
This measure facilitates an efficient mapping between sys_­time and calendar types ([time.cal]).
[Example
:

sys_­seconds{sys_­days{1970y/January/1}}.time_­since_­epoch() is 0s.

sys_­seconds{sys_­days{2000y/January/1}}.time_­since_­epoch() is 946'684'800s, which is 10'957 * 86'400s.

end example
]

23.17.7.1.2 Members [time.clock.system.members]

using system_clock::rep = unspecified;
Requires: system_­clock​::​duration​::​min() < system_­clock​::​duration​::​zero() shall be true.

[Note
:
This implies that rep is a signed type.
end note
]
static time_t to_time_t(const time_point& t) noexcept;
Returns: A time_­t object that represents the same point in time as t when both values are restricted to the coarser of the precisions of time_­t and time_­point.
It is implementation-defined whether values are rounded or truncated to the required precision.
static time_point from_time_t(time_t t) noexcept;
Returns: A time_­point object that represents the same point in time as t when both values are restricted to the coarser of the precisions of time_­t and time_­point.
It is implementation-defined whether values are rounded or truncated to the required precision.

23.17.7.1.3 Non-member functions [time.clock.system.nonmembers]

template<class charT, class traits, class Duration> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const sys_time<Duration>& tp);
Remarks: This operator shall not participate in overload resolution if treat_­as_­floating_­point_­v<typename Duration​::​rep> is true, or if Duration{1} >= days{1}.
Effects:
auto const dp = floor<days>(tp);
os << year_month_day{dp} << ' ' << time_of_day{tp-dp};
Returns: os.
[Example
:
cout << sys_seconds{0s} << '\n';                // 1970-01-01 00:00:00
cout << sys_seconds{946'684'800s} << '\n';      // 2000-01-01 00:00:00
cout << sys_seconds{946'688'523s} << '\n';      // 2000-01-01 01:02:03
end example
]
template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const sys_days& dp);
Effects: os << year_­month_­day{dp}.
Returns: os.
template<class charT, class traits, class Duration> basic_ostream<charT, traits>& to_stream(basic_ostream<charT, traits>& os, const charT* fmt, const sys_time<Duration>& tp);
Effects: Streams tp into os using the format specified by the NTCTS fmt.
fmt encoding follows the rules specified in [time.format].
If %Z is used, it will be replaced with "UTC" widened to charT.
If %z is used (or a modified variant of %z), an offset of 0min will be formatted.
Returns: os.
template<class charT, class traits, class Duration, class Alloc = allocator<charT>> basic_istream<charT, traits>& from_stream(basic_istream<charT, traits>& is, const charT* fmt, sys_time<Duration>& tp, basic_string<charT, traits, Alloc>* abbrev = nullptr, minutes* offset = nullptr);
Effects: Attempts to parse the input stream is into the sys_­time tp using the format flags given in the NTCTS fmt as specified in [time.parse].
If the parse fails to decode a valid date, is.setstate(ios_­base​::​failbit) shall be called and tp shall not be modified.
If %Z is used and successfully parsed, that value will be assigned to *abbrev if abbrev is non-null.
If %z (or a modified variant) is used and successfully parsed, that value will be assigned to *offset if offset is non-null.
Additionally, the parsed offset will be subtracted from the successfully parsed timestamp prior to assigning that difference to tp.
Returns: is.