27 Time library [time]

27.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.
namespace std::chrono {
  template<class Rep, class Period = ratio<1>>
  class duration {
  public:
    using rep    = Rep;
    using period = typename Period::type;

  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 common_type_t<duration> operator+() const;
    constexpr common_type_t<duration> operator-() const;
    constexpr duration& operator++();
    constexpr duration  operator++(int);
    constexpr duration& operator--();
    constexpr duration  operator--(int);

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

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

    // [time.duration.special], special values
    static constexpr duration zero() noexcept;
    static constexpr duration min() noexcept;
    static constexpr duration max() noexcept;
  };
}
2
#
Rep shall be an arithmetic type or a class emulating an arithmetic type.
If duration is instantiated with a duration type as the argument for the template parameter Rep, the program is ill-formed.
3
#
If Period is not a specialization of ratio, the program is ill-formed.
If Period​::​num is not positive, the program is ill-formed.
4
#
Members of duration do not throw exceptions other than those thrown by the indicated operations on their representations.
5
#
The defaulted copy constructor of duration shall be a constexpr function if and only if the required initialization of the member rep_­ for copy and move, respectively, would satisfy the requirements for a constexpr function.
6
#
[ 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  of a second
                                    // (30 Hz) using a double
— end example
 ]

27.5.1 Constructors [time.duration.cons]

🔗
template<class Rep2> constexpr explicit duration(const Rep2& r);
1
#
Constraints: is_­convertible_­v<const Rep2&, rep> is true and
  • (1.1)
    treat_­as_­floating_­point_­v<rep> is true or
  • (1.2)
    treat_­as_­floating_­point_­v<Rep2> is false.
[ Example
: 
duration<int, milli> d(3);          // OK
duration<int, milli> d(3.5);        // error
— end example
 ]
2
#
Postconditions: count() == static_­cast<rep>(r).
🔗
template<class Rep2, class Period2> constexpr duration(const duration<Rep2, Period2>& d);
3
#
Constraints: No overflow is induced in the conversion and treat_­as_­floating_­point_­v<rep> is true or both ratio_­divide<Period2, period>​::​den is 1 and treat_­as_­floating_­point_­v<Rep2> 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
 ]
4
#
Effects: Initializes rep_­ with duration_­cast<duration>(d).count().

27.5.2 Observer [time.duration.observer]

🔗
constexpr rep count() const;
1
#
Returns: rep_­.

27.5.3 Arithmetic [time.duration.arithmetic]

🔗
constexpr common_type_t<duration> operator+() const;
1
#
Returns: common_­type_­t<duration>(*this).
🔗
constexpr common_type_t<duration> operator-() const;
2
#
Returns: common_­type_­t<duration>(-rep_­).
🔗
constexpr duration& operator++();
3
#
Effects: Equivalent to: ++rep_­.
4
#
Returns: *this.
🔗
constexpr duration operator++(int);
5
#
Effects: Equivalent to: return duration(rep_­++);
🔗
constexpr duration& operator--();
6
#
Effects: Equivalent to: --rep_­.
7
#
Returns: *this.
🔗
constexpr duration operator--(int);
8
#
Effects: Equivalent to: return duration(rep_­--);
🔗
constexpr duration& operator+=(const duration& d);
9
#
Effects: Equivalent to: rep_­ += d.count().
10
#
Returns: *this.
🔗
constexpr duration& operator-=(const duration& d);
11
#
Effects: Equivalent to: rep_­ -= d.count().
12
#
Returns: *this.
🔗
constexpr duration& operator*=(const rep& rhs);
13
#
Effects: Equivalent to: rep_­ *= rhs.
14
#
Returns: *this.
🔗
constexpr duration& operator/=(const rep& rhs);
15
#
Effects: Equivalent to: rep_­ /= rhs.
16
#
Returns: *this.
🔗
constexpr duration& operator%=(const rep& rhs);
17
#
Effects: Equivalent to: rep_­ %= rhs.
18
#
Returns: *this.
🔗
constexpr duration& operator%=(const duration& rhs);
19
#
Effects: Equivalent to: rep_­ %= rhs.count().
20
#
Returns: *this.

27.5.4 Special values [time.duration.special]

🔗
static constexpr duration zero() noexcept;
1
#
Returns: duration(duration_­values<rep>​::​zero()).
🔗
static constexpr duration min() noexcept;
2
#
Returns: duration(duration_­values<rep>​::​min()).
🔗
static constexpr duration max() noexcept;
3
#
Returns: duration(duration_­values<rep>​::​max()).

27.5.5 Non-member arithmetic [time.duration.nonmember]

