25 Time library [time]

25.9 Class template time_­of_­day [time.tod]

25.9.1 Overview [time.tod.overview]

namespace std::chrono {
  template<class Duration> class time_of_day;

  template<> class time_of_day<hours>;
  template<> class time_of_day<minutes>;
  template<> class time_of_day<seconds>;
  template<class Rep, class Period> class time_of_day<duration<Rep, Period>>;
}
1
#
The time_­of_­day class template splits a duration representing the time elapsed since midnight into a “broken down” time of day such as hours:minutes:seconds.
The Duration template parameter dictates the precision to which the time is broken down.
[ Note
:
This can vary from a coarse precision of hours to a very fine precision of nanoseconds.
— end note
 ]
A time_­of_­day object also tracks whether it should be output as a 12-hour time format or a 24-hour time format.
2
#
The primary time_­of_­day template is not defined.
Four specializations are provided to handle four different levels of precision.
3
#
Each specialization of time_­of_­day is a trivially copyable and standard-layout class type.

25.9.2 Hours precision [time.tod.hours]

namespace std::chrono {
  template<>
  class time_of_day<hours> {
  public:
    using precision = chrono::hours;

    time_of_day() = default;
    explicit constexpr time_of_day(chrono::hours since_midnight) noexcept;

    constexpr chrono::hours hours() const noexcept;

    explicit constexpr operator  precision()   const noexcept;
    constexpr          precision to_duration() const noexcept;

    constexpr void make24() noexcept;
    constexpr void make12() noexcept;
  };
}
1
#
[ Note
:
This specialization handles hours since midnight.
— end note
 ]
🔗
explicit constexpr time_of_day(chrono::hours since_midnight) noexcept;
2
#
Effects: Constructs an object of type time_­of_­day in 24-hour format corresponding to since_­midnight hours after 00:00:00.
3
#
Ensures: hours() returns the integral number of hours since_­midnight is after 00:00:00.
🔗
constexpr chrono::hours hours() const noexcept;
4
#
Returns: The stored hour of *this.
🔗
explicit constexpr operator precision() const noexcept;
5
#
Returns: The number of hours since midnight.
🔗
constexpr precision to_duration() const noexcept;
6
#
Returns: precision{*this}.
🔗
constexpr void make24() noexcept;
7
#
Effects: If *this is a 12-hour time, converts to a 24-hour time.
Otherwise, no effects.
🔗
constexpr void make12() noexcept;
8
#
Effects: If *this is a 24-hour time, converts to a 12-hour time.
Otherwise, no effects.

25.9.3 Minutes precision [time.tod.minutes]

namespace std::chrono {
  template<>
  class time_of_day<minutes> {
  public:
    using precision = chrono::minutes;

    time_of_day() = default;
    explicit constexpr time_of_day(chrono::minutes since_midnight) noexcept;

    constexpr chrono::hours    hours()   const noexcept;
    constexpr chrono::minutes  minutes() const noexcept;

    explicit constexpr operator precision()    const noexcept;
    constexpr          precision to_duration() const noexcept;

    constexpr void make24() noexcept;
    constexpr void make12() noexcept;
  };
}
1
#
[ Note
:
This specialization handles hours and minutes since midnight.
— end note
 ]
🔗
explicit constexpr time_of_day(minutes since_midnight) noexcept;
2
#
Effects: Constructs an object of type time_­of_­day in 24-hour format corresponding to since_­midnight minutes after 00:00:00.
3
#
Ensures: hours() returns the integral number of hours since_­midnight is after 00:00:00.
minutes() returns the integral number of minutes since_­midnight is after (00:00:00 + hours()).
🔗
constexpr chrono::hours hours() const noexcept;
4
#
Returns: The stored hour of *this.
🔗
constexpr chrono::minutes minutes() const noexcept;
5
#
Returns: The stored minute of *this.
🔗
explicit constexpr operator precision() const noexcept;
6
#
Returns: The number of minutes since midnight.
🔗
constexpr precision to_duration() const noexcept;
7
#
Returns: precision{*this}.
🔗
constexpr void make24() noexcept;
8
#
Effects: If *this is a 12-hour time, converts to a 24-hour time.
Otherwise, no effects.
🔗
constexpr void make12() noexcept;
9
#
Effects: If *this is a 24-hour time, converts to a 12-hour time.
Otherwise, no effects.

25.9.4 Seconds precision [time.tod.seconds]

namespace std::chrono {
  template<>
  class time_of_day<seconds> {
  public:
    using precision = chrono::seconds;

    time_of_day() = default;
    explicit constexpr time_of_day(chrono::seconds since_midnight) noexcept;

    constexpr chrono::hours   hours()   const noexcept;
    constexpr chrono::minutes minutes() const noexcept;
    constexpr chrono::seconds seconds() const noexcept;

    explicit constexpr operator  precision()   const noexcept;
    constexpr          precision to_duration() const noexcept;

    constexpr void make24() noexcept;
    constexpr void make12() noexcept;
  };
}
1
#
[ Note
:
This specialization handles hours, minutes, and seconds since midnight.
— end note
 ]
