Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/chrono/duration"

From cppreference.com
< cpp‎ | chrono
(Undo revision 155931 by Rust (talk))
(Added the hash<chrono::duration> item.)
Line 18: Line 18:
 
{{dsc hitem|Member type|Definition}}
 
{{dsc hitem|Member type|Definition}}
 
{{dsc|{{tt|rep}}|{{tt|Rep}}, an arithmetic type representing the number of ticks}}
 
{{dsc|{{tt|rep}}|{{tt|Rep}}, an arithmetic type representing the number of ticks}}
−
{{dsc|{{tt|period}}|{{rev inl|until=c++17|{{tt|Period}}}}{{rev inl|since=c++17|{{tt|typename Period::type}}}}, a {{lc|std::ratio}} representing the tick period (i.e. the number of second's fractions per tick)}}
+
{{dsc|{{tt|period}}|{{rev inl|until=c++17|{{tt|Period}}}}{{rev inl|since=c++17|{{c/core|typename Period::type}}}}, a {{lc|std::ratio}} representing the tick period (i.e. the number of second's fractions per tick)}}
 
{{dsc end}}
 
{{dsc end}}
  
Line 29: Line 29:
 
{{dsc inc|cpp/chrono/duration/dsc min}}
 
{{dsc inc|cpp/chrono/duration/dsc min}}
 
{{dsc inc|cpp/chrono/duration/dsc max}}
 
{{dsc inc|cpp/chrono/duration/dsc max}}
−
{{dsc inc|cpp/chrono/duration/dsc operator_arith}}
+
{{dsc inc|cpp/chrono/duration/dsc operator arith}}
−
{{dsc inc|cpp/chrono/duration/dsc operator_arith2}}
+
{{dsc inc|cpp/chrono/duration/dsc operator arith2}}
−
{{dsc inc|cpp/chrono/duration/dsc operator_arith3}}
+
{{dsc inc|cpp/chrono/duration/dsc operator arith3}}
 
{{dsc end}}
 
{{dsc end}}
  
 
===Non-member functions===
 
===Non-member functions===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc|cpp/chrono/duration/dsc operator_arith4}}
+
{{dsc inc|cpp/chrono/duration/dsc operator arith4}}
−
{{dsc inc|cpp/chrono/duration/dsc operator_cmp}}
+
{{dsc inc|cpp/chrono/duration/dsc operator cmp}}
−
{{dsc inc|cpp/chrono/duration/dsc duration_cast}}
+
{{dsc inc|cpp/chrono/duration/dsc duration cast}}
 
{{dsc inc|cpp/chrono/duration/dsc floor}}
 
{{dsc inc|cpp/chrono/duration/dsc floor}}
 
{{dsc inc|cpp/chrono/duration/dsc ceil}}
 
{{dsc inc|cpp/chrono/duration/dsc ceil}}
 
{{dsc inc|cpp/chrono/duration/dsc round}}
 
{{dsc inc|cpp/chrono/duration/dsc round}}
 
{{dsc inc|cpp/chrono/duration/dsc abs}}
 
{{dsc inc|cpp/chrono/duration/dsc abs}}
−
{{dsc inc|cpp/chrono/duration/dsc operator_ltlt}}
+
{{dsc inc|cpp/chrono/duration/dsc operator ltlt}}
 
{{dsc inc|cpp/chrono/duration/dsc from_stream}}
 
{{dsc inc|cpp/chrono/duration/dsc from_stream}}
 
{{dsc end}}
 
{{dsc end}}
  
 
===Helper types===
 
===Helper types===
 +
A type {{c/core|/* intXX */}} used in the table below means a signed interger type of at least XX bits.
 
{{dsc begin}}
 
{{dsc begin}}
 
{{dsc hitem|Type|Definition}}
 
{{dsc hitem|Type|Definition}}
−
{{dsc|{{lc|std::chrono::nanoseconds}}|{{c|duration</*signed integer type of at least 64 bits*/, std::nano>}}}}
+
{{dsc|{{ttb|std::chrono::nanoseconds}}|{{c/core|std::chrono::duration</* int64 */, std::nano>}}}}
−
{{dsc|{{lc|std::chrono::microseconds}}|{{c|duration</*signed integer type of at least 55 bits*/, std::micro>}}}}
+
{{dsc|{{ttb|std::chrono::microseconds}}|{{c/core|std::chrono::duration</* int55 */, std::micro>}}}}
−
{{dsc|{{lc|std::chrono::milliseconds}}|{{c|duration</*signed integer type of at least 45 bits*/, std::milli>}}}}
+
{{dsc|{{ttb|std::chrono::milliseconds}}|{{c/core|std::chrono::duration</* int45 */, std::milli>}}}}
−
{{dsc|{{lc|std::chrono::seconds}}|{{c|duration</*signed integer type of at least 35 bits*/>}}}}
+
{{dsc|{{ttb|std::chrono::seconds}}|{{c/core|std::chrono::duration</* int35 */>}}}}
−
{{dsc|{{lc|std::chrono::minutes}}|{{c|duration</*signed integer type of at least 29 bits*/, std::ratio<60>>}}}}
+
{{dsc|{{ttb|std::chrono::minutes}}|{{c/core|std::chrono::duration</* int29 */, std::ratio<60>>}}}}
−
{{dsc|{{lc|std::chrono::hours}}|{{c|duration</*signed integer type of at least 23 bits*/, std::ratio<3600>>}}}}
+
{{dsc|{{ttb|std::chrono::hours}}|{{c/core|std::chrono::duration</* int23 */, std::ratio<3600>>}}}}
−
{{dsc|{{lc|std::chrono::days}} {{mark since c++20}}|{{c|duration</*signed integer type of at least 25 bits*/, std::ratio<86400>>}}}}
+
{{dsc|{{ttb|std::chrono::days}} {{mark since c++20}}|{{c/core|std::chrono::duration</* int25 */, std::ratio<86400>>}}}}
−
{{dsc|{{lc|std::chrono::weeks}} {{mark since c++20}}|{{c|duration</*signed integer type of at least 22 bits*/, std::ratio<604800>>}}}}
+
{{dsc|{{ttb|std::chrono::weeks}} {{mark since c++20}}|{{c/core|std::chrono::duration</* int22 */, std::ratio<604800>>}}}}
−
{{dsc|{{lc|std::chrono::months}} {{mark since c++20}}|{{c|duration</*signed integer type of at least 20 bits*/, std::ratio<2629746>>}}}}
+
{{dsc|{{ttb|std::chrono::months}} {{mark since c++20}}|{{c/core|std::chrono::duration</* int20 */, std::ratio<2629746>>}}}}
−
{{dsc|{{lc|std::chrono::years}} {{mark since c++20}}|{{c|duration</*signed integer type of at least 17 bits*/, std::ratio<31556952>>}}}}
+
{{dsc|{{ttb|std::chrono::years}} {{mark since c++20}}|{{c/core|std::chrono::duration</* int17 */, std::ratio<31556952>>}}}}
 
{{dsc end}}
 
{{dsc end}}
 
Note: each of the predefined duration types up to {{tt|hours}} covers a range of at least ±292 years.
 
Note: each of the predefined duration types up to {{tt|hours}} covers a range of at least ±292 years.
Line 71: Line 72:
 
{{dsc inc|cpp/chrono/dsc duration_values}}
 
{{dsc inc|cpp/chrono/dsc duration_values}}
 
{{dsc inc|cpp/chrono/dsc formatter|duration}}
 
{{dsc inc|cpp/chrono/dsc formatter|duration}}
 +
{{dsc hash|cpp/chrono/duration|notes={{mark c++26}}}}
 
{{dsc end}}
 
{{dsc end}}
  
Line 87: Line 89:
 
Note: the literal suffixes {{tt|d}} and {{tt|y}} do not refer to {{tt|days}} and {{tt|years}} but to {{ltt|cpp/chrono/day}} and {{ltt|cpp/chrono/year}}, respectively.
 
Note: the literal suffixes {{tt|d}} and {{tt|y}} do not refer to {{tt|days}} and {{tt|years}} but to {{ltt|cpp/chrono/day}} and {{ltt|cpp/chrono/year}}, respectively.
 
}}
 
}}
 +
 +
