[time.clock.utc] - C++17 → C++20

Files changed (1) hide show

tmp/tmpiyxz8vy0/{from.md → to.md} +181 -0

tmp/tmpiyxz8vy0/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,181 @@

+### Class `utc_clock` <a id="time.clock.utc">[[time.clock.utc]]</a>
+#### Overview <a id="time.clock.utc.overview">[[time.clock.utc.overview]]</a>
+``` cpp
+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 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*]
+`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*]
+#### Member functions <a id="time.clock.utc.members">[[time.clock.utc.members]]</a>
+``` cpp
+static time_point now();
+```
+*Returns:* `from_sys(system_clock::now())`, or a more accurate value of
+`utc_time`.
+``` cpp
+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.
+``` cpp
+template<class Duration>
+  static utc_time<common_type_t<Duration, seconds>>
+    from_sys(const sys_time<Duration>& t);
+```
+*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*:
+``` cpp
+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*]
+#### Non-member functions <a id="time.clock.utc.nonmembers">[[time.clock.utc.nonmembers]]</a>
+``` cpp
+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:
+``` cpp
+return os << format(STATICALLY-WIDEN<charT>("{:%F %T}"), t);
+```
+[*Example 1*:
+``` cpp
+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:
+``` text
+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*]
+``` cpp
+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 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`.
+*Returns:* `is`.
+``` cpp
+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.
+``` cpp
+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.

Diff to HTML by rtfpessoa