25 Time library [time]

25.7 Clocks [time.clock]

1
#
The types defined in this subclause shall satisfy the Cpp17TrivialClock requirements ([time.clock.req]) unless otherwise specified.

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

25.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;
  };
}
1
#
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
 ]

25.7.1.2 Members [time.clock.system.members]

🔗
using system_clock::rep = unspecified;
1
#
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;
2
#
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;
3
#
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.

25.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);
1
#
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}.
2
#
Effects: 
auto const dp = floor<days>(tp);
os << year_month_day{dp} << ' ' << time_of_day{tp-dp};
3
#
Returns: os.
4
#
[ 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);
5
#
Effects: os << year_­month_­day{dp}.
6
#
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);
7
#
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.
8
#
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);
9
#
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.
10
#
Returns: is.

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

25.7.2.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.
[ Example
:

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
:
noexcept(from_­sys(system_­clock​::​now())) is false.
— end note
 ]

25.7.2.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<typename 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 leap second insertion and the last representable value of sys_­time prior to the insertion of the leap second is returned.
🔗
template<typename 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 number 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
: 
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
 ]

25.7.2.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: Calls to_­stream(os, fmt, t), where fmt is a string containing "%F %T" widened to charT.
2
#
Returns: os.
🔗
template<class charT, class traits, class Duration> basic_ostream<charT, traits>& to_stream(basic_ostream<charT, traits>& os, const charT* fmt, const utc_time<Duration>& tp);
3
#
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.
If tp represents a time during a leap second insertion, and if a seconds field is formatted, the integral portion of that format shall be "60" widened to charT.
4
#
Returns: os.
5
#
[ Example
: 
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);
6
#
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) 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.
7
#
Returns: is.

25.7.3 Class tai_­clock [time.clock.tai]

25.7.3.1 Overview [time.clock.tai.overview]

namespace std::chrono {
  class tai_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<tai_clock>;
    static constexpr bool is_steady = unspecified;

    static time_point now();

    template<class Duration>
      static utc_time<common_type_t<Duration, seconds>>
        to_utc(const tai_time<Duration>&) noexcept;
    template<class Duration>
      static tai_time<common_type_t<Duration, seconds>>
        from_utc(const utc_time<Duration>&) noexcept;
  };
}
1
#
The clock tai_­clock measures seconds since 1958-01-01 00:00:00 and is offset 10s ahead of UTC at this date.
That is, 1958-01-01 00:00:00 TAI is equivalent to 1957-12-31 23:59:50 UTC.
Leap seconds are not inserted into TAI.
Therefore every time a leap second is inserted into UTC, UTC falls another second behind TAI.
For example by 2000-01-01 there had been 22 leap seconds inserted so 2000-01-01 00:00:00 UTC is equivalent to 2000-01-01 00:00:32 TAI (22s plus the initial 10s offset).
2
#
tai_­clock is not a Cpp17TrivialClock unless the implementation can guarantee that tai_­clock​::​now() does not propagate an exception.
[ Note
:
noexcept(from_­utc(utc_­clock​::​now())) is false.
— end note
 ]

25.7.3.2 Member functions [time.clock.tai.members]

🔗
static time_point now();
1
#
Returns: from_­utc(utc_­clock​::​now()), or a more accurate value of tai_­time.
🔗
template<class Duration> static utc_time<common_type_t<Duration, seconds>> to_utc(const tai_time<Duration>& t) noexcept;
2
#
Returns: 
utc_time<common_type_t<Duration, seconds>>{t.time_since_epoch()} - 378691210s
[ Note
: 
378691210s == sys_days{1970y/January/1} - sys_days{1958y/January/1} + 10s
— end note
 ]
🔗
template<class Duration> static tai_time<common_type_t<Duration, seconds>> from_utc(const utc_time<Duration>& t) noexcept;
3
#
Returns: 
tai_time<common_type_t<Duration, seconds>>{t.time_since_epoch()} + 378691210s
[ Note
: 
378691210s == sys_days{1970y/January/1} - sys_days{1958y/January/1} + 10s
— end note
 ]

25.7.3.3 Non-member functions [time.clock.tai.nonmembers]

