Skip to content
Tutorials Center
My learning

Topics

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.

C++
using namespace std::chrono;
auto timeout = 1500ms;
seconds whole = duration_cast<seconds>(timeout);   // 1s

Try it

C++ The three building blocks

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.

C++ Printing with std::format (C++20)

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

C++
#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_clock for measuring elapsed time and timeouts (it never goes backwards); use system_clock for 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 with std::format or std::print (C++20), which add unit suffixes.
  • Implicit conversions only go to finer units. seconds to milliseconds is fine; the reverse needs duration_cast, floor, ceil or round (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::months and years are average-length durations (not calendar-aware). For "same day next month" use year_month_day arithmetic with + months{1} and check ok().
  • 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, abs for durations C++17; calendars, time zones, utc_clock and formatting C++20.