20 General utilities library [utilities]

20.12 Time utilities [time]

20.12.1 In general [time.general]

1

This subclause describes the chrono library ([time.syn]) and various C functions ([date.time]) that provide generally useful time utilities.

20.12.2 Header <chrono> synopsis [time.syn]

namespace std {
namespace chrono {

// [time.duration], class template duration
template <class Rep, class Period = ratio<1> > class duration;

// [time.point], class template time_point
template <class Clock, class Duration = typename Clock::duration> class time_point;

}  // namespace chrono

// [time.traits.specializations] common_type specializations
template <class Rep1, class Period1, class Rep2, class Period2>
  struct common_type<chrono::duration<Rep1, Period1>, chrono::duration<Rep2, Period2>>;

template <class Clock, class Duration1, class Duration2>
  struct common_type<chrono::time_point<Clock, Duration1>, chrono::time_point<Clock, Duration2>>;

namespace chrono {

// [time.traits], customization traits
template <class Rep> struct treat_as_floating_point;
template <class Rep> struct duration_values;

// [time.duration.nonmember], duration arithmetic
template <class Rep1, class Period1, class Rep2, class Period2>
  common_type_t<duration<Rep1, Period1>, duration<Rep2, Period2>>
  constexpr operator+(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);
template <class Rep1, class Period1, class Rep2, class Period2>
  common_type_t<duration<Rep1, Period1>, duration<Rep2, Period2>>
  constexpr operator-(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);
template <class Rep1, class Period, class Rep2>
  duration<common_type_t<Rep1, Rep2>, Period>
  constexpr operator*(const duration<Rep1, Period>& d, const Rep2& s);
template <class Rep1, class Rep2, class Period>
  duration<common_type_t<Rep1, Rep2>, Period>
  constexpr operator*(const Rep1& s, const duration<Rep2, Period>& d);
template <class Rep1, class Period, class Rep2>
  duration<common_type_t<Rep1, Rep2>, Period>
  constexpr operator/(const duration<Rep1, Period>& d, const Rep2& s);
template <class Rep1, class Period1, class Rep2, class Period2>
  common_type_t<Rep1, Rep2>
  constexpr operator/(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);
template <class Rep1, class Period, class Rep2>
  duration<common_type_t<Rep1, Rep2>, Period>
  constexpr operator%(const duration<Rep1, Period>& d, const Rep2& s);
template <class Rep1, class Period1, class Rep2, class Period2>
  common_type_t<duration<Rep1, Period1>, duration<Rep2, Period2>>
  constexpr operator%(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);

// [time.duration.comparisons], duration comparisons
template <class Rep1, class Period1, class Rep2, class Period2>
  constexpr bool operator==(const duration<Rep1, Period1>& lhs,
                            const duration<Rep2, Period2>& rhs);
template <class Rep1, class Period1, class Rep2, class Period2>
  constexpr bool operator!=(const duration<Rep1, Period1>& lhs,
                            const duration<Rep2, Period2>& rhs);
template <class Rep1, class Period1, class Rep2, class Period2>
  constexpr bool operator< (const duration<Rep1, Period1>& lhs,
                            const duration<Rep2, Period2>& rhs);
template <class Rep1, class Period1, class Rep2, class Period2>
  constexpr bool operator<=(const duration<Rep1, Period1>& lhs,
                            const duration<Rep2, Period2>& rhs);
template <class Rep1, class Period1, class Rep2, class Period2>
  constexpr bool operator> (const duration<Rep1, Period1>& lhs,
                            const duration<Rep2, Period2>& rhs);
template <class Rep1, class Period1, class Rep2, class Period2>
  constexpr bool operator>=(const duration<Rep1, Period1>& lhs,
                            const duration<Rep2, Period2>& rhs);

// [time.duration.cast], duration_cast
template <class ToDuration, class Rep, class Period>
  constexpr ToDuration duration_cast(const duration<Rep, Period>& d);

// convenience typedefs
typedef duration<signed integer type of at least 64 bits,        nano> nanoseconds;
typedef duration<signed integer type of at least 55 bits,       micro> microseconds;
typedef duration<signed integer type of at least 45 bits,       milli> milliseconds;
typedef duration<signed integer type of at least 35 bits             > seconds;
typedef duration<signed integer type of at least 29 bits, ratio<  60>> minutes;
typedef duration<signed integer type of at least 23 bits, ratio<3600>> hours;

// [time.point.nonmember], time_point arithmetic
template <class Clock, class Duration1, class Rep2, class Period2>
  constexpr time_point<Clock, common_type_t<Duration1, duration<Rep2, Period2>>>
  operator+(const time_point<Clock, Duration1>& lhs, const duration<Rep2, Period2>& rhs);
template <class Rep1, class Period1, class Clock, class Duration2>
  constexpr time_point<Clock, common_type_t<duration<Rep1, Period1>, Duration2>>
  operator+(const duration<Rep1, Period1>& lhs, const time_point<Clock, Duration2>& rhs);
template <class Clock, class Duration1, class Rep2, class Period2>
  constexpr time_point<Clock, common_type_t<Duration1, duration<Rep2, Period2>>>
  operator-(const time_point<Clock, Duration1>& lhs, const duration<Rep2, Period2>& rhs);
template <class Clock, class Duration1, class Duration2>
  constexpr common_type_t<Duration1, Duration2>
  operator-(const time_point<Clock, Duration1>& lhs, const time_point<Clock, Duration2>& rhs);

// [time.point.comparisons] time_point comparisons
template <class Clock, class Duration1, class Duration2>
   constexpr bool operator==(const time_point<Clock, Duration1>& lhs,
                             const time_point<Clock, Duration2>& rhs);
template <class Clock, class Duration1, class Duration2>
   constexpr bool operator!=(const time_point<Clock, Duration1>& lhs,
                             const time_point<Clock, Duration2>& rhs);
template <class Clock, class Duration1, class Duration2>
   constexpr bool operator< (const time_point<Clock, Duration1>& lhs,
                             const time_point<Clock, Duration2>& rhs);
template <class Clock, class Duration1, class Duration2>
   constexpr bool operator<=(const time_point<Clock, Duration1>& lhs,
                             const time_point<Clock, Duration2>& rhs);
template <class Clock, class Duration1, class Duration2>
   constexpr bool operator> (const time_point<Clock, Duration1>& lhs,
                             const time_point<Clock, Duration2>& rhs);
template <class Clock, class Duration1, class Duration2>
   constexpr bool operator>=(const time_point<Clock, Duration1>& lhs,
                             const time_point<Clock, Duration2>& rhs);

// [time.point.cast], time_point_cast
template <class ToDuration, class Clock, class Duration>
  constexpr time_point<Clock, ToDuration>
  time_point_cast(const time_point<Clock, Duration>& t);

// [time.clock], clocks
class system_clock;
class steady_clock;
class high_resolution_clock;

}  // namespace chrono

inline namespace literals {
inline namespace chrono_literals {

//  [time.duration.literals], suffixes for duration literals
constexpr chrono::hours                                 operator "" h(unsigned long long);
constexpr chrono::duration<unspecified, ratio<3600,1>> operator "" h(long double);
constexpr chrono::minutes                               operator "" min(unsigned long long);
constexpr chrono::duration<unspecified, ratio<60,1>>   operator "" min(long double);
constexpr chrono::seconds                               operator "" s(unsigned long long);
constexpr chrono::duration<unspecified>                operator "" s(long double);
constexpr chrono::milliseconds                          operator "" ms(unsigned long long);
constexpr chrono::duration<unspecified, milli>         operator "" ms(long double);
constexpr chrono::microseconds                          operator "" us(unsigned long long);
constexpr chrono::duration<unspecified, micro>         operator "" us(long double);
constexpr chrono::nanoseconds                           operator "" ns(unsigned long long);
constexpr chrono::duration<unspecified, nano>          operator "" ns(long double);

}  // namespace chrono_literals
}  // namespace literals

namespace chrono {

using namespace literals::chrono_literals;

} // namespace chrono

}  // namespace std

