27 Time library [time]

27.7 Clocks [time.clock]

27.7.3 Class utc_­clock [time.clock.utc]

27.7.3.1 Overview [time.clock.utc.overview]

namespace std::chrono { class utc_clock { public: using rep = a signed arithmetic type; using period = ratio<unspecified, unspecified>; using duration = chrono::duration<rep, period>; using time_point = chrono::time_point<utc_clock>; static constexpr bool is_steady = unspecified; static time_point now(); template<class Duration> static sys_time<common_type_t<Duration, seconds>> to_sys(const utc_time<Duration>& t); template<class Duration> static utc_time<common_type_t<Duration, seconds>> from_sys(const sys_time<Duration>& t); }; }
1
#
In contrast to sys_­time, which does not take leap seconds into account, utc_­clock and its associated time_­point, utc_­time, count time, including leap seconds, since 1970-01-01 00:00:00 UTC.
[Note 1:
The UTC time standard began on 1972-01-01 00:00:10 TAI. To measure time since this epoch instead, one can add/subtract the constant sys_­days{1972y/1/1} - sys_­days{1970y/1/1} (63'072'000s) from the utc_­time.
— end note]
[Example 1:
clock_­cast<utc_­clock>(sys_­seconds{sys_­days{1970y/January/1}}).time_­since_­epoch() is 0s.

clock_­cast<utc_­clock>(sys_­seconds{sys_­days{2000y/January/1}}).time_­since_­epoch() is 946'684'822s,
which is 10'957 * 86'400s + 22s.

— end example]
2
#
utc_­clock is not a Cpp17TrivialClock unless the implementation can guarantee that utc_­clock​::​now() does not propagate an exception.
[Note 2:
noexcept(from_­sys(system_­clock​::​now())) is false.
— end note]

27.7.3.2 Member functions [time.clock.utc.members]

🔗
static time_point now();
1
#
Returns: from_­sys(system_­clock​::​now()), or a more accurate value of utc_­time.
🔗
template<class Duration> static sys_time<common_type_t<Duration, seconds>> to_sys(const utc_time<Duration>& u);
2
#
Returns: A sys_­time t, such that from_­sys(t) == u if such a mapping exists.
Otherwise u represents a time_­point during a positive leap second insertion, the conversion counts that leap second as not inserted, and the last representable value of sys_­time prior to the insertion of the leap second is returned.
🔗
template<class Duration> static utc_time<common_type_t<Duration, seconds>> from_sys(const sys_time<Duration>& t);
3
#
Returns: A utc_­time u, such that u.time_­since_­epoch() - t.time_­since_­epoch() is equal to the sum of leap seconds that were inserted between t and 1970-01-01.
If t is exactly the date of leap second insertion, then the conversion counts that leap second as inserted.
[Example 1: auto t = sys_days{July/1/2015} - 2ns; auto u = utc_clock::from_sys(t); assert(u.time_since_epoch() - t.time_since_epoch() == 25s); t += 1ns; u = utc_clock::from_sys(t); assert(u.time_since_epoch() - t.time_since_epoch() == 25s); t += 1ns; u = utc_clock::from_sys(t); assert(u.time_since_epoch() - t.time_since_epoch() == 26s); t += 1ns; u = utc_clock::from_sys(t); assert(u.time_since_epoch() - t.time_since_epoch() == 26s); — end example]

27.7.3.3 Non-member functions [time.clock.utc.nonmembers]

🔗
template<class charT, class traits, class Duration> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const utc_time<Duration>& t);
1
#
Effects: Equivalent to: return os << format(STATICALLY-WIDEN<charT>("{:%F %T}"), t);
2
#
[Example 1: auto t = sys_days{July/1/2015} - 500ms; auto u = clock_cast<utc_clock>(t); for (auto i = 0; i < 8; ++i, u += 250ms) cout << u << " UTC\n";
Produces this output: 
2015-06-30 23:59:59.500 UTC
2015-06-30 23:59:59.750 UTC
2015-06-30 23:59:60.000 UTC
2015-06-30 23:59:60.250 UTC
2015-06-30 23:59:60.500 UTC
2015-06-30 23:59:60.750 UTC
2015-07-01 00:00:00.000 UTC
2015-07-01 00:00:00.250 UTC
— end example]
🔗
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, utc_time<Duration>& tp, basic_string<charT, traits, Alloc>* abbrev = nullptr, minutes* offset = nullptr);
3
#
Effects: Attempts to parse the input stream is into the utc_­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) is called and tp is not 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.
4
#
Returns: is.
🔗
struct leap_second_info { bool is_leap_second; seconds elapsed; };
5
#
The type leap_­second_­info has data members and special members specified above.
It has no base classes or members other than those specified.
🔗
template<class Duration> leap_second_info get_leap_second_info(const utc_time<Duration>& ut);
6
#
Returns: A leap_­second_­info lsi, where lsi.is_­leap_­second is true if ut is during a positive leap second insertion, and otherwise false.
lsi.elapsed is the sum of leap seconds between 1970-01-01 and ut.
If lsi.is_­leap_­second is true, the leap second referred to by ut is included in the sum.