Standard library header <chrono>

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Technical Specifications

 

Standard Library headers

Language Support
<cstddef> <cstdlib> <version> <limits> <climits>	<cfloat> <cstdint> <new> <typeinfo>	<source_location> <exception> <initializer_list> <compare>	<coroutine> <csignal> <csetjmp> <cstdarg>
Concepts
<concepts>
Diagnostics
<stdexcept>	<cassert>	<cerrno>	<system_error>
General utilities
<utility> <memory> <memory_resource> <scoped_allocator>	<bitset> <tuple> <optional> <any>	<variant> <type_traits> <ratio> <chrono>	<typeindex> <functional> <ctime>
Strings
<string> <string_view> <cstring>	<charconv> <format>	<cctype> <cwctype>	<cwchar> <cuchar>
Localization
<locale>	<codecvt>	<clocale>
Containers
<span> <array> <vector>	<deque> <forward_list> <list>	<map> <set> <queue>	<unordered_map> <unordered_set> <stack>
Iterators
<iterator>
Ranges
<ranges>
Algorithms
<algorithm>	<execution>
Numerics
<complex> <random>	<valarray> <numeric>	<bit> <numbers>	<cfenv> <cmath>
Input/Output
<iosfwd> <ios> <iomanip> <streambuf>	<istream> <ostream> <iostream>	<sstream> <fstream> <syncstream>	<cstdio> <cinttypes> <strstream>
Regular expressions
<regex>
Filesystem support
<filesystem>
Thread support
<thread> <atomic> <mutex>	<shared_mutex> <condition_variable> <future>	<stop_token> <semaphore>	<latch> <barrier>
C compatibility
<ciso646> <cstdalign>	<cstdbool> <ccomplex>	<ctgmath>

 

This header is part of the date and time library.

Classes

Defined in namespace std::chrono
duration (C++11)	a time interval (class template)
time_point (C++11)	a point in time (class template)
treat_as_floating_point	indicates that a duration is convertible to duration with different tick period (class template)
clock_time_conversion (C++20)	traits class defining how to convert time points of one clock to another (class template)
duration_values	constructs zero, min, and max values of a tick count of given type (class template)
time_zone (C++20)	represents a time zone (class)
nonexistent_local_time (C++20)	exception thrown to report that a local time is nonexistent (class)
ambiguous_local_time (C++20)	exception thrown to report that a local time is ambiguous (class)
Clocks
Defined in namespace std::chrono
system_clock (C++11)	wall clock time from the system-wide realtime clock (class)
steady_clock (C++11)	monotonic clock that will never be adjusted (class)
high_resolution_clock (C++11)	the clock with the shortest tick period available (class)
utc_clock (C++20)	Clock for Coordinated Universal Time (UTC) (class)
tai_clock (C++20)	Clock for International Atomic Time (TAI) (class)
gps_clock (C++20)	Clock for GPS time (class)
file_clock (C++20)	Clock used for file time (typedef)
local_t (C++20)	pseudo-clock representing local time (class)
Convenience Typedefs
Defined in namespace std::chrono
std::chrono::nanoseconds	duration type with Period std::nano
std::chrono::microseconds	duration type with Period std::micro
std::chrono::milliseconds	duration type with Period std::milli
std::chrono::seconds	duration type with Period std::ratio<1>
std::chrono::minutes	duration type with Period std::ratio<60>
std::chrono::hours	duration type with Period std::ratio<3600>
std::chrono::days	duration type with Period std::ratio<86400>
std::chrono::weeks	duration type with Period std::ratio<604800>
std::chrono::months	duration type with Period std::ratio<2629746>
std::chrono::years	duration type with Period std::ratio<31556952>
Specializations
Defined in namespace std
std::common_type<std::chrono::duration>	specializes the std::common_type trait (class template specialization)
std::common_type<std::chrono::time_point>	specializes the std::common_type trait (class template specialization)

Functions

