cppdraft_translate/cppdraft/time/hms.md

[time.hms]

# 30 Time library [[time]](./#time)

## 30.9 Class template hh_mm_ss [time.hms]

### [30.9.1](#overview) Overview [[time.hms.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](#overview-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8423)

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[.](#overview-1.sentence-1)

The Duration template parameter dictates the precision
to which the time is split[.](#overview-1.sentence-2)

A hh_mm_ss models negative durations
with a distinct is_negative getter
that returns true when the input duration is negative[.](#overview-1.sentence-3)

The individual duration fields always return non-negative durations
even when is_negative() indicates
the structure is representing a negative duration[.](#overview-1.sentence-4)

[2](#overview-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8440)

If Duration is not a specialization of duration,
the program is ill-formed[.](#overview-2.sentence-1)

### [30.9.2](#members) Members [[time.hms.members]](time.hms.members)

[🔗](#members-itemdecl:1)

`static constexpr unsigned fractional_width = see below;
`

[1](#members-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8451)

fractional_width is the number of fractional decimal digits
represented by precision[.](#members-1.sentence-1)

fractional_width has the value
of the smallest possible integer in the range [0, 18] such thatprecision will exactly represent all values of Duration[.](#members-1.sentence-2)

If no such value of fractional_width exists, thenfractional_width is 6[.](#members-1.sentence-3)

[*Example [1](#members-example-1)*:

See Table [132](#tab:time.hms.width "Table 132: Examples for fractional_­width") for some durations,
the resulting fractional_width, and
the formatted fractional second output of Duration{1}[.](#members-1.sentence-4)

Table [132](#tab:time.hms.width) — Examples for fractional_width [[tab:time.hms.width]](./tab:time.hms.width)  

| [🔗](#tab:time.hms.width-row-1)<br>**Duration** | **fractional_width** | **Formatted fractional second output** |
| --- | --- | --- |
| [🔗](#tab:time.hms.width-row-2)<br>hours, minutes, and seconds | 0 |  |
| [🔗](#tab:time.hms.width-row-3)<br>milliseconds | 3 | 0.001 |
| [🔗](#tab:time.hms.width-row-4)<br>microseconds | 6 | 0.000001 |
| [🔗](#tab:time.hms.width-row-5)<br>nanoseconds | 9 | 0.000000001 |
| [🔗](#tab:time.hms.width-row-6)<br>duration<int, ratio<1, 2>> | 1 | 0.5 |
| [🔗](#tab:time.hms.width-row-7)<br>duration<int, ratio<1, 3>> | 6 | 0.333333 |
| [🔗](#tab:time.hms.width-row-8)<br>duration<int, ratio<1, 4>> | 2 | 0.25 |
| [🔗](#tab:time.hms.width-row-9)<br>duration<int, ratio<1, 5>> | 1 | 0.2 |
| [🔗](#tab:time.hms.width-row-10)<br>duration<int, ratio<1, 6>> | 6 | 0.166666 |
| [🔗](#tab:time.hms.width-row-11)<br>duration<int, ratio<1, 7>> | 6 | 0.142857 |
| [🔗](#tab:time.hms.width-row-12)<br>duration<int, ratio<1, 8>> | 3 | 0.125 |
| [🔗](#tab:time.hms.width-row-13)<br>duration<int, ratio<1, 9>> | 6 | 0.111111 |
| [🔗](#tab:time.hms.width-row-14)<br>duration<int, ratio<1, 10>> | 1 | 0.1 |
| [🔗](#tab:time.hms.width-row-15)<br>duration<int, ratio<756, 625>> | 4 | 0.2096 |

— *end example*]

[🔗](#members-itemdecl:2)

`using precision = see below;
`

[2](#members-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8502)

precision isduration<common_type_t<Duration::rep, seconds::rep>, ratio<1, 10fractional_width>>

[🔗](#members-itemdecl:3)

`constexpr explicit hh_mm_ss(Duration d);
`

[3](#members-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8514)

*Effects*: Constructs an object of type hh_mm_ss which represents the Duration d with precision precision[.](#members-3.sentence-1)

- [(3.1)](#members-3.1)

  Initializes is_neg with d < Duration​::​zero()[.](#members-3.1.sentence-1)

- [(3.2)](#members-3.2)

  Initializes h with duration_cast<chrono​::​hours>(abs(d))[.](#members-3.2.sentence-1)

- [(3.3)](#members-3.3)

  Initializes m with duration_cast<chrono​::​minutes>(abs(d) - hours())[.](#members-3.3.sentence-1)

- [(3.4)](#members-3.4)

  Initializes s with duration_cast<chrono​::​seconds>(abs(d) - hours() - minutes())[.](#members-3.4.sentence-1)

- [(3.5)](#members-3.5)

  If treat_as_floating_point_v<precision​::​rep> is true,
 initializes ss with abs(d) - hours() - minutes() - seconds()[.](#members-3.5.sentence-1)
  Otherwise, initializes ss with duration_cast<precision>(abs(d) - hours() - minutes() - seconds())[.](#members-3.5.sentence-2)

[*Note [1](#members-note-1)*:

When precision​::​rep is integral andprecision​::​period is ratio<1>,subseconds() always returns a value equal to 0s[.](#members-3.sentence-2)

— *end note*]

[4](#members-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8541)

*Postconditions*: If treat_as_floating_point_v<precision​::​rep> is true,to_duration() returns d,
otherwise to_duration() returns duration_cast<precision>(d)[.](#members-4.sentence-1)

[🔗](#lib:is_negative,hh_mm_ss)

`constexpr bool is_negative() const noexcept;
`

[5](#members-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8554)

*Returns*: is_neg[.](#members-5.sentence-1)

[🔗](#lib:hours,hh_mm_ss)

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

[6](#members-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8565)

*Returns*: h[.](#members-6.sentence-1)

[🔗](#lib:minutes,hh_mm_ss)

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

[7](#members-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8576)

*Returns*: m[.](#members-7.sentence-1)

[🔗](#lib:seconds,hh_mm_ss)

`constexpr chrono::seconds seconds() const noexcept;
`

[8](#members-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8587)

*Returns*: s[.](#members-8.sentence-1)

[🔗](#lib:subseconds,hh_mm_ss)

`constexpr precision subseconds() const noexcept;
`

[9](#members-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8598)

*Returns*: ss[.](#members-9.sentence-1)

[🔗](#lib:to_duration,hh_mm_ss)

`constexpr precision to_duration() const noexcept;
`

[10](#members-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8609)

*Returns*: If is_neg, returns -(h + m + s + ss),
otherwise returns h + m + s + ss[.](#members-10.sentence-1)

[🔗](#lib:operator_precision,hh_mm_ss)

`constexpr explicit operator precision() const noexcept;
`

[11](#members-11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8621)

*Returns*: to_duration()[.](#members-11.sentence-1)

### [30.9.3](#nonmembers) Non-members [[time.hms.nonmembers]](time.hms.nonmembers)

[🔗](#nonmembers-itemdecl:1)

`template<class charT, class traits, class Duration>
  basic_ostream<charT, traits>&
    operator<<(basic_ostream<charT, traits>& os, const hh_mm_ss<Duration>& hms);
`

[1](#nonmembers-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8635)

*Effects*: Equivalent to:return os << format(os.getloc(), *STATICALLY-WIDEN*<charT>("{:L%T}"), hms);

[2](#nonmembers-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L8642)

[*Example [1](#nonmembers-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*]