C++ Reference ยท Memory and Utilities
The C++ std::chrono library
Overview of the C++ <chrono> library: durations, time points, clocks and C++20 calendars, how they fit together, and the common conversion rules.
<chrono> is the standard time library. It is built from three ideas that work together. A duration is an amount of time with a unit (500ms, 2h). A clock is a source of "now" with a known starting point (system_clock, steady_clock). A time point is a moment: a duration measured since a clock's epoch. Since C++20 the library also contains calendar types (year_month_day, weekday), time zones and formatting.
Because every value carries its unit in its type, the compiler stops you from adding seconds to milliseconds as raw integers, or from subtracting time points of different clocks. Conversions that could lose information must be written explicitly.
using namespace std::chrono; auto timeout = 1500ms; seconds whole = duration_cast<seconds>(timeout); // 1s
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
#include <chrono> namespace std::chrono { template<class Rep, class Period = ratio<1>> class duration; template<class Clock, class Duration = typename Clock::duration> class time_point; class system_clock; class steady_clock; class high_resolution_clock; // C++20 calendar: year, month, day, weekday, year_month_day, sys_days, local_days, zoned_time, ... }
| Component | Description |
|---|---|
duration |
A count of ticks and a period; aliases nanoseconds ... hours, and since C++20 days, weeks, months, years. |
time_point |
A duration since a clock's epoch; aliases sys_time<D>, sys_seconds, sys_days, local_time<D> (C++20). |
| clocks | system_clock (wall clock), steady_clock (monotonic), high_resolution_clock, plus utc_clock, tai_clock, gps_clock, file_clock (C++20). |
| calendar and time zones | year, month, day, weekday, year_month_day, time_zone, zoned_time, hh_mm_ss (C++20). |
| Literals | h, min, s, ms, us, ns (C++14); d and y (C++20). |
Returns: the types are value types; now() returns a time point and count() returns the raw number.
Errors / undefined behavior: invalid calendar values do not throw; ok() tells you whether a date exists. Overflow of a duration count follows the rules of its integer type (signed overflow is undefined behavior).
Usage notes
- Pick the right clock. Use
steady_clockfor measuring elapsed time and timeouts (it never goes backwards); usesystem_clockfor calendar time that may be shown to humans or stored. - Do not print
count()unless you must. Keep values as chrono types and format them withstd::formatorstd::print(C++20), which add unit suffixes. - Implicit conversions only go to finer units.
secondstomillisecondsis fine; the reverse needsduration_cast,floor,ceilorround(the last three since C++17). - Integer vs floating durations.
std::chrono::duration<double>represents fractional seconds and converts implicitly from any integer duration. std::chrono::monthsandyearsare average-length durations (not calendar-aware). For "same day next month" useyear_month_dayarithmetic with+ months{1}and checkok().- Time zones (
std::chrono::zoned_time,current_zone()) need the IANA time-zone database at run time. They work on typical desktop and server systems; a minimal container without tzdata cannot resolve zone names, see calendar and time zones. - Waiting APIs (
std::this_thread::sleep_for,condition_variable::wait_for,future::wait_until) all accept chrono durations and time points. - Compile time:
<chrono>with<format>or<print>costs noticeable compile time; it is the price of type safety. - Version notes: durations, clocks and time points are C++11; literals C++14;
floor,ceil,round,absfor durations C++17; calendars, time zones,utc_clockand formatting C++20.