20.12.3 Clock requirements [time.clock.req]

1

A clock is a bundle consisting of a duration, a time_point, and a function now() to get the current time_point. The origin of the clock's time_point is referred to as the clock's epoch. A clock shall meet the requirements in Table [tab:time.clock].

2

In Table [tab:time.clock] C1 and C2 denote clock types. t1 and t2 are values returned by C1::now() where the call returning t1 happens before ([intro.multithread]) the call returning t2 and both of these calls occur before C1::time_point::max(). [ Note: this means C1 did not wrap around between t1 and t2.  — end note ]

Table 59 — Clock requirements
ExpressionReturn typeOperational semantics
C1::rep An arithmetic type or a class emulating an arithmetic type The representation type of C1::duration.
C1::period a specialization of ratio The tick period of the clock in seconds.
C1::duration chrono::duration<C1::rep, C1::period> The duration type of the clock.
C1::time_point chrono::time_point<C1> or chrono::time_point<C2, C1::duration> The time_point type of the clock. C1 and C2 shall refer to the same epoch.
C1::is_steady const bool true if t1 <= t2 is always true and the time between clock ticks is constant, otherwise false.
C1::now() C1::time_point Returns a time_point object representing the current point in time.
3

[ Note: The relative difference in durations between those reported by a given clock and the SI definition is a measure of the quality of implementation.  — end note ]

