Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Memory and Utilities

C++ std::chrono::duration class template

Reference for std::chrono::duration: literals like 250ms, implicit and explicit conversions, floor, ceil, round, floating durations and arithmetic rules.

std::chrono::duration<Rep, Period> represents a span of time as a count of ticks. Rep is the arithmetic type of the count (usually long long, or double for fractional values) and Period is a std::ratio giving the length of one tick in seconds. duration<int, std::ratio<60>> is a count of minutes held in an int.

You rarely write the template arguments. The standard aliases nanoseconds, microseconds, milliseconds, seconds, minutes, hours (and days, weeks, months, years since C++20) cover most needs, and the literal suffixes (10s, 250ms) create values directly. The unit is part of the type, so a function taking std::chrono::seconds cannot be called with a bare 5.

C++
using namespace std::chrono;
milliseconds ms = 3s;       // 3000ms, implicit and exact
auto t = 1min + 30s;        // 90s

Try it

C++ Literals, conversions and arithmetic

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++ Splitting a duration and using it in an API

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++
template<class Rep, class Period = std::ratio<1>> class duration;

constexpr Rep count() const;
static constexpr duration zero() noexcept;   // also min(), max()

template<class ToDuration, class Rep, class Period>
constexpr ToDuration duration_cast(const duration<Rep, Period>& d);
// floor<ToDuration>, ceil<ToDuration>, round<ToDuration>: C++17; abs(d): C++17
Name Description
Rep Arithmetic type (or a class that behaves like one) holding the tick count.
Period std::ratio giving seconds per tick.
count() The raw number of ticks.
duration_cast<To>(d) Convert with truncation toward zero.
floor, ceil, round Convert rounding down, up, or to nearest (ties to even).
zero(), min(), max() Special values.

Returns: a duration in the target type; count() returns Rep.

Errors / undefined behavior: integer overflow in the count is undefined behavior for signed Rep. duration_cast between integer types can overflow silently when the result does not fit. Constructing a duration from a floating value to an integer Rep is a compile error.

Usage notes

  • Implicit conversion rule: allowed when no information can be lost, i.e. Rep is floating or the source period is an exact integer multiple of the target. seconds to milliseconds is implicit; milliseconds to seconds is not.
  • Arithmetic between different units yields the finest common unit (1min + 30s is 90s). Multiplication and division by a number keep the unit; dividing two durations gives a plain number.
  • Choose a rounding explicitly. duration_cast truncates toward zero, which surprises for negative values; floor always goes toward negative infinity.
  • count() should stay at the edges. Passing raw counts around brings back the unit-confusion bugs chrono prevents.
  • Fractional seconds are best held in std::chrono::duration<double> (alias it as you like). Use std::chrono::duration<double, std::milli> for fractional milliseconds.
  • Literals need using namespace std::chrono_literals; (also included by using namespace std::chrono;). Fractional literals such as 1.5s produce a duration with a floating-point Rep.
  • months and years (C++20) are average lengths (30.436875 days, 365.2425 days), not calendar units. See calendar and time zones.
  • Comparison operators work across units and, since C++20, <=> is available.
  • Printing: std::cout << 5s and std::format("{}", 5s) print 5s in C++20; before that you printed count() and added the unit yourself.