🔗
template<class charT, class traits, class Duration> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const tai_time<Duration>& t);
1
#
Effects: Calls to_­stream(os, fmt, t), where fmt is a string containing "%F %T" widened to charT.
2
#
Returns: os.
🔗
template<class charT, class traits, class Duration> basic_ostream<charT, traits>& to_stream(basic_ostream<charT, traits>& os, const charT* fmt, const tai_time<Duration>& tp);
3
#
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 "TAI".
If %z is used (or a modified variant of %z), an offset of 0min will be formatted.
The date and time formatted shall be equivalent to that formatted by a sys_­time initialized with: 
sys_time<Duration>{tp.time_since_epoch()} -
  (sys_days{1970y/January/1} - sys_days{1958y/January/1})
4
#
Returns: os.
5
#
[ Example
: 
auto st = sys_days{2000y/January/1};
auto tt = clock_cast<tai_clock>(st);
cout << format("%F %T %Z == ", st) << format("%F %T %Z\n", tt);
Produces this output:
2000-01-01 00:00:00 UTC == 2000-01-01 00:00:32 TAI
— 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, tai_time<Duration>& tp, basic_string<charT, traits, Alloc>* abbrev = nullptr, minutes* offset = nullptr);
6
#
Effects: Attempts to parse the input stream is into the tai_­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.
7
#
Returns: is.

25.7.4 Class gps_­clock [time.clock.gps]

25.7.4.1 Overview [time.clock.gps.overview]

namespace std::chrono {
  class gps_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<gps_clock>;
    static constexpr bool is_steady = unspecified;

    static time_point now();

    template<class Duration>
      static utc_time<common_type_t<Duration, seconds>>
        to_utc(const gps_time<Duration>&) noexcept;
    template<class Duration>
      static gps_time<common_type_t<Duration, seconds>>
        from_utc(const utc_time<Duration>&) noexcept;
  };
}
1
#
The clock gps_­clock measures seconds since the first Sunday of January, 1980 00:00:00 UTC.
Leap seconds are not inserted into GPS.
Therefore every time a leap second is inserted into UTC, UTC falls another second behind GPS.
Aside from the offset from 1958y/January/1 to 1980y/January/Sunday[1], GPS is behind TAI by 19s due to the 10s offset between 1958 and 1970 and the additional 9 leap seconds inserted between 1970 and 1980.
2
#
gps_­clock is not a Cpp17TrivialClock unless the implementation can guarantee that gps_­clock​::​now() does not propagate an exception.
[ Note
:
noexcept(from_­utc(utc_­clock​::​now())) is false.
— end note
 ]

25.7.4.2 Member functions [time.clock.gps.members]

🔗
static time_point now();
1
#
Returns: from_­utc(utc_­clock​::​now()), or a more accurate value of gps_­time.
🔗
template<class Duration> static utc_time<common_type_t<Duration, seconds>> to_utc(const gps_time<Duration>& t) noexcept;
2
#
Returns: 
gps_time<common_type_t<Duration, seconds>>{t.time_since_epoch()} + 315964809s
[ Note
: 
315964809s == sys_days{1980y/January/Sunday[1]} - sys_days{1970y/January/1} + 9s
— end note
 ]
🔗
template<class Duration> static gps_time<common_type_t<Duration, seconds>> from_utc(const utc_time<Duration>& t) noexcept;
3
#
Returns: 
gps_time<common_type_t<Duration, seconds>>{t.time_since_epoch()} - 315964809s
[ Note
: 
315964809s == sys_days{1980y/January/Sunday[1]} - sys_days{1970y/January/1} + 9s
— end note
 ]

25.7.4.3 Non-member functions [time.clock.gps.nonmembers]

🔗
template<class charT, class traits, class Duration> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const gps_time<Duration>& t);
1
#
Effects: Calls to_­stream(os, fmt, t), where fmt is a string containing "%F %T" widened to charT.
2
#
Returns: os.
🔗
template<class charT, class traits, class Duration> basic_ostream<charT, traits>& to_stream(basic_ostream<charT, traits>& os, const charT* fmt, const gps_time<Duration>& tp);
3
#
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 "GPS".
If %z is used (or a modified variant of %z), an offset of 0min will be formatted.
The date and time formatted shall be equivalent to that formatted by a sys_­time initialized with: 
sys_time<Duration>{tp.time_since_epoch()} +
  (sys_days{1980y/January/Sunday[1]} - sys_days{1970y/January/1})