4

A type TC meets the TrivialClock requirements if:

20.12.4 Time-related traits [time.traits]

20.12.4.1 treat_as_floating_point [time.traits.is_fp]

template <class Rep> struct treat_as_floating_point : is_floating_point<Rep> { };

1

The duration template uses the treat_as_floating_point trait to help determine if a duration object can be converted to another duration with a different tick period. If treat_as_floating_point<Rep>::value is true, then implicit conversions are allowed among durations. Otherwise, the implicit convertibility depends on the tick periods of the durations. [ Note: The intention of this trait is to indicate whether a given class behaves like a floating-point type, and thus allows division of one value by another with acceptable loss of precision. If treat_as_floating_point<Rep>::value is false, Rep will be treated as if it behaved like an integral type for the purpose of these conversions.  — end note ]

20.12.4.2 duration_values [time.traits.duration_values]

template <class Rep> struct duration_values { public: static constexpr Rep zero(); static constexpr Rep min(); static constexpr Rep max(); };

1

The duration template uses the duration_values trait to construct special values of the durations representation (Rep). This is done because the representation might be a class type with behavior which requires some other implementation to return these special values. In that case, the author of that class type should specialize duration_values to return the indicated values.

static constexpr Rep zero();

2

Returns: Rep(0). [ Note: Rep(0) is specified instead of Rep() because Rep() may have some other meaning, such as an uninitialized value.  — end note ]

3

Remark: The value returned shall be the additive identity.

static constexpr Rep min();

4

Returns: numeric_limits<Rep>::lowest().

5

Remark: The value returned shall compare less than or equal to zero().

static constexpr Rep max();

6

Returns: numeric_limits<Rep>::max().

7

Remark: The value returned shall compare greater than zero().

20.12.4.3 Specializations of common_type [time.traits.specializations]

template <class Rep1, class Period1, class Rep2, class Period2> struct common_type<chrono::duration<Rep1, Period1>, chrono::duration<Rep2, Period2>> { typedef chrono::duration<common_type_t<Rep1, Rep2>, see below> type; };

1

The period of the duration indicated by this specialization of common_type shall be the greatest common divisor of Period1 and Period2. [ Note: This can be computed by forming a ratio of the greatest common divisor of Period1::num and Period2::num and the least common multiple of Period1::den and Period2::den.  — end note ]

2

[ Note: The typedef name type is a synonym for the duration with the largest tick period possible where both duration arguments will convert to it without requiring a division operation. The representation of this type is intended to be able to hold any value resulting from this conversion with no truncation error, although floating-point durations may have round-off errors.  — end note ]

template <class Clock, class Duration1, class Duration2> struct common_type<chrono::time_point<Clock, Duration1>, chrono::time_point<Clock, Duration2>> { typedef chrono::time_point<Clock, common_type_t<Duration1, Duration2>> type; };

3

The common type of two time_point types is a time_point with the same clock as the two types and the common type of their two durations.

20.12.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.

7

Remarks: 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.