1
#
In the function descriptions that follow, unless stated otherwise, let CD represent the return type of the function.
🔗
template<class Rep1, class Period1, class Rep2, class Period2> constexpr common_type_t<duration<Rep1, Period1>, duration<Rep2, Period2>> 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 common_type_t<duration<Rep1, Period1>, duration<Rep2, Period2>> 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<common_type_t<Rep1, Rep2>, Period> operator*(const duration<Rep1, Period>& d, const Rep2& s);
4
#
Constraints: is_­convertible_­v<const Rep2&, common_­type_­t<Rep1, Rep2>> is true.
5
#
Returns: CD(CD(d).count() * s).
🔗
template<class Rep1, class Rep2, class Period> constexpr duration<common_type_t<Rep1, Rep2>, Period> operator*(const Rep1& s, const duration<Rep2, Period>& d);
6
#
Constraints: is_­convertible_­v<const Rep1&, common_­type_­t<Rep1, Rep2>> is true.
7
#
Returns: d * s.
🔗
template<class Rep1, class Period, class Rep2> constexpr duration<common_type_t<Rep1, Rep2>, Period> operator/(const duration<Rep1, Period>& d, const Rep2& s);
8
#
Constraints: is_­convertible_­v<const Rep2&, common_­type_­t<Rep1, Rep2>> is true and Rep2 is not a specialization of duration.
9
#
Returns: CD(CD(d).count() / s).
🔗
template<class Rep1, class Period1, class Rep2, class Period2> constexpr common_type_t<Rep1, Rep2> operator/(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);
10
#
Let CD be common_­type_­t<duration<Rep1, Period1>, duration<Rep2, Period2>>.
11
#
Returns: CD(lhs).count() / CD(rhs).count().
🔗
template<class Rep1, class Period, class Rep2> constexpr duration<common_type_t<Rep1, Rep2>, Period> operator%(const duration<Rep1, Period>& d, const Rep2& s);
12
#
Constraints: is_­convertible_­v<const Rep2&, common_­type_­t<Rep1, Rep2>> is true and Rep2 is not a specialization of duration.
13
#
Returns: CD(CD(d).count() % s).
🔗
template<class Rep1, class Period1, class Rep2, class Period2> constexpr common_type_t<duration<Rep1, Period1>, duration<Rep2, Period2>> operator%(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);
14
#
Returns: CD(CD(lhs).count() % CD(rhs).count()).

27.5.6 Comparisons [time.duration.comparisons]

1
#
In the function descriptions that follow, CT represents common_­type_­t<A, B>, 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: 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);
4
#
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);
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: !(lhs < rhs).
🔗
template<class Rep1, class Period1, class Rep2, class Period2> requires three_­way_­comparable<typename CT::rep> constexpr auto operator<=>(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);
7
#
Returns: CT(lhs).count() <=> CT(rhs).count().

27.5.7 Conversions [time.duration.cast]

🔗
template<class ToDuration, class Rep, class Period> constexpr ToDuration duration_cast(const duration<Rep, Period>& d);
1
#
Constraints: ToDuration is a specialization 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)))
3
#
[ Note
:
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.
— end note
 ]
🔗
template<class ToDuration, class Rep, class Period> constexpr ToDuration floor(const duration<Rep, Period>& d);
4
#
Constraints: ToDuration is a specialization of duration.
5
#
Returns: The greatest result t representable in ToDuration for which t <= d.
🔗
template<class ToDuration, class Rep, class Period> constexpr ToDuration ceil(const duration<Rep, Period>& d);
6
#
Constraints: ToDuration is a specialization of duration.
7
#
Returns: The least result t representable in ToDuration for which t >= d.
🔗
template<class ToDuration, class Rep, class Period> constexpr ToDuration round(const duration<Rep, Period>& d);
8
#
Constraints: ToDuration is a specialization of duration and treat_­as_­floating_­point_­v<typename ToDuration​::​rep> is false.
9
#
Returns: The value of ToDuration that is closest to d.
If there are two closest values, then return the value t for which t % 2 == 0.

27.5.8 Suffixes for duration literals [time.duration.literals]

1
#
This subclause describes literal suffixes for constructing duration literals.
The suffixes h, min, s, ms, us, ns denote duration values of the corresponding types hours, minutes, seconds, milliseconds, microseconds, and nanoseconds respectively if they are applied to integer-literals.
2
#
If any of these suffixes are applied to a floating-point-literal the result is a chrono​::​duration literal with an unspecified floating-point representation.
3
#
If any of these suffixes are applied to an integer-literal and the resulting chrono​::​duration value cannot be represented in the result type because of overflow, the program is ill-formed.
4
#
[ Example
:
The following code shows some duration literals.
using namespace std::chrono_literals;
auto constexpr aday=24h;
auto constexpr lesson=45min;
auto constexpr halfanhour=0.5h;
— end example
 ]
🔗
constexpr chrono::hours operator""h(unsigned long long hours); constexpr chrono::duration<unspecified, ratio<3600, 1>> operator""h(long double hours);
5
#
Returns: A duration literal representing hours hours.
🔗
constexpr chrono::minutes operator""min(unsigned long long minutes); constexpr chrono::duration<unspecified, ratio<60, 1>> operator""min(long double minutes);
6
#
Returns: A duration literal representing minutes minutes.
🔗
constexpr chrono::seconds operator""s(unsigned long long sec); constexpr chrono::duration<unspecified> operator""s(long double sec);
7
#
Returns: A duration literal representing sec seconds.
8
#
[ Note
:
The same suffix s is used for basic_­string but there is no conflict, since duration suffixes apply to numbers and string literal suffixes apply to character array literals.
— end note
 ]