===Notes===
 +
The actual time interval (in seconds) that is held by a duration object {{c|d}} is roughly equal to {{c|1=d.count() * D::period::num / D::period::den}}, where {{tt|D}} is of type {{tt|chrono::duration<>}} and {{c|d}} is an object of such type.
  
 
{{feature test macro|__cpp_lib_chrono_udls|value=201304L|std=C++14|[[#Literals|User-defined literals for time types]]}}
 
{{feature test macro|__cpp_lib_chrono_udls|value=201304L|std=C++14|[[#Literals|User-defined literals for time types]]}}
−
 
−
===Notes===
 
−
The actual time interval (in seconds) that is held by a duration object {{tt|d}} is roughly equal to {{c|1=d.count() * D::period::num / D::period::den}}, where {{tt|D}} is of type {{tt|chrono::duration<>}} and {{tt|d}} is an object of such type.
 
  
 
===Example===
 
===Example===
Line 107: Line 109:
 
int main()
 
int main()
 
{
 
{
−
    using shakes = std::chrono::duration<int, mul<std::deca, std::nano>>;
 
−
    using jiffies = std::chrono::duration<int, std::centi>;
 
 
     using microfortnights = std::chrono::duration<float,
 
     using microfortnights = std::chrono::duration<float,
 
         mul<mul<std::ratio<2>, std::chrono::weeks::period>, std::micro>>;
 
         mul<mul<std::ratio<2>, std::chrono::weeks::period>, std::micro>>;
 
     using nanocenturies = std::chrono::duration<float,
 
     using nanocenturies = std::chrono::duration<float,
 
         mul<mul<std::hecto, std::chrono::years::period>, std::nano>>;
 
         mul<mul<std::hecto, std::chrono::years::period>, std::nano>>;
−
     using fps_24 = std::chrono::duration<double, std::ratio<1,24>>;
+
     using fps_24 = std::chrono::duration<double, std::ratio<1, 24>>;
−
 
+
   
 
     std::cout << "1 second is:\n";
 
     std::cout << "1 second is:\n";
−
 
+
   
 
     // integer scale conversion with no precision loss: no cast
 
     // integer scale conversion with no precision loss: no cast
−
     std::cout << std::chrono::microseconds(1s).count() << " microseconds\n"
+
     std::cout << std::chrono::milliseconds(1s).count() << " milliseconds\n"
−
               << shakes(1s).count() << " shakes\n"
+
               << std::chrono::microseconds(1s).count() << " microseconds\n"
−
               << jiffies(1s).count() << " jiffies\n";
+
               << std::chrono::nanoseconds(1s).count() << " nanoseconds\n";
−
 
+
   
 
     // integer scale conversion with precision loss: requires a cast
 
     // integer scale conversion with precision loss: requires a cast
 
     std::cout << std::chrono::duration_cast<std::chrono::minutes>(1s).count()
 
     std::cout << std::chrono::duration_cast<std::chrono::minutes>(1s).count()
 
               << " minutes\n";
 
               << " minutes\n";
−
 
+
   
 
     // floating-point scale conversion: no cast
 
     // floating-point scale conversion: no cast
 
     std::cout << microfortnights(1s).count() << " microfortnights\n"
 
     std::cout << microfortnights(1s).count() << " microfortnights\n"
Line 133: Line 133:
 
|output=
 
|output=
 
1 second is:
 
1 second is:
 +
1000 milliseconds
 
1000000 microseconds
 
1000000 microseconds
−
100000000 shakes
+
1000000000 nanoseconds
−
100 jiffies
+
 
0 minutes
 
0 minutes
 
0.82672 microfortnights
 
0.82672 microfortnights

Revision as of 00:42, 30 August 2023

 
C++
 
Utilities library
General utilities
Relational operators (deprecated in C++20)
 
Date and time utilities
Time point
(C++11)
(C++20)
Duration
duration
(C++11)
Clocks
(C++11)
(C++11)
(C++20)
(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)
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 representing the time in 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.

Contents

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 second's fractions per tick)

Member functions

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

Non-member functions

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

Helper types

A type /* intXX */ used in the table below means a signed interger 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) [edit]
(C++11)
 indicates that a duration is convertible to duration with different tick period
(class template) [edit]
(C++11)
 constructs zero, min, and max values of a tick count of given type
(class template) [edit]
(C++20)
 formatting support for duration
(class template specialization) [edit]
(C++26)
 hash support for std::duration
(class template specialization)

Literals

Defined in inline namespace std::literals::chrono_literals
(C++14)
 a std::chrono::duration literal representing hours
(function) [edit]
(C++14)
 a std::chrono::duration literal representing minutes
(function) [edit]
(C++14)
 a std::chrono::duration literal representing seconds
(function) [edit]
(C++14)
 a std::chrono::duration literal representing milliseconds
(function) [edit]
(C++14)
 a std::chrono::duration literal representing microseconds
(function) [edit]
(C++14)
 a std::chrono::duration literal representing nanoseconds
(function) [edit]

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

(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 is an object of such type.

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";
 
    // 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.82672 microfortnights
0.316887 nanocenturies
24 frames at 24fps
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/chrono/duration&oldid=157549"