[ 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.12.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 no overflow is induced in the conversion and 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.12.5.2 duration observer [time.duration.observer]

constexpr rep count() const;

1

Returns: rep_.

20.12.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.12.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.12.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_t<A, B>.

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

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<common_type_t<Rep1, Rep2>, 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<common_type_t<Rep1, Rep2>, 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 common_type_t<Rep1, Rep2> 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<common_type_t<Rep1, Rep2>, 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 common_type_t<duration<Rep1, Period1>, duration<Rep2, Period2>> operator%(const duration<Rep1, Period1>& lhs, const duration<Rep2, Period2>& rhs);

13

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

20.12.5.6 duration 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: !(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.12.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.

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

1

This section 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 integral 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.

20.12.6 Class template time_point [time.point]

template <class Clock, class Duration = typename Clock::duration>
class time_point {
public:
  typedef Clock                     clock;
  typedef Duration                  duration;
  typedef typename duration::rep    rep;
  typedef typename duration::period period;
private:
  duration d_;  // exposition only

public:
  // [time.point.cons], construct:
  constexpr time_point();  // has value epoch
  constexpr explicit time_point(const duration& d);  // same as time_point() + d
  template <class Duration2>
    constexpr time_point(const time_point<clock, Duration2>& t);

  // [time.point.observer], observer:
  constexpr duration time_since_epoch() const;

  // [time.point.arithmetic], arithmetic:
  time_point& operator+=(const duration& d);
  time_point& operator-=(const duration& d);

  // [time.point.special], special values:
  static constexpr time_point min();
  static constexpr time_point max();
};
1

Clock shall meet the Clock requirements ([time.clock]).

2

If Duration is not an instance of duration, the program is ill-formed.

20.12.6.1 time_point constructors [time.point.cons]

constexpr time_point();

1

Effects: Constructs an object of type time_point, initializing d_ with duration::zero(). Such a time_point object represents the epoch.

constexpr explicit time_point(const duration& d);

2

Effects: Constructs an object of type time_point, initializing d_ with d. Such a time_point object represents the epoch + d.

template <class Duration2> constexpr time_point(const time_point<clock, Duration2>& t);

3

Remarks: This constructor shall not participate in overload resolution unless Duration2 is implicitly convertible to duration.

4

Effects: Constructs an object of type time_point, initializing d_ with t.time_since_epoch().

20.12.6.2 time_point observer [time.point.observer]

constexpr duration time_since_epoch() const;

1

Returns: d_.

20.12.6.3 time_point arithmetic [time.point.arithmetic]

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

1

Effects: d_ += d.

2

Returns: *this.

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

3

Effects: d_ -= d.

4

Returns: *this.

20.12.6.4 time_point special values [time.point.special]

static constexpr time_point min();

1

Returns: time_point(duration::min()).

static constexpr time_point max();

2

Returns: time_point(duration::max()).

20.12.6.5 time_point non-member arithmetic [time.point.nonmember]

template <class Clock, class Duration1, class Rep2, class Period2> constexpr time_point<Clock, common_type_t<Duration1, duration<Rep2, Period2>>> operator+(const time_point<Clock, Duration1>& lhs, const duration<Rep2, Period2>& rhs);

1

Returns: CT(lhs.time_since_epoch() + rhs), where CT is the type of the return value.

template <class Rep1, class Period1, class Clock, class Duration2> constexpr time_point<Clock, common_type_t<duration<Rep1, Period1>, Duration2>> operator+(const duration<Rep1, Period1>& lhs, const time_point<Clock, Duration2>& rhs);

2

Returns: rhs + lhs.

template <class Clock, class Duration1, class Rep2, class Period2> constexpr time_point<Clock, common_type_t<Duration1, duration<Rep2, Period2>>> operator-(const time_point<Clock, Duration1>& lhs, const duration<Rep2, Period2>& rhs);

3

Returns: lhs + (-rhs).

template <class Clock, class Duration1, class Duration2> constexpr common_type_t<Duration1, Duration2> operator-(const time_point<Clock, Duration1>& lhs, const time_point<Clock, Duration2>& rhs);

4

Returns: lhs.time_since_epoch() - rhs.time_since_epoch().

20.12.6.6 time_point comparisons [time.point.comparisons]

template <class Clock, class Duration1, class Duration2> constexpr bool operator==(const time_point<Clock, Duration1>& lhs, const time_point<Clock, Duration2>& rhs);

1

Returns: lhs.time_since_epoch() == rhs.time_since_epoch().

template <class Clock, class Duration1, class Duration2> constexpr bool operator!=(const time_point<Clock, Duration1>& lhs, const time_point<Clock, Duration2>& rhs);

2

Returns: !(lhs == rhs).

template <class Clock, class Duration1, class Duration2> constexpr bool operator<(const time_point<Clock, Duration1>& lhs, const time_point<Clock, Duration2>& rhs);

3

Returns: lhs.time_since_epoch() < rhs.time_since_epoch().

template <class Clock, class Duration1, class Duration2> constexpr bool operator<=(const time_point<Clock, Duration1>& lhs, const time_point<Clock, Duration2>& rhs);

4

Returns: !(rhs < lhs).

template <class Clock, class Duration1, class Duration2> constexpr bool operator>(const time_point<Clock, Duration1>& lhs, const time_point<Clock, Duration2>& rhs);

5

Returns: rhs < lhs.

template <class Clock, class Duration1, class Duration2> constexpr bool operator>=(const time_point<Clock, Duration1>& lhs, const time_point<Clock, Duration2>& rhs);

6

Returns: !(lhs < rhs).

20.12.6.7 time_point_cast [time.point.cast]

template <class ToDuration, class Clock, class Duration> constexpr time_point<Clock, ToDuration> time_point_cast(const time_point<Clock, Duration>& t);

1

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

2

Returns: time_point<Clock, ToDuration>(duration_cast<ToDuration>(t.time_since_epoch())).

20.12.7 Clocks [time.clock]

1

The types defined in this subclause shall satisfy the TrivialClock requirements ([time.clock.req]).

20.12.7.1 Class system_clock [time.clock.system]

1

Objects of class system_clock represent wall clock time from the system-wide realtime clock.

class system_clock {
public:
  typedef see below                           rep;
  typedef ratio<unspecified, unspecified>   period;
  typedef chrono::duration<rep, period>       duration;
  typedef chrono::time_point<system_clock>    time_point;
  static constexpr bool is_steady =        unspecified;

  static time_point now() noexcept;

  // Map to C API
  static time_t      to_time_t  (const time_point& t) noexcept;
  static time_point  from_time_t(time_t t) noexcept;
};

typedef unspecified system_clock::rep;

2

Requires: system_clock::duration::min() < system_clock::duration::zero() shall be true. [ Note: This implies that rep is a signed type.  — end note ]

static time_t to_time_t(const time_point& t) noexcept;

3

Returns: A time_t object that represents the same point in time as t when both values are restricted to the coarser of the precisions of time_t and time_point. It is implementation defined whether values are rounded or truncated to the required precision.

static time_point from_time_t(time_t t) noexcept;

4

Returns: A time_point object that represents the same point in time as t when both values are restricted to the coarser of the precisions of time_t and time_point. It is implementation defined whether values are rounded or truncated to the required precision.

20.12.7.2 Class steady_clock [time.clock.steady]

1

Objects of class steady_clock represent clocks for which values of time_point never decrease as physical time advances and for which values of time_point advance at a steady rate relative to real time. That is, the clock may not be adjusted.

class steady_clock {
public:
  typedef unspecified                               rep;
  typedef ratio<unspecified, unspecified>          period;
  typedef chrono::duration<rep, period>              duration;
  typedef chrono::time_point<unspecified, duration>  time_point;
  static constexpr bool is_steady =               true;

  static time_point now() noexcept;
};

20.12.7.3 Class high_resolution_clock [time.clock.hires]

1

Objects of class high_resolution_clock represent clocks with the shortest tick period. high_resolution_clock may be a synonym for system_clock or steady_clock.

class high_resolution_clock {
public:
  typedef unspecified                               rep;
  typedef ratio<unspecified, unspecified>          period;
  typedef chrono::duration<rep, period>              duration;
  typedef chrono::time_point<unspecified, duration> time_point;
  static constexpr bool is_steady =               unspecified;

  static time_point now() noexcept;
};

20.12.8 Date and time functions [date.time]

1

Table [tab:util.hdr.ctime] describes the header <ctime>.

Table 60 — Header <ctime> synopsis
TypeName(s)
Macros: NULL CLOCKS_PER_SEC
Types: size_t clock_t time_t
Struct: tm
Functions:
asctime clock difftime localtime strftime
ctime gmtime mktime time
2

The contents are the same as the Standard C library header <time.h>.232 The functions asctime, ctime, gmtime, and localtime are not required to avoid data races ([res.on.data.races]).

See also: ISO C Clause 7.12, Amendment 1 Clause 4.6.4.

231)

strftime supports the C conversion specifiers C, D, e, F, g, G, h, r, R, t, T, u, V, and z, and the modifiers E and O.