27 Time library [time]

27.9 Class template hh_­mm_­ss [time.hms]

27.9.1 Overview [time.hms.overview]

namespace std::chrono {
  template<class Duration> class hh_mm_ss {
  public:
    static constexpr unsigned fractional_width = see below;
    using precision                            = see below;

    constexpr hh_mm_ss() noexcept : hh_mm_ss{Duration::zero()} {}
    constexpr explicit hh_mm_ss(Duration d);

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

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

  private:
    bool            is_neg;     // exposition only
    chrono::hours   h;          // exposition only
    chrono::minutes m;          // exposition only
    chrono::seconds s;          // exposition only
    precision       ss;         // exposition only
  };
}
1
#
The hh_­mm_­ss class template splits a duration into a multi-field time structure hours:minutes:seconds and possibly subseconds, where subseconds will be a duration unit based on a non-positive power of 10.
The Duration template parameter dictates the precision to which the time is split.
A hh_­mm_­ss models negative durations with a distinct is_­negative getter that returns true when the input duration is negative.
The individual duration fields always return non-negative durations even when is_­negative() indicates the structure is representing a negative duration.
2
#
If Duration is not an instance of duration, the program is ill-formed.

27.9.2 Members [time.hms.members]

🔗
static constexpr unsigned fractional_width = see below;
1
#
fractional_­width is the number of fractional decimal digits represented by precision.
fractional_­width has the value of the smallest possible integer in the range [0, 18] such that precision will exactly represent all values of Duration.
If no such value of fractional_­width exists, then fractional_­width is 6.
[ Example
:
See Table 98 for some durations, the resulting fractional_­width, and the formatted fractional second output of Duration{1}.
Table 98: Examples for fractional_­width   [tab:time.hms.width]
Duration
fractional_­width
Formatted fractional second output
hours, minutes, and seconds
0
milliseconds
3
0.001
microseconds
6
0.000001
nanoseconds
9
0.000000001
duration<int, ratio<1, 2>>
1
0.5
duration<int, ratio<1, 3>>
6
0.333333
duration<int, ratio<1, 4>>
2
0.25
duration<int, ratio<1, 5>>
1
0.2
duration<int, ratio<1, 6>>
6
0.166666
duration<int, ratio<1, 7>>
6
0.142857
duration<int, ratio<1, 8>>
3
0.125
duration<int, ratio<1, 9>>
6
0.111111
duration<int, ratio<1, 10>>
1
0.1
duration<int, ratio<756, 625>>
4
0.2096
— end example
 ]
🔗
using precision = see below;
2
#
precision is 
duration<common_type_t<Duration::rep, seconds::rep>, ratio<1, >>
🔗
constexpr explicit hh_mm_ss(Duration d);
3
#
Effects: Constructs an object of type hh_­mm_­ss which represents the Duration d with precision precision.
  • (3.1)
    Initializes is_­neg with d < Duration​::​zero().
  • (3.2)
    Initializes h with duration_­cast<chrono​::​hours>(abs(d)).
  • (3.3)
    Initializes m with duration_­cast<chrono​::​minutes>(abs(d) - hours()).
  • (3.4)
    Initializes s with duration_­cast<chrono​::​seconds>(abs(d) - hours() - minutes()).
  • (3.5)
    If treat_­as_­floating_­point_­v<precision​::​rep> is true, initializes ss with abs(d) - hours() - minutes() - seconds().
    Otherwise, initializes ss with duration_­cast<precision>(abs(d) - hours() - minutes() - seconds()).
[ Note
:
When precision​::​rep is integral and precision​::​period is ratio<1>, subseconds() always returns a value equal to 0s.
— end note
 ]
4
#
Postconditions: If treat_­as_­floating_­point_­v<precision​::​rep> is true, to_­duration() returns d, otherwise to_­duration() returns duration_­cast<precision>(d).
🔗
constexpr bool is_negative() const noexcept;
5
#
Returns: is_­neg.
🔗
constexpr chrono::hours hours() const noexcept;
6
#
Returns: h.
🔗
constexpr chrono::minutes minutes() const noexcept;
7
#
Returns: m.
🔗
constexpr chrono::seconds seconds() const noexcept;
8
#
Returns: s.
🔗
constexpr precision subseconds() const noexcept;
9
#
Returns: ss.
🔗
constexpr precision to_duration() const noexcept;
10
#
Returns: If is_­neg, returns -(h + m + s + ss), otherwise returns h + m + s + ss.
🔗
constexpr explicit operator precision() const noexcept;
11
#
Returns: to_­duration().

27.9.3 Non-members [time.hms.nonmembers]

🔗
template<class charT, class traits, class Duration> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const hh_mm_ss<Duration>& hms);
1
#
Effects: Equivalent to: 
return os << format(os.getloc(), STATICALLY-WIDEN<charT>("{:%T}"), hms);
2
#
[ Example
: 
for (auto ms : {-4083007ms, 4083007ms, 65745123ms}) {
  hh_mm_ss hms{ms};
  cout << hms << '\n';
}
cout << hh_mm_ss{65745s} << '\n';
Produces the output (assuming the "C" locale): 
-01:08:03.007
01:08:03.007
18:15:45.123
18:15:45
— end example
 ]