20 General utilities library [utilities]

20.11 Time utilities [time]

20.11.5 Class template duration [time.duration]

1

A duration type measures time between two points in time (time_points). A duration has a representation which holds a count of ticks and a tick period. The tick period is the amount of time which occurs from one tick to the next, in units of seconds. It is expressed as a rational constant using the template ratio.

template <class Rep, class Period = ratio<1>>
class duration {
public:
  typedef Rep    rep;
  typedef Period period;
private:
  rep rep_;  // exposition only
public:
  // [time.duration.cons], construct/copy/destroy:
  constexpr duration() = default;
  template <class Rep2>
      constexpr explicit duration(const Rep2& r);
  template <class Rep2, class Period2>
     constexpr duration(const duration<Rep2, Period2>& d);
  ~duration() = default;
  duration(const duration&) = default;
  duration& operator=(const duration&) = default;

  // [time.duration.observer], observer:
  constexpr rep count() const;

  // [time.duration.arithmetic], arithmetic:
  constexpr duration  operator+() const;
  constexpr duration  operator-() const;
  duration& operator++();
  duration  operator++(int);
  duration& operator--();
  duration  operator--(int);

  duration& operator+=(const duration& d);
  duration& operator-=(const duration& d);

  duration& operator*=(const rep& rhs);
  duration& operator/=(const rep& rhs);
  duration& operator%=(const rep& rhs);
  duration& operator%=(const duration& rhs);

  // [time.duration.special], special values:
  static constexpr duration zero();
  static constexpr duration min();
  static constexpr duration max();
};
2

Requires: Rep shall be an arithmetic type or a class emulating an arithmetic type.

3

Remarks: If duration is instantiated with a duration type for the template argument Rep, the program is ill-formed.

4

Remarks: If Period is not a specialization of ratio, the program is ill-formed.

5

Remarks: If Period::num is not positive, the program is ill-formed.

6

Requires: Members of duration shall not throw exceptions other than those thrown by the indicated operations on their representations.

[ Example: 

duration<long, ratio<60>> d0;       // holds a count of minutes using a long
duration<long long, milli> d1;      // holds a count of milliseconds using a long long
duration<double, ratio<1, 30>>  d2; // holds a count with a tick period of $\frac{1}{30}$ of a second
                                    // (30 Hz) using a double

 — end example ]

20.11.5.1 duration constructors [time.duration.cons]

template <class Rep2> constexpr explicit duration(const Rep2& r);

1

Remarks: This constructor shall not participate in overload resolution unless Rep2 is implicitly convertible to rep and

  • (1.1)

    treat_as_floating_point<rep>::value is true or

  • (1.2)

    treat_as_floating_point<Rep2>::value is false.

[ Example: 

duration<int, milli> d(3);          // OK
duration<int, milli> d(3.5);        // error

 — end example ]

2

Effects: Constructs an object of type duration.

3

Postcondition: count() == static_cast<rep>(r).

template <class Rep2, class Period2> constexpr duration(const duration<Rep2, Period2>& d);

4

Remarks: This constructor shall not participate in overload resolution unless treat_as_floating_point<rep>::value is true or both ratio_divide<Period2, period>::den is 1 and treat_as_floating_point<Rep2>::value is false. [ Note: This requirement prevents implicit truncation error when converting between integral-based duration types. Such a construction could easily lead to confusion about the value of the duration.  — end note ] [ Example: 

duration<int, milli> ms(3);
duration<int, micro> us = ms;       // OK
duration<int, milli> ms2 = us;      // error

 — end example ]

5

Effects: Constructs an object of type duration, constructing rep_ from
duration_cast<duration>(d).count().

20.11.5.2 duration observer [time.duration.observer]

constexpr rep count() const;

1

Returns: rep_.

20.11.5.3 duration arithmetic [time.duration.arithmetic]

constexpr duration operator+() const;

1

Returns: *this.

constexpr duration operator-() const;

2

Returns: duration(-rep_);.

duration& operator++();

3

Effects: ++rep_.

4

Returns: *this.

duration operator++(int);

5

Returns: duration(rep_++);.

duration& operator--();

6

Effects: --rep_.

7

Returns: *this.

duration operator--(int);

8

Returns: duration(rep_--);.

duration& operator+=(const duration& d);

9

Effects: rep_ += d.count().

10

Returns: *this.

duration& operator-=(const duration& d);

11

Effects: rep_ -= d.count().

12

Returns: *this.

duration& operator*=(const rep& rhs);

13

Effects: rep_ *= rhs.

14

Returns: *this.

duration& operator/=(const rep& rhs);

15

Effects: rep_ /= rhs.

16

Returns: *this.

duration& operator%=(const rep& rhs);

17

Effects: rep_ %= rhs.

18

Returns: *this.

duration& operator%=(const duration& rhs);

19

Effects: rep_ %= rhs.count().

20

Returns: *this.

20.11.5.4 duration special values [time.duration.special]

static constexpr duration zero();

1

Returns: duration(duration_values<rep>::zero()).

static constexpr duration min();

2

Returns: duration(duration_values<rep>::min()).

static constexpr duration max();

3

Returns: duration(duration_values<rep>::max()).

