[time.clock.utc] (original) (raw)

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();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);};}

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 Cpp17TrivialClockunless 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]

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_pointduring a positive leap second insertion, the conversion counts that leap second as not inserted, and the last representable value of sys_timeprior 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_<charT>("{: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 isinto the utc_time tp using the format flags given in the NTCTS fmtas 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.

struct leap_second_info { bool is_leap_second; seconds elapsed;};

The type leap_second_infohas 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 trueif 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.