std::chrono::duration

C++

Language

Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

Utilities library

Type support (basic types, RTTI, type traits)
Dynamic memory management
Error handling
Program utilities
Variadic functions
Library feature-test macros
Date and time
Function objects
initializer_list (C++11)
bitset
hash (C++11)
integer_sequence (C++14)
Relational operators (deprecated)
rel_ops::operator!=rel_ops::operator>rel_ops::operator<=rel_ops::operator>=
Comparisons (C++20)
strong_order weak_order partial_order strong_equal weak_equal	strong_ordering weak_ordering partial_ordering strong_equality weak_equality	is_eqis_neqis_ltis_lteqis_gtis_gteq
common_comparison_category
Common vocabulary types
pair tuple (C++11) apply (C++17) make_from_tuple (C++17)	optional (C++17) any (C++17) variant (C++17)
Swap, forward and move
swap
exchange (C++14)
forward (C++11)
move (C++11)
move_if_noexcept (C++11)
Elementary string conversions
to_chars (C++17)
from_chars (C++17)
chars_format (C++17)
Type operations
declval (C++11)
as_const (C++17)

Date and time utilities

duration (C++11) time_point (C++11) time_of_day (C++20)	clock_time_conversion (C++20) clock_cast (C++20)
Clocks
system_clock (C++11) steady_clock (C++11) high_resolution_clock (C++11) is_clock (C++20)	utc_clock (C++20) tai_clock (C++20) gps_clock (C++20) file_clock (C++20) local_t (C++20)
Calendars
day (C++20) month (C++20) year (C++20) weekday (C++20) operator/ (C++20) year_month_day (C++20) year_month_day_last (C++20) year_month_weekday (C++20) year_month_weekday_last (C++20)	weekday_indexed (C++20) weekday_last (C++20) month_day (C++20) month_day_last (C++20) month_weekday (C++20) month_weekday_last (C++20) year_month (C++20)
Time zones
tzdb (C++20) tzdb_list (C++20) get_tzdbget_tzdb_listreload_tzdbremote_version (C++20)(C++20)(C++20)(C++20)	time_zone (C++20) locate_zone (C++20) current_zone (C++20) zoned_time (C++20) link (C++20) leap (C++20)
C-style date and time

std::chrono::duration

Member functions
duration::duration
duration::operator=
duration::count
duration::zero
duration::min
duration::max
duration::operator+duration::operator-
duration::operator++duration::operator--
duration::operator+=duration::operator-=duration::operator*=duration::operator/=duration::operator%=
Non-member functions
operator+operator-operator*operator/operator% operator==operator!=operator<operator<=operator>operator>= operator<< (C++20) to_stream (C++20)	common_type duration_cast floor (C++17) ceil (C++17) round (C++17) abs (C++17) operator""h (C++14) operator""min (C++14) operator""s (C++14) operator""ms (C++14) operator""us (C++14) operator""ns (C++14) from_stream (C++20)
Helper classes
treat_as_floating_point duration_values

Defined in header <chrono>
template< class Rep, class Period = std::ratio<1> > class duration;		(since C++11)

Class template std::chrono::duration represents a time interval.

It consists of a count of ticks of type Rep and a tick period, where the tick period is a compile-time rational constant representing the number of seconds from one tick to the next.

The only data stored in a duration is a tick count of type Rep. If Rep is floating point, then the duration can represent fractions of ticks. Period is included as part of the duration's type, and is only used when converting between different durations.

Member types

Member type	Definition
rep	Rep, an arithmetic type representing the number of ticks
period	Period (until C++17)typename Period::type (since C++17), a std::ratio representing the tick period (i.e. the number of seconds per tick)

Member functions

(constructor)	constructs new duration (public member function)
operator=	assigns the contents (public member function)
count	returns the count of ticks (public member function)
zero [static]	returns the special duration value zero (public static member function)
min [static]	returns the special duration value min (public static member function)
max [static]	returns the special duration value max (public static member function)
operator+operator-	implements unary + and unary - (public member function)
operator++operator++(int)operator--operator--(int)	increments or decrements the tick count (public member function)
operator+=operator-=operator*=operator/=operator%=	implements compound assignment between two durations (public member function)

Non-member functions

std::common_type<std::chrono::duration>	specializes the std::common_type trait (class template specialization)
operator+operator-operator*operator/operator%	implements arithmetic operations with durations as arguments (function template)
operator==operator!=operator<operator<=operator>operator>=	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)
operator<< (C++20)	performs stream output on a duration (function template)
to_stream (C++20)	outputs a duration into a stream according to the provided format (function template)
from_stream (C++20)	parses a duration from a stream according to the provided format (function template)

Helper types

Type	Definition
std::chrono::nanoseconds	duration</*signed integer type of at least 64 bits*/, std::nano>
std::chrono::microseconds	duration</*signed integer type of at least 55 bits*/, std::micro>
std::chrono::milliseconds	duration</*signed integer type of at least 45 bits*/, std::milli>
std::chrono::seconds	duration</*signed integer type of at least 35 bits*/>
std::chrono::minutes	duration</*signed integer type of at least 29 bits*/, std::ratio<60>>
std::chrono::hours	duration</*signed integer type of at least 23 bits*/, std::ratio<3600>>
std::chrono::days (since C++20)	duration</*signed integer type of at least 25 bits*/, std::ratio<86400>>
std::chrono::weeks (since C++20)	duration</*signed integer type of at least 22 bits*/, std::ratio<604800>>
std::chrono::months (since C++20)	duration</*signed integer type of at least 20 bits*/, std::ratio<2629746>>
std::chrono::years (since C++20)	duration</*signed integer type of at least 17 bits*/, std::ratio<31556952>>

Note: each of the predefined duration types up to hours covers a range of at least 292 years.

Each of the predefined duration types days, weeks, months and years covers a range of at least 40000 years. years is equal to 365.2425 days (the average length of a Gregorian year). months is equal to 30.436875 days (exactly 1/12 of years).

(since C++20)

Helper classes

treat_as_floating_point	indicates that a duration is convertible to duration with different tick period (class template)
duration_values	constructs zero, min, and max values of a tick count of given type (class 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)

Note: the literal suffixes d and y do not refer to days and years but to day and year, respectively.

(since C++20)

Example

This example shows how to define several custom duration types and convert between types:

Run this code

#include <iostream>
#include <chrono>

constexpr auto year = 31556952ll; // seconds in average Gregorian year

int main()
{
    using shakes = std::chrono::duration<int, std::ratio<1, 100000000>>;
    using jiffies = std::chrono::duration<int, std::centi>;
    using microfortnights = std::chrono::duration<float, std::ratio<14*24*60*60, 1000000>>;
    using nanocenturies = std::chrono::duration<float, std::ratio<100*year, 1000000000>>;

    std::chrono::seconds sec(1);

    std::cout << "1 second is:\n";

    // integer scale conversion with no precision loss: no cast
    std::cout << std::chrono::microseconds(sec).count() << " microseconds\n"
              << shakes(sec).count() << " shakes\n"
              << jiffies(sec).count() << " jiffies\n";

    // integer scale conversion with precision loss: requires a cast
    std::cout << std::chrono::duration_cast<std::chrono::minutes>(sec).count()
              << " minutes\n";

    // floating-point scale conversion: no cast
    std::cout << microfortnights(sec).count() << " microfortnights\n"
              << nanocenturies(sec).count() << " nanocenturies\n";
}

Output:

1 second is:
1000000 microseconds
100000000 shakes
100 jiffies
0 minutes
0.82672 microfortnights
0.316887 nanocenturies