7.8 KiB
[time.clock.utc]
30 Time library [time]
30.7 Clocks [time.clock]
30.7.3 Class utc_clock [time.clock.utc]
30.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(); templatestatic sys_time<common_type_t<Duration, seconds>> to_sys(const utc_time& t); templatestatic utc_time<common_type_t<Duration, seconds>> from_sys(const sys_time& t); };}
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 constantsys_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]
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]
30.7.3.2 Member functions [time.clock.utc.members]
static time_point now();
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);
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);
Returns: A utc_time u, such thatu.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]
30.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);
Effects: Equivalent to:return os << format(os.getloc(), STATICALLY-WIDEN("{:L%F %T}"), t);
[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);
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 andtp 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.
Returns: is.
struct leap_second_info { bool is_leap_second; seconds elapsed; };
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);
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.