23 General utilities library [utilities]

23.17 Time utilities [time]

23.17.1 In general [time.general]

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

23.17.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;
  }

  // [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;
    template <class Rep> inline constexpr bool treat_as_floating_point_v
      = treat_as_floating_point<Rep>::value;

    // [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);
    template <class ToDuration, class Rep, class Period>
      constexpr ToDuration floor(const duration<Rep, Period>& d);
    template <class ToDuration, class Rep, class Period>
      constexpr ToDuration ceil(const duration<Rep, Period>& d);
    template <class ToDuration, class Rep, class Period>
      constexpr ToDuration round(const duration<Rep, Period>& d);

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

    // [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);
    template <class ToDuration, class Clock, class Duration>
      constexpr time_point<Clock, ToDuration>
      floor(const time_point<Clock, Duration>& tp);
    template <class ToDuration, class Clock, class Duration>
      constexpr time_point<Clock, ToDuration>
      ceil(const time_point<Clock, Duration>& tp);
    template <class ToDuration, class Clock, class Duration>
      constexpr time_point<Clock, ToDuration>
      round(const time_point<Clock, Duration>& tp);

    // [time.duration.alg], specialized algorithms
    template <class Rep, class Period>
      constexpr duration<Rep, Period> abs(duration<Rep, Period> d);

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

  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 {
    using namespace literals::chrono_literals;
  }
}

23.17.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 47.
2
#
In Table 47 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 47 — Clock requirements
Expression
Return type
Operational 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:
  • (4.1)
    TC satisfies the Clock requirements ([time.clock.req]),
  • (4.2)
    the types TC​::​rep, TC​::​duration, and TC​::​time_­point satisfy the requirements of EqualityComparable (Table 20), LessThanComparable (Table 21), DefaultConstructible (Table 22), CopyConstructible (Table 24), CopyAssignable (Table 26), Destructible (Table 27), and the requirements of numeric types ([numeric.requirements]).
    [ Note
    :
    This means, in particular, that operations on these types will not throw exceptions.
    — end note
     ]
  • (4.3)
    lvalues of the types TC​::​rep, TC​::​duration, and TC​::​time_­point are swappable ([swappable.requirements]),
  • (4.4)
    the function TC​::​now() does not throw exceptions, and
  • (4.5)
    the type TC​::​time_­point​::​clock meets the TrivialClock requirements, recursively.

23.17.4 Time-related traits [time.traits]

23.17.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_­v<Rep> 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_­v<Rep> is false, Rep will be treated as if it behaved like an integral type for the purpose of these conversions.
— end note
 ]

23.17.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
#
Remarks: The value returned shall be the additive identity.
static constexpr Rep min();
4
#
Returns: numeric_­limits<Rep>​::​lowest().
5
#
Remarks: The value returned shall compare less than or equal to zero().
static constexpr Rep max();
6
#
Returns: numeric_­limits<Rep>​::​max().
7
#
Remarks: The value returned shall compare greater than zero().

23.17.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>> { using type = chrono::duration<common_type_t<Rep1, Rep2>, see below>; };
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>> { using type = chrono::time_point<Clock, common_type_t<Duration1, Duration2>>; };
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.

23.17.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:
  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();
  static constexpr duration min();
  static constexpr duration max();
};
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 shall 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
 ]

23.17.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_­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
#
Effects: Constructs an object of type duration.
3
#
Postconditions: 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_­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
 ]
5
#
Effects: Constructs an object of type duration, constructing rep_­ from
duration_­cast<duration>(d).count().

23.17.5.2 duration observer [time.duration.observer]

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

23.17.5.3 duration 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: As if by ++rep_­.
4
#
Returns: *this.
constexpr duration operator++(int);
5
#
Returns: duration(rep_­++).
constexpr duration& operator--();
6
#
Effects: As if by --rep_­.
7
#
Returns: *this.
constexpr duration operator--(int);
8
#
Returns: duration(rep_­--).
constexpr duration& operator+=(const duration& d);
9
#
Effects: As if by: rep_­ += d.count();
10
#
Returns: *this.
constexpr duration& operator-=(const duration& d);
11
#
Effects: As if by: rep_­ -= d.count();
12
#
Returns: *this.
constexpr duration& operator*=(const rep& rhs);
13
#
Effects: As if by: rep_­ *= rhs;
14
#
Returns: *this.
constexpr duration& operator/=(const rep& rhs);
15
#
Effects: As if by: rep_­ /= rhs;
16
#
Returns: *this.
constexpr duration& operator%=(const rep& rhs);
17
#
Effects: As if by: rep_­ %= rhs;
18
#
Returns: *this.
constexpr duration& operator%=(const duration& rhs);
19
#
Effects: As if by: rep_­ %= rhs.count();
20
#
Returns: *this.

23.17.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()).

23.17.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 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
#
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 a specialization 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()).

23.17.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).

