std::chrono::duration

From cppreference.com
< cpp‎ | chrono
C++
Date and time library
Time point
(C++11)
(C++20)
Duration
duration
(C++11)
Clocks
(C++11)
(C++11)
(C++20)
(C++20)
(C++20)
(C++11)
(C++20)
(C++20)
(C++20)
Time of day
(C++20)(C++20)
(C++20)(C++20)
(C++20)

Calendar
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)(C++20)
Time zone
(C++20)
(C++20)
(C++20) (C++20) (C++20) (C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
chrono I/O
(C++20)
C-style date and time
std::chrono::duration
Member functions
Non-member functions
(C++17)
(C++17)
(C++17)
(C++17)
(C++14)
(C++14)
(C++14)
(C++14)
(C++14)
(C++14)
(C++20)

Helper classes
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 fraction

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

Member types

Member type Definition
rep Rep, an arithmetic type, or a class emulating an arithmetic type, representing the number of ticks
period Period(until C++17) typename Period::type (since C++17) , a std::ratio

Member functions

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

Non-member functions

(C++11)
 implements arithmetic operations with durations as arguments
(function template)
(C++11) (C++11)(removed in C++20) (C++11) (C++11) (C++11) (C++11) (C++20)
compares two durations
(function template)
(C++11)
 converts a duration to another, with a different tick interval
(function template)
(C++17)
 converts a duration to another, rounding down
(function template)
(C++17)
 converts a duration to another, rounding up
(function template)
(C++17)
 converts a duration to another, rounding to nearest, ties to even
(function template)
(C++17)
 obtains the absolute value of the duration
(function template)
(C++20)
 performs stream output on a duration
(function template)
(C++20)
 parses a duration from a stream according to the provided format
(function template)

Helper types

A type /* intXX */ used in the table below means a signed integer type of at least XX bits.

Type Definition
std::chrono::nanoseconds std:: chrono :: duration < /* int64 */, std::nano >
std::chrono::microseconds std:: chrono :: duration < /* int55 */, std::micro >
std::chrono::milliseconds std:: chrono :: duration < /* int45 */, std::milli >
std::chrono::seconds std:: chrono :: duration < /* int35 */ >
std::chrono::minutes std:: chrono :: duration < /* int29 */, std::ratio < 60 >>
std::chrono::hours std:: chrono :: duration < /* int23 */, std::ratio < 3600 >>
std::chrono::days (since C++20) std:: chrono :: duration < /* int25 */, std::ratio < 86400 >>
std::chrono::weeks (since C++20) std:: chrono :: duration < /* int22 */, std::ratio < 604800 >>
std::chrono::months (since C++20) std:: chrono :: duration < /* int20 */, std::ratio < 2629746 >>
std::chrono::years (since C++20) std:: chrono :: duration < /* int17 */, 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

(C++11)
 specializes the std::common_type trait
(class template specialization)
(C++11)
 indicates that a duration is convertible to duration with different tick period
(class template)
(C++11)
 constructs zero, min, and max values of a tick count of given type
(class template)
(C++20)
 formatting support for duration
(class template specialization)
(C++26)
 hash support for std::chrono::duration
(class template specialization)

Helper specializations

template < class Rep, class Period >

constexpr bool enable_nonlocking_formatter_optimization<chrono:: duration <Rep, Period>>

= enable_nonlocking_formatter_optimization<Rep> ;
(since C++23)

This specialization of std::enable_nonlocking_formatter_optimization enables efficient implementation of std::print and std::println for printing a chrono::duration object when the template parameter Rep

Literals

Defined in inline namespace std::literals::chrono_literals
(C++14)
 a std::chrono::duration literal representing hours
(function)
(C++14)
 a std::chrono::duration literal representing minutes
(function)
(C++14)
 a std::chrono::duration literal representing seconds
(function)
(C++14)
 a std::chrono::duration literal representing milliseconds
(function)
(C++14)
 a std::chrono::duration literal representing microseconds
(function)
(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

(since C++20)

Notes

The actual time interval (in seconds) that is held by a duration object d is roughly equal to d.count ( ) * D:: period :: num / D:: period :: den , where D is of type chrono::duration<> and d

Feature-test macro Value Std Feature
__cpp_lib_chrono_udls 201304L (C++14) User-defined literals for time types

Example

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

Run this code
#include <chrono>
#include <iostream>
 
using namespace std::chrono_literals;
 
template<typename T1, typename T2>
using mul = std::ratio_multiply<T1, T2>;
 
int main()
{
    using microfortnights = std::chrono::duration<float,
        mul<mul<std::ratio<2>, std::chrono::weeks::period>, std::micro>>;
    using nanocenturies = std::chrono::duration<float,
        mul<mul<std::hecto, std::chrono::years::period>, std::nano>>;
    using fps_24 = std::chrono::duration<double, std::ratio<1, 24>>;
 
    std::cout << "1 second is:\n";
 
    // integer scale conversion with no precision loss: no cast
    std::cout << std::chrono::milliseconds(1s).count() << " milliseconds\n"
              << std::chrono::microseconds(1s).count() << " microseconds\n"
              << std::chrono::nanoseconds(1s).count() << " nanoseconds\n";
 
    // integer scale conversion with precision loss: requires a cast
    std::cout << std::chrono::duration_cast<std::chrono::minutes>(1s).count()
              << " minutes\n";
    // alternative to duration_cast:
    std::cout << 1s / 1min << " minutes\n";
 
    // floating-point scale conversion: no cast
    std::cout << microfortnights(1s).count() << " microfortnights\n"
              << nanocenturies(1s).count() << " nanocenturies\n"
              << fps_24(1s).count() << " frames at 24fps\n";
}

Output: 

1 second is:
1000 milliseconds
1000000 microseconds
1000000000 nanoseconds
0 minutes
0 minutes
0.82672 microfortnights
0.316887 nanocenturies
24 frames at 24fps
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/chrono/duration&oldid=179838