cppdraft_translate/cppdraft/time/hms.md

[time.hms]

30 Time library [time]

30.9 Class template hh_mm_ss [time.hms]

30.9.1 Overview [time.hms.overview]

namespace std::chrono {template 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 structurehours: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 a specialization of duration, the program is ill-formed.

30.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 thatprecision will exactly represent all values of Duration.

If no such value of fractional_width exists, thenfractional_width is 6.

[Example 1:

See Table 132 for some durations, the resulting fractional_width, and the formatted fractional second output of Duration{1}.

Table 132 — 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 isduration<common_type_t<Duration::rep, seconds::rep>, ratio<1, 10fractional_width>>

🔗

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(abs(d) - hours() - minutes() - seconds()).

[Note 1:

When precision​::​rep is integral andprecision​::​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(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().

30.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("{:L%T}"), hms);

2

#

[Example 1: 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.00701:08:03.00718:15:45.12318:15:45

— end example]