4
#
Returns: os.
5
#
[ Example
: 
auto st = sys_days{2000y/January/1};
auto gt = clock_cast<gps_clock>(st);
cout << format("%F %T %Z == ", st) << format("%F %T %Z\n", gt);
Produces this output:
2000-01-01 00:00:00 UTC == 2000-01-01 00:00:13 GPS
— 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, gps_time<Duration>& tp, basic_string<charT, traits, Alloc>* abbrev = nullptr, minutes* offset = nullptr);
6
#
Effects: Attempts to parse the input stream is into the gps_­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.
7
#
Returns: is.

25.7.5 Class file_­clock [time.clock.file]

25.7.5.1 Overview [time.clock.file.overview]

namespace std::chrono {
  class file_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<file_clock>;
    static constexpr bool is_steady = unspecified;

    static time_point now() noexcept;

    // Conversion functions, see below
  };
}
1
#
The clock file_­clock is used to create the time_­point system used for file_­time_­type ([filesystems]).
Its epoch is unspecified.

25.7.5.2 Member functions [time.clock.file.members]

🔗
static time_point now();
1
#
Returns: A file_­clock​::​time_­point indicating the current time.
2
#
The class file_­clock shall provide precisely one of the following two sets of static member functions:
template<class Duration>
  static sys_time<see below>
    to_sys(const file_time<Duration>&);
template<class Duration>
  static file_time<see below>
    from_sys(const sys_time<Duration>&);
or:
template<class Duration>
  static utc_time<see below>
    to_utc(const file_time<Duration>&);
template<class Duration>
  static file_time<see below>
    from_utc(const utc_time<Duration>&);
These member functions shall provide time_­point conversions consistent with those specified by utc_­clock, tai_­clock, and gps_­clock.
The Duration of the resultant time_­point is computed from the Duration of the input time_­point.

25.7.5.3 Non-member functions [time.clock.file.nonmembers]

🔗
template<class charT, class traits, class Duration> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const file_time<Duration>& t);
1
#
Effects: Calls to_­stream(os, fmt, t), where fmt is a string containing "%F %T" widened to charT.
2
#
Returns: os.
🔗
template<class charT, class traits, class Duration> basic_ostream<charT, traits>& to_stream(basic_ostream<charT, traits>& os, const charT* fmt, const file_time<Duration>& tp);
3
#
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.
The date and time formatted shall be equivalent to that formatted by a sys_­time initialized with clock_­cast<system_­clock>(tp), or by a utc_­time initialized with clock_­cast<utc_­clock>(tp).
4
#
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, file_time<Duration>& tp, basic_string<charT, traits, Alloc>* abbrev = nullptr, minutes* offset = nullptr);
5
#
Effects: Attempts to parse the input stream is into the file_­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.
6
#
Returns: is.

25.7.6 Class steady_­clock [time.clock.steady]

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

    static time_point now() noexcept;
  };
}
1
#
Objects of class steady_­clock represent clocks for which values of time_­point never decrease as physical time advances and for which values of time_­point advance at a steady rate relative to real time.
That is, the clock may not be adjusted.

25.7.7 Class high_­resolution_­clock [time.clock.hires]

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

    static time_point now() noexcept;
  };
}
1
#
Objects of class high_­resolution_­clock represent clocks with the shortest tick period.
high_­resolution_­clock may be a synonym for system_­clock or steady_­clock.

25.7.8 Local time [time.clock.local]