🔗
constexpr chrono::milliseconds operator""ms(unsigned long long msec); constexpr chrono::duration<unspecified, milli> operator""ms(long double msec);
9
#
Returns: A duration literal representing msec milliseconds.
🔗
constexpr chrono::microseconds operator""us(unsigned long long usec); constexpr chrono::duration<unspecified, micro> operator""us(long double usec);
10
#
Returns: A duration literal representing usec microseconds.
🔗
constexpr chrono::nanoseconds operator""ns(unsigned long long nsec); constexpr chrono::duration<unspecified, nano> operator""ns(long double nsec);
11
#
Returns: A duration literal representing nsec nanoseconds.

27.5.9 Algorithms [time.duration.alg]

🔗
template<class Rep, class Period> constexpr duration<Rep, Period> abs(duration<Rep, Period> d);
1
#
Constraints: numeric_­limits<Rep>​::​is_­signed is true.
2
#
Returns: If d >= d.zero(), return d, otherwise return -d.

27.5.10 I/O [time.duration.io]

🔗
template<class charT, class traits, class Rep, class Period> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const duration<Rep, Period>& d);
1
#
Effects: Inserts the duration d onto the stream os as if it were implemented as follows: 
basic_ostringstream<charT, traits> s;
s.flags(os.flags());
s.imbue(os.getloc());
s.precision(os.precision());
s << d.count() << units-suffix;
return os << s.str();
where units-suffix depends on the type Period​::​type as follows:
  • (1.1)
    If Period​::​type is atto, units-suffix is "as".
  • (1.2)
    Otherwise, if Period​::​type is femto, units-suffix is "fs".
  • (1.3)
    Otherwise, if Period​::​type is pico, units-suffix is "ps".
  • (1.4)
    Otherwise, if Period​::​type is nano, units-suffix is "ns".
  • (1.5)
    Otherwise, if Period​::​type is micro, it is implementation-defined whether units-suffix is "Ξs" ("\u00b5\u0073") or "us".
  • (1.6)
    Otherwise, if Period​::​type is milli, units-suffix is "ms".
  • (1.7)
    Otherwise, if Period​::​type is centi, units-suffix is "cs".
  • (1.8)
    Otherwise, if Period​::​type is deci, units-suffix is "ds".
  • (1.9)
    Otherwise, if Period​::​type is ratio<1>, units-suffix is "s".
  • (1.10)
    Otherwise, if Period​::​type is deca, units-suffix is "das".
  • (1.11)
    Otherwise, if Period​::​type is hecto, units-suffix is "hs".
  • (1.12)
    Otherwise, if Period​::​type is kilo, units-suffix is "ks".
  • (1.13)
    Otherwise, if Period​::​type is mega, units-suffix is "Ms".
  • (1.14)
    Otherwise, if Period​::​type is giga, units-suffix is "Gs".
  • (1.15)
    Otherwise, if Period​::​type is tera, units-suffix is "Ts".
  • (1.16)
    Otherwise, if Period​::​type is peta, units-suffix is "Ps".
  • (1.17)
    Otherwise, if Period​::​type is exa, units-suffix is "Es".
  • (1.18)
    Otherwise, if Period​::​type is ratio<60>, units-suffix is "min".
  • (1.19)
    Otherwise, if Period​::​type is ratio<3600>, units-suffix is "h".
  • (1.20)
    Otherwise, if Period​::​type is ratio<86400>, units-suffix is "d".
  • (1.21)
    Otherwise, if Period​::​type​::​den == 1, units-suffix is "[num]s".
  • (1.22)
    Otherwise, units-suffix is "[num/den]s".
In the list above, the use of num and den refer to the static data members of Period​::​type, which are converted to arrays of charT using a decimal conversion with no leading zeroes.
2
#
Returns: os.
🔗
template<class charT, class traits, class Rep, class Period, class Alloc = allocator<charT>> basic_istream<charT, traits>& from_stream(basic_istream<charT, traits>& is, const charT* fmt, duration<Rep, Period>& d, basic_string<charT, traits, Alloc>* abbrev = nullptr, minutes* offset = nullptr);
3
#
Effects: Attempts to parse the input stream is into the duration d using the format flags given in the NTCTS fmt as specified in [time.parse].
If the parse parses everything specified by the parsing format flags without error, and yet none of the flags impacts a duration, d will be assigned a zero value.
If %Z is used and successfully parsed, that value will be assigned to *abbrev if abbrev is non-null.
If %z (or a modified variant) is used and successfully parsed, that value will be assigned to *offset if offset is non-null.
4
#
Returns: is.