23.17.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 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
#
Remarks: This function shall not participate in overload resolution unless 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
#
Remarks: This function shall not participate in overload resolution unless 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
#
Remarks: This function shall not participate in overload resolution unless 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.

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

23.17.5.9 duration algorithms [time.duration.alg]

template <class Rep, class Period> constexpr duration<Rep, Period> abs(duration<Rep, Period> d);
1
#
Remarks: This function shall not participate in overload resolution unless numeric_­limits<Rep>​::​is_­signed is true.
2
#
Returns: If d >= d.zero(), return d, otherwise return -d.

23.17.6 Class template time_­point [time.point]

template <class Clock, class Duration = typename Clock::duration>
class time_point {
public:
  using clock    = Clock;
  using duration = Duration;
  using rep      = typename duration::rep;
  using period   = typename duration::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
  constexpr time_point& operator+=(const duration& d);
  constexpr 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.req]).
2
#
If Duration is not an instance of duration, the program is ill-formed.

23.17.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().

23.17.6.2 time_­point observer [time.point.observer]

constexpr duration time_since_epoch() const;
1
#
Returns: d_­.

23.17.6.3 time_­point arithmetic [time.point.arithmetic]

constexpr time_point& operator+=(const duration& d);
1
#
Effects: As if by: d_­ += d;
2
#
Returns: *this.
constexpr time_point& operator-=(const duration& d);
3
#
Effects: As if by: d_­ -= d;
4
#
Returns: *this.

23.17.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()).

23.17.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: CT(lhs.time_­since_­epoch() - rhs), where CT is the type of the return value.
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().

23.17.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).

23.17.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 a specialization of duration.
2
#
Returns: 
time_point<Clock, ToDuration>(duration_cast<ToDuration>(t.time_since_epoch()))
template <class ToDuration, class Clock, class Duration> constexpr time_point<Clock, ToDuration> floor(const time_point<Clock, Duration>& tp);
3
#
Remarks: This function shall not participate in overload resolution unless ToDuration is a specialization of duration.
4
#
Returns: time_­point<Clock, ToDuration>(floor<ToDuration>(tp.time_­since_­epoch())).
template <class ToDuration, class Clock, class Duration> constexpr time_point<Clock, ToDuration> ceil(const time_point<Clock, Duration>& tp);
5
#
Remarks: This function shall not participate in overload resolution unless ToDuration is a specialization of duration.
6
#
Returns: time_­point<Clock, ToDuration>(ceil<ToDuration>(tp.time_­since_­epoch())).
template <class ToDuration, class Clock, class Duration> constexpr time_point<Clock, ToDuration> round(const time_point<Clock, Duration>& tp);
7
#
Remarks: This function shall not participate in overload resolution unless ToDuration is a specialization of duration, and treat_­as_­floating_­point_­v<typename ToDuration​::​rep> is false.
8
#
Returns: time_­point<Clock, ToDuration>(round<ToDuration>(tp.time_­since_­epoch())).

23.17.7 Clocks [time.clock]

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

23.17.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:
  using rep        = see below;
  using period     = ratio<unspecified, unspecified>;
  using duration   = chrono::duration<rep, period>;
  using time_point = chrono::time_point<system_clock>;
  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;
};
using system_clock::rep = unspecified;
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.

23.17.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:
  using rep        = unspecified;
  using period     = ratio<unspecified, unspecified>;
  using duration   = chrono::duration<rep, period>;
  using time_point = chrono::time_point<unspecified, duration>;
  static constexpr bool is_steady = true;

  static time_point now() noexcept;
};

23.17.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:
  using rep        = unspecified;
  using period     = ratio<unspecified, unspecified>;
  using duration   = chrono::duration<rep, period>;
  using time_point = chrono::time_point<unspecified, duration>;
  static constexpr bool is_steady = unspecified;

  static time_point now() noexcept;
};

23.17.8 Header <ctime> synopsis [ctime.syn]

#define NULL see [support.types.nullptr]
#define CLOCKS_PER_SEC see below
#define TIME_UTC see below

namespace std {
  using size_t = see [support.types.layout];
  using clock_t = see below;
  using time_t = see below;

  struct timespec;
  struct tm;

  clock_t clock();
  double difftime(time_t time1, time_t time0);
  time_t mktime(struct tm* timeptr);
  time_t time(time_t* timer);
  int timespec_get(timespec* ts, int base);
  char* asctime(const struct tm* timeptr);
  char* ctime(const time_t* timer);
  struct tm* gmtime(const time_t* timer);
  struct tm* localtime(const time_t* timer);
  size_t strftime(char* s, size_t maxsize, const char* format, const struct tm* timeptr);
}
1
#
The contents of the header <ctime> are the same as the C standard library header <time.h>.223
2
#
The functions asctime, ctime, gmtime, and localtime are not required to avoid data races ([res.on.data.races]).
See also: ISO C 7.
27.
223)
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.