1
#
The family of time points denoted by local_­time<Duration> are based on the pseudo clock local_­t.
local_­t has no member now() and thus does not meet the clock requirements.
Nevertheless local_­time<Duration> serves the vital role of representing local time with respect to a not-yet-specified time zone.
Aside from being able to get the current time, the complete time_­point algebra is available for local_­time<Duration> (just as for sys_­time<Duration>).
🔗
template<class charT, class traits, class Duration> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const local_time<Duration>& lt);
2
#
Effects: 
os << sys_time<Duration>{lt.time_since_epoch()};
3
#
Returns: os.
🔗
template<class charT, class traits, class Duration> basic_ostream<charT, traits>& to_stream(basic_ostream<charT, traits>& os, const charT* fmt, const local_time<Duration>& tp, const string* abbrev = nullptr, const seconds* offset_sec = nullptr);
4
#
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 *abbrev if abbrev is not equal to nullptr.
If abbrev is equal to nullptr (and %Z is used), os.setstate(ios_­base​::​failbit) shall be called.
If %z is used (or a modified variant of %z), it will be formatted with the value of *offset_­sec if offset_­sec is not equal to nullptr.
If %z (or a modified variant of %z) is used, and offset_­sec is equal to nullptr, then os.setstate(ios_­base​::​failbit) shall be called.
5
#
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, local_time<Duration>& tp, basic_string<charT, traits, Alloc>* abbrev = nullptr, minutes* offset = nullptr);
6
#
Effects: Attempts to parse the input stream is into the local_­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.
7
#
Returns: is.

25.7.9 time_­point conversions [time.clock.cast]

25.7.9.1 Class template clock_­time_­conversion [time.clock.conv]

namespace std::chrono {
  template<class DestClock, class SourceClock>
  struct clock_time_conversion {};
}
1
#
clock_­time_­conversion serves as a trait which can be used to specify how to convert a source time_­point of type time_­point<SourceClock, Duration> to a destination time_­point of type time_­point<DestClock, Duration> via a specialization: clock_­time_­conversion<DestClock, SourceClock>.
A specialization of clock_­time_­conversion<DestClock, SourceClock> shall provide a const-qualified operator() that takes a parameter of type time_­point<SourceClock, Duration> and returns a time_­point<DestClock, OtherDuration> representing an equivalent point in time.
OtherDuration is a chrono​::​duration whose specialization is computed from the input Duration in a manner which can vary for each clock_­time_­conversion specialization.
A program may specialize clock_­time_­conversion if at least one of the template parameters is a user-defined clock type.
2
#
Several specializations are provided by the implementation, as described in [time.clock.cast.id], [time.clock.cast.sys.utc], [time.clock.cast.sys], and [time.clock.cast.utc].

25.7.9.2 Identity conversions [time.clock.cast.id]

template<typename Clock>
struct clock_time_conversion<Clock, Clock> {
  template<class Duration>
    time_point<Clock, Duration>
      operator()(const time_point<Clock, Duration>& t) const;
};
🔗
template<class Duration> time_point<Clock, Duration> operator()(const time_point<Clock, Duration>& t) const;
1
#
Returns: t.
template<>
struct clock_time_conversion<system_clock, system_clock> {
  template<class Duration>
    sys_time<Duration>
      operator()(const sys_time<Duration>& t) const;
};
🔗
template<class Duration> sys_time<Duration> operator()(const sys_time<Duration>& t) const;
2
#
Returns: t.
template<>
struct clock_time_conversion<utc_clock, utc_clock> {
  template<class Duration>
    utc_time<Duration>
      operator()(const utc_time<Duration>& t) const;
};
🔗
template<class Duration> utc_time<Duration> operator()(const utc_time<Duration>& t) const;
3
#
Returns: t.

25.7.9.3 Conversions between system_­clock and utc_­clock [time.clock.cast.sys.utc]

template<>
struct clock_time_conversion<utc_clock, system_clock> {
  template<class Duration>
    utc_time<common_type_t<Duration, seconds>>
      operator()(const sys_time<Duration>& t) const;
};
🔗
template<class Duration> utc_time<common_type_t<Duration, seconds>> operator()(const sys_time<Duration>& t) const;
1
#
Returns: utc_­clock​::​from_­sys(t).
template<>
struct clock_time_conversion<system_clock, utc_clock> {
  template<class Duration>
    sys_time<common_type_t<Duration, seconds>>
      operator()(const utc_time<Duration>& t) const;
};
🔗
template<class Duration> sys_time<common_type_t<Duration, seconds>> operator()(const utc_time<Duration>& t) const;
2
#
Returns: utc_­clock​::​to_­sys(t).

25.7.9.4 Conversions between system_­clock and other clocks [time.clock.cast.sys]