🔗
explicit constexpr time_of_day(seconds since_midnight) noexcept;
2
#
Effects: Constructs an object of type time_­of_­day in 24-hour format corresponding to since_­midnight seconds after 00:00:00.
3
#
Ensures: hours() returns the integral number of hours since_­midnight is after 00:00:00.
minutes() returns the integral number of minutes since_­midnight is after (00:00:00 + hours()).
seconds() returns the integral number of seconds since_­midnight is after (00:00:00 + hours() + minutes()).
🔗
constexpr chrono::hours hours() const noexcept;
4
#
Returns: The stored hour of *this.
🔗
constexpr chrono::minutes minutes() const noexcept;
5
#
Returns: The stored minute of *this.
🔗
constexpr chrono::seconds seconds() const noexcept;
6
#
Returns: The stored second of *this.
🔗
explicit constexpr operator precision() const noexcept;
7
#
Returns: The number of seconds since midnight.
🔗
constexpr precision to_duration() const noexcept;
8
#
Returns: precision{*this}.
🔗
constexpr void make24() noexcept;
9
#
Effects: If *this is a 12-hour time, converts to a 24-hour time.
Otherwise, no effects.
🔗
constexpr void make12() noexcept;
10
#
Effects: If *this is a 24-hour time, converts to a 12-hour time.
Otherwise, no effects.

25.9.5 Sub-second precision [time.tod.subsecond]

namespace std::chrono {
  template<class Rep, class Period>
  class time_of_day<duration<Rep, Period>> {
  public:
    using precision = duration<Rep, Period>;

    time_of_day() = default;
    explicit constexpr time_of_day(precision since_midnight) noexcept;

    constexpr chrono::hours     hours()      const noexcept;
    constexpr chrono::minutes   minutes()    const noexcept;
    constexpr chrono::seconds   seconds()    const noexcept;
    constexpr precision subseconds() const noexcept;

    explicit constexpr operator  precision()   const noexcept;
    constexpr          precision to_duration() const noexcept;

    constexpr void make24() noexcept;
    constexpr void make12() noexcept;
  };
}
1
#
This specialization shall not exist unless treat_­as_­floating_­point_­v<Rep> is false and duration<Rep, Period> is not convertible to seconds.
[ Note
:
This specialization handles hours, minutes, seconds, and fractional seconds since midnight.
Typical uses are with milliseconds, microseconds and nanoseconds.
— end note
 ]
🔗
explicit constexpr time_of_day(precision since_midnight) noexcept;
2
#
Effects: Constructs an object of type time_­of_­day in 24-hour format corresponding to since_­midnight fractional seconds after 00:00:00.
3
#
Ensures: hours() returns the integral number of hours since_­midnight is after 00:00:00.
minutes() returns the integral number of minutes since_­midnight is after (00:00:00 + hours()).
seconds() returns the integral number of seconds since_­midnight is after (00:00:00 + hours() + minutes()).
subseconds() returns the integral number of fractional seconds since_­midnight is after (00:00:00 + hours() + minutes() + seconds()).
🔗
constexpr chrono::hours hours() const noexcept;
4
#
Returns: The stored hour of *this.
🔗
constexpr chrono::minutes minutes() const noexcept;
5
#
Returns: The stored minute of *this.
🔗
constexpr chrono::seconds seconds() const noexcept;
6
#
Returns: The stored second of *this.
🔗
constexpr duration<Rep, Period> subseconds() const noexcept;
7
#
Returns: The stored subsecond of *this.
🔗
explicit constexpr operator precision() const noexcept;
8
#
Returns: The number of subseconds since midnight.
🔗
constexpr precision to_duration() const noexcept;
9
#
Returns: precision{*this}.
🔗
constexpr void make24() noexcept;
10
#
Effects: If *this is a 12-hour time, converts to a 24-hour time.
Otherwise, no effects.
🔗
constexpr void make12() noexcept;
11
#
Effects: If *this is a 24-hour time, converts to a 12-hour time.
Otherwise, no effects.

25.9.6 Formatted output [time.tod.io]

🔗
template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const time_of_day<hours>& t);
1
#
Effects: If t is a 24-hour time, outputs to os according to the format "%H00" ([time.format]).
Otherwise outputs to os according to the format "%I%p" ([time.format]).
2
#
Returns: os.
3
#
[ Example
: 
for (hours h : {1h, 18h}) {
  time_of_day<hours> tod(h);
  os << tod << '\n';
  tod.make12();
  os << tod << '\n';
}
Produces the output:
0100
1am
1800
6pm
— end example
 ]
🔗
template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const time_of_day<minutes>& t);
4
#
Effects: If t is a 24-hour time, outputs to os according to the format "%H:%M" ([time.format]).
Otherwise outputs to os according to the format "%I:%M%p" ([time.format]).
5
#
Returns: os.
[ Example
: 
for (minutes m : {68min, 1095min}) {
  time_of_day<minutes> tod(m);
  os << tod << '\n';
  tod.make12();
  os << tod << '\n';
}
Produces the output:
01:08
1:08am
18:15
6:15pm
— end example
 ]
🔗
template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const time_of_day<seconds>& t);
6
#
Effects: If t is a 24-hour time, outputs to os according to the format "%T" ([time.format]).
Otherwise outputs to os according to the format "%I:%M:%S%p" ([time.format]).
7
#
Returns: os.
[ Example
: 
for (seconds s : {4083s, 65745s}) {
  time_of_day<seconds> tod(s);
  os << tod << '\n';
  tod.make12();
  os << tod << '\n';
}
Produces the output:
01:08:03
1:08:03am
18:15:45
6:15:45pm
— end example
 ]
🔗
template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const time_of_day<duration<Rep, Period>>& t);
8
#
Effects: If t is a 24-hour time, outputs to os according to the format "%T" ([time.format]).
Otherwise outputs to os according to the format "%I:%M:%S%p" ([time.format]).
9
#
Returns: os.
[ Example
: 
for (milliseconds ms : {4083007ms, 65745123ms}) {
  time_of_day<seconds> tod(ms);
  os << tod << '\n';
  tod.make12();
  os << tod << '\n';
}
Produces the output:
01:08:03.007
1:08:03.007am
18:15:45.123
6:15:45.123pm
— end example
 ]