Duration
Defined in namespace std::chrono
operator+operator-operator*operator/operator%	implements arithmetic operations with durations as arguments (function template)
operator==operator!=operator<operator<=operator>operator>=operator<=> (removed in C++20)(C++20)	compares two durations (function template)
duration_cast	converts a duration to another, with a different tick interval (function template)
floor(std::chrono::duration) (C++17)	converts a duration to another, rounding down (function template)
ceil(std::chrono::duration) (C++17)	converts a duration to another, rounding up (function template)
round(std::chrono::duration) (C++17)	converts a duration to another, rounding to nearest, ties to even (function template)
abs(std::chrono::duration) (C++17)	obtains the absolute value of the duration (function template)
Time point
Defined in namespace std::chrono
operator+operator-	performs add and subtract operations involving a time point (function template)
operator==operator!=operator<operator<=operator>operator>=operator<=> (removed in C++20)(C++20)	compares two time points (function template)
time_point_cast	converts a time point to another time point on the same clock, with a different duration (function template)
floor(std::chrono::time_point) (C++17)	converts a time_point to another, rounding down (function template)
ceil(std::chrono::time_point) (C++17)	converts a time_point to another, rounding up (function template)
round(std::chrono::time_point) (C++17)	converts a time_point to another, rounding to nearest, ties to even (function template)
clock_cast (C++20)	convert time points of one clock to another (function template)
Literals
Defined in inline namespace std::literals::chrono_literals
operator""h (C++14)	A std::chrono::duration literal representing hours (function)
operator""min (C++14)	A std::chrono::duration literal representing minutes (function)
operator""s (C++14)	A std::chrono::duration literal representing seconds (function)
operator""ms (C++14)	A std::chrono::duration literal representing milliseconds (function)
operator""us (C++14)	A std::chrono::duration literal representing microseconds (function)
operator""ns (C++14)	A std::chrono::duration literal representing nanoseconds (function)
operator""d (C++20)	A std::chrono::day literal representing a day of a month (function)
operator""y (C++20)	A std::chrono::year literal representing a particular year (function)

Synopsis

namespace std {
  namespace chrono {
    // class template duration
    template <class Rep, class Period = ratio<1>> class duration;
    // class template time_point
    template <class Clock, class Duration = typename Clock::duration> class time_point;
  }
  // 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 {
    // customization traits
    template <class Rep> struct treat_as_floating_point;
    template <class Rep> struct duration_values;
    template <class Rep>
    constexpr bool treat_as_floating_point_v = treat_as_floating_point<Rep>::value;
    // 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);
    // 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);
    // 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 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
    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
    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);
    // specialized algorithms
    template <class Rep, class Period>
    constexpr duration<Rep, Period> abs(duration<Rep, Period> d);
    // clocks
    class system_clock;
    class steady_clock;
    class high_resolution_clock;
  }
  inline namespace literals {
    inline namespace chrono_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);
      constexpr chrono::day  operator""d(unsigned long long d) noexcept;
      constexpr chrono::year operator""y(unsigned long long y) noexcept;
    }
  }
  namespace chrono {
    using namespace literals::chrono_literals;
  }

std::chrono::treat_as_floating_point

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

std::chrono::duration_values

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

std::chrono::duration

template <class Rep, class Period = ratio<1>>
class duration {
public:
  using rep = Rep;
  using period = Period;
private:
  rep rep_; // exposition only
public:
  // 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;
  // observer
  constexpr rep count() const;
  // arithmetic
  constexpr duration operator+() const;
  constexpr 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);
  // special values
  static constexpr duration zero();
  static constexpr duration min();
  static constexpr duration max();
};

std::chrono::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:
  // 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);
  // observer
  constexpr duration time_since_epoch() const;
  // arithmetic
  constexpr time_point& operator+=(const duration& d);
  constexpr time_point& operator-=(const duration& d);
  // special values
  static constexpr time_point min();
  static constexpr time_point max();
};

std::chrono::system_clock

class system_clock {
public:
  using rep = /*see description*/ ;
  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;
};

std::chrono::steady_clock

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

std::chrono::high_resolution_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;
};