template<class SourceClock>
struct clock_time_conversion<system_clock, SourceClock> {
  template<class Duration>
    auto operator()(const time_point<SourceClock, Duration>& t) const
      -> decltype(SourceClock::to_sys(t));
};
🔗
template<class Duration> auto operator()(const time_point<SourceClock, Duration>& t) const -> decltype(SourceClock::to_sys(t));
1
#
Remarks: This function does not participate in overload resolution unless SourceClock​::​to_­sys(t) is well-formed.
If SourceClock​::​to_­sys(t) does not return sys_­time<Duration>, where Duration is a valid chrono​::​duration specialization, the program is ill-formed.
2
#
Returns: SourceClock​::​to_­sys(t).
template<class DestClock>
struct clock_time_conversion<DestClock, system_clock> {
  template<class Duration>
    auto operator()(const sys_time<Duration>& t) const
      -> decltype(DestClock::from_sys(t));
};
🔗
template<class Duration> auto operator()(const sys_time<Duration>& t) const -> decltype(DestClock::from_sys(t));
3
#
Remarks: This function does not participate in overload resolution unless DestClock​::​from_­sys(t) is well-formed.
If DestClock​::​from_­sys(t) does not return time_­point<DestClock, Duration>, where Duration is a valid chrono​::​duration specialization, the program is ill-formed.
4
#
Returns: DestClock​::​from_­sys(t).

25.7.9.5 Conversions between utc_­clock and other clocks [time.clock.cast.utc]

template<class SourceClock>
struct clock_time_conversion<utc_clock, SourceClock> {
  template<class Duration>
    auto operator()(const time_point<SourceClock, Duration>& t) const
      -> decltype(SourceClock::to_utc(t));
};
🔗
template<class Duration> auto operator()(const time_point<SourceClock, Duration>& t) const -> decltype(SourceClock::to_utc(t));
1
#
Remarks: This function does not participate in overload resolution unless SourceClock​::​to_­utc(t) is well-formed.
If SourceClock​::​to_­utc(t) does not return utc_­time<Duration>, where Duration is a valid chrono​::​duration specialization, the program is ill-formed.
2
#
Returns: SourceClock​::​to_­utc(t).
template<class DestClock>
struct clock_time_conversion<DestClock, utc_clock> {
  template<class Duration>
    auto operator()(const utc_time<Duration>& t) const
      -> decltype(DestClock::from_utc(t));
};
🔗
template<class Duration> auto operator()(const utc_time<Duration>& t) const -> decltype(DestClock::from_utc(t));
3
#
Remarks: This function does not participate in overload resolution unless DestClock​::​from_­utc(t) is well-formed.
If DestClock​::​from_­utc(t) does not return time_­point<DestClock, Duration>, where Duration is a valid chrono​::​duration specialization, the program is ill-formed.
4
#
Returns: DestClock​::​from_­utc(t).

25.7.9.6 Function template clock_­cast [time.clock.cast.fn]

🔗
template<class DestClock, class SourceClock, class Duration> auto clock_cast(const time_point<SourceClock, Duration>& t);
1
#
Remarks: This function does not participate in overload resolution unless at least one of the following clock time conversion expressions is well-formed:
  • (1.1)
    clock_time_conversion<DestClock, SourceClock>{}(t)
  • (1.2)
    clock_time_conversion<DestClock, system_clock>{}(
    clock_time_conversion<system_clock, SourceClock>{}(t))
  • (1.3)
    clock_time_conversion<DestClock, utc_clock>{}(
    clock_time_conversion<utc_clock, SourceClock>{}(t))
  • (1.4)
    clock_time_conversion<DestClock, utc_clock>{}(
    clock_time_conversion<utc_clock, system_clock>{}(
        clock_time_conversion<system_clock, SourceClock>{}(t)))
  • (1.5)
    clock_time_conversion<DestClock, system_clock>{}(
    clock_time_conversion<system_clock, utc_clock>{}(
        clock_time_conversion<utc_clock, SourceClock>{}(t)))
A clock time conversion expression is considered better than another clock time conversion expression if it involves fewer operator() calls on clock_­time_­conversion specializations.
If, among the well-formed clock time conversion expressions from the above list, there is not a unique best expression, the clock_­cast is ambiguous and the program is ill-formed.
2
#
Returns: The best well-formed clock time conversion expression in the above list.