20.11.5.5 duration non-member arithmetic [time.duration.nonmember]

1

In the function descriptions that follow, CD represents the return type of the function. CR(A,B) represents common_type<A, B>::type.

template <class Rep1, class Period1, class Rep2, class Period2> constexpr typename common_type<duration<Rep1, Period1>, duration<Rep2, Period2> >::type operator+(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);

2

Returns: CD(CD(lhs).count() + CD(rhs).count()).

template <class Rep1, class Period1, class Rep2, class Period2> constexpr typename common_type<duration<Rep1, Period1>, duration<Rep2, Period2> >::type operator-(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);

3

Returns: CD(CD(lhs).count() - CD(rhs).count()).

template <class Rep1, class Period, class Rep2> constexpr duration<typename common_type<Rep1, Rep2>::type, Period> operator*(const duration<Rep1, Period>& d, const Rep2& s);

4

Remarks: This operator shall not participate in overload resolution unless Rep2 is implicitly convertible to CR(Rep1, Rep2).

5

Returns: CD(CD(d).count() * s).

template <class Rep1, class Rep2, class Period> constexpr duration<typename common_type<Rep1, Rep2>::type, Period> operator*(const Rep1& s, const duration<Rep2, Period>& d);

6

Remarks: This operator shall not participate in overload resolution unless Rep1 is implicitly convertible to CR(Rep1, Rep2).

7

Returns: d * s.

template <class Rep1, class Period, class Rep2> constexpr duration<typename common_type<Rep1, Rep2>::type, Period> operator/(const duration<Rep1, Period>& d, const Rep2& s);

8

Remarks: This operator shall not participate in overload resolution unless Rep2 is implicitly convertible to CR(Rep1, Rep2) and Rep2 is not an instantiation of duration.

9

Returns: CD(CD(d).count() / s).

template <class Rep1, class Period1, class Rep2, class Period2> constexpr typename common_type<Rep1, Rep2>::type operator/(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);

10

Returns: CD(lhs).count() / CD(rhs).count().

template <class Rep1, class Period, class Rep2> constexpr duration<typename common_type<Rep1, Rep2>::type, Period> operator%(const duration<Rep1, Period>& d, const Rep2& s);

11

Remarks: This operator shall not participate in overload resolution unless Rep2 is implicitly convertible to CR(Rep1, Rep2) and Rep2 is not an instantiation of duration.

12

Returns: CD(CD(d).count() % s).

template <class Rep1, class Period1, class Rep2, class Period2> constexpr typename common_type<duration<Rep1, Period1>, duration<Rep2, Period2>>::type operator%(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);

13

Returns: CD(CD(lhs).count() % CD(rhs).count()).

20.11.5.6 duration comparisons [time.duration.comparisons]

1

In the function descriptions that follow, CT represents common_type<A, B>::type, where A and B are the types of the two arguments to the function.

template <class Rep1, class Period1, class Rep2, class Period2> constexpr bool operator==(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);

2

Returns: CT(lhs).count() == CT(rhs).count().

template <class Rep1, class Period1, class Rep2, class Period2> constexpr bool operator!=(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);

3

Returns: !(lhs == rhs).

template <class Rep1, class Period1, class Rep2, class Period2> constexpr bool operator<(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);

4

Returns: CT(lhs).count() < CT(rhs).count().

template <class Rep1, class Period1, class Rep2, class Period2> constexpr bool operator<=(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);

5

Returns: !(rhs < lhs).

template <class Rep1, class Period1, class Rep2, class Period2> constexpr bool operator>(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);

6

Returns: rhs < lhs.

template <class Rep1, class Period1, class Rep2, class Period2> constexpr bool operator>=(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);

7

Returns: !(lhs < rhs).

20.11.5.7 duration_cast [time.duration.cast]

template <class ToDuration, class Rep, class Period> constexpr ToDuration duration_cast(const duration<Rep, Period>& d);

1

Remarks: This function shall not participate in overload resolution unless ToDuration is an instantiation of duration.

2

Returns: Let CF be ratio_divide<Period, typename ToDuration::period>, and CR be common_type< typename ToDuration::rep, Rep, intmax_t>::type.

  • (2.1)

    If CF::num == 1 and CF::den == 1, returns 

    ToDuration(static_cast<typename ToDuration::rep>(d.count()))
  • (2.2)

    otherwise, if CF::num != 1 and CF::den == 1, returns 

    ToDuration(static_cast<typename ToDuration::rep>(
  static_cast<CR>(d.count()) * static_cast<CR>(CF::num)))
  • (2.3)

    otherwise, if CF::num == 1 and CF::den != 1, returns 

    ToDuration(static_cast<typename ToDuration::rep>(
  static_cast<CR>(d.count()) / static_cast<CR>(CF::den)))
  • (2.4)

    otherwise, returns 

    ToDuration(static_cast<typename ToDuration::rep>(
  static_cast<CR>(d.count()) * static_cast<CR>(CF::num) / static_cast<CR>(CF::den)))

Notes: This function does not use any implicit conversions; all conversions are done with static_cast. It avoids multiplications and divisions when it is known at compile time that one or more arguments is 1. Intermediate computations are carried out in the widest representation and only converted to the destination representation at the final step.