Difference between revisions of "cpp/chrono/duration"

Latest revision as of 04:29, 24 July 2024

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.

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

[edit] Non-member functions

operator+operator-operator*operator/operator% (C++11)	implements arithmetic operations with durations as arguments (function template) [edit]
operator==operator!=operator<operator<=operator>operator>=operator<=> (C++11)(C++11)(removed in C++20)(C++11)(C++11)(C++11)(C++11)(C++20)	compares two durations (function template) [edit]
duration_cast (C++11)	converts a duration to another, with a different tick interval (function template) [edit]
floor(std::chrono::duration) (C++17)	converts a duration to another, rounding down (function template) [edit]
ceil(std::chrono::duration) (C++17)	converts a duration to another, rounding up (function template) [edit]
round(std::chrono::duration) (C++17)	converts a duration to another, rounding to nearest, ties to even (function template) [edit]
abs(std::chrono::duration) (C++17)	obtains the absolute value of the duration (function template) [edit]
operator<< (C++20)	performs stream output on a `duration` (function template) [edit]
from_stream (C++20)	parses a `duration` from a stream according to the provided format (function template) [edit]

[edit] 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)

[edit] Helper classes

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

[edit] 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 enables it.

[edit] Literals

Defined in inline namespace `std::literals::chrono_literals`
operator""h (C++14)	a std::chrono::duration literal representing hours (function) [edit]
operator""min (C++14)	a std::chrono::duration literal representing minutes (function) [edit]
operator""s (C++14)	a std::chrono::duration literal representing seconds (function) [edit]
operator""ms (C++14)	a std::chrono::duration literal representing milliseconds (function) [edit]
operator""us (C++14)	a std::chrono::duration literal representing microseconds (function) [edit]
operator""ns (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)

[edit] 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

[edit] 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

@@ Line 1: / Line 1: @@
 {{cpp/chrono/title|duration}}
 {{cpp/chrono/duration/navbar}}
-{{dcl begin}}
+{{ddcl|header=chrono|since=c++11|1=
-{{dcl header | chrono}}
-{{dcl | since=c++11 | 1=
 template<
      class Rep,
      class Period = std::ratio<1>
 > class duration;
 }}
-{{dcl end}}
 Class template {{tt|std::chrono::duration}} represents a time interval.
-It consists of a count of ticks of type {{tt|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.
+It consists of a count of ticks of type {{tt|Rep}} and a tick period, where the tick period is a compile-time rational {{ltt|cpp/numeric/ratio/ratio|fraction}} representing the time in seconds from one tick to the next.
-The only data stored in a {{tt|duration}} is a tick count of type {{tt|Rep}}.<!-- per N2661, not actually in the standard wording -->  If {{tt|Rep}} is floating point, then the {{tt|duration}} can represent fractions of ticks.  {{tt|Period}} is included as part of the duration's type, and is only used when converting between different durations.
+The only data stored in a {{tt|duration}} is a tick count of type {{tt|Rep}}.<!--per N2661, not actually in the standard wording--> If {{tt|Rep}} is floating point, then the {{tt|duration}} can represent fractions of ticks. {{tt|Period}} is included as part of the duration's type, and is only used when converting between different durations.
 ===Member types===
 {{dsc begin}}
-{{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, or a class emulating 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 seconds 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}}
 ===Member functions===
 {{dsc begin}}
-{{dsc inc | cpp/chrono/duration/dsc constructor}}
+{{dsc inc|cpp/chrono/duration/dsc constructor}}
-{{dsc inc | cpp/chrono/duration/dsc operator{{=}} }}
+{{dsc inc|cpp/chrono/duration/dsc operator{{=}}}}
-{{dsc inc | cpp/chrono/duration/dsc count }}
+{{dsc inc|cpp/chrono/duration/dsc count}}
-{{dsc inc | cpp/chrono/duration/dsc zero }}
+{{dsc inc|cpp/chrono/duration/dsc zero}}
-{{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}}
 ===Non-member functions===
 {{dsc begin}}
-{{dsc inc | cpp/chrono/duration/dsc common_type}}
+{{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 to_stream}}
-{{dsc inc | cpp/chrono/duration/dsc from_stream}}
 {{dsc end}}
 ===Helper types===
+A type {{c/core|/* intXX */}} used in the table below means a signed integer type of at least XX bits.
 {{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}}
 Note: each of the predefined duration types up to {{tt|hours}} covers a range of at least ±292 years.
-{{rrev|since=c++20|Each of the predefined duration types {{tt|days}}, {{tt|weeks}}, {{tt|months}} and {{tt|years}} covers a range of at least ±40000 years. {{tt|years}} is equal to 365.2425 {{tt|days}} (the average length of a Gregorian year). {{tt|months}} is equal to 30.436875 {{tt|days}} (exactly 1/12 of {{tt|years}}). }}
+{{rrev|since=c++20|Each of the predefined duration types {{tt|days}}, {{tt|weeks}}, {{tt|months}} and {{tt|years}} covers a range of at least ±40000 years. {{tt|years}} is equal to 365.2425 {{tt|days}} (the average length of a Gregorian year). {{tt|months}} is equal to 30.436875 {{tt|days}} (exactly 1/12 of {{tt|years}}).}}
 ===Helper classes===
 {{dsc begin}}
-{{dsc tclass | cpp/chrono/treat_as_floating_point | indicates that a duration is convertible to duration with different tick period }}
+{{dsc inc|cpp/chrono/duration/dsc common_type}}
-{{dsc tclass | cpp/chrono/duration_values | constructs zero, min, and max values of a tick count of given type}}
+{{dsc inc|cpp/chrono/dsc treat_as_floating_point}}
+{{dsc inc|cpp/chrono/dsc duration_values}}
+{{dsc inc|cpp/chrono/dsc formatter|duration}}
+{{dsc hash|cpp/chrono/duration|nested=true|notes={{mark c++26}}}}
 {{dsc end}}
+===Helper specializations===
+{{dcl begin}}
+{{dcl|since=c++23|1=
+template< class Rep, class Period >
+constexpr bool enable_nonlocking_formatter_optimization<chrono::duration<Rep, Period>>
+ = enable_nonlocking_formatter_optimization<Rep>;
+}}
+{{dcl end}}
+This specialization of {{ltt std|cpp/utility/format/enable_nonlocking_formatter_optimization}} enables efficient implementation of {{ltt std|cpp/io/print}} and {{ltt std|cpp/io/println}} for printing a {{tt|chrono::duration}} object when the template parameter {{tt|Rep}} enables it.
 ===Literals===
 {{dsc begin}}
-{{dsc namespace | std::literals::chrono_literals | inline=true }}
+{{dsc namespace|std::literals::chrono_literals|inline=true}}
-{{dsc inc | cpp/chrono/dsc operator""h}}
+{{dsc inc|cpp/chrono/dsc operator""h}}
-{{dsc inc | cpp/chrono/dsc operator""min}}
+{{dsc inc|cpp/chrono/dsc operator""min}}
-{{dsc inc | cpp/chrono/dsc operator""s}}
+{{dsc inc|cpp/chrono/dsc operator""s}}
-{{dsc inc | cpp/chrono/dsc operator""ms}}
+{{dsc inc|cpp/chrono/dsc operator""ms}}
-{{dsc inc | cpp/chrono/dsc operator""us}}
+{{dsc inc|cpp/chrono/dsc operator""us}}
-{{dsc inc | cpp/chrono/dsc operator""ns}}
+{{dsc inc|cpp/chrono/dsc operator""ns}}
 {{dsc end}}
 {{rrev|since=c++20|
-Note: the literal suffixes {{tt|d}}, {{tt|m}} and {{tt|y}} do not refer to {{tt|days}}, {{tt|months}} and {{tt|years}} but to {{ltt|cpp/chrono/day}}, {{ltt|cpp/chrono/month}} 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]]}}
 ===Example===
 {{example
- | This example shows how to define several custom duration types and convert between types:
+|This example shows how to define several custom duration types and convert between types:
- | code=
+|code=
-#include <iostream>
 #include <chrono>
+#include <iostream>
-constexpr auto year = 31556952ll; // seconds in average Gregorian year
+using namespace std::chrono_literals;
+template<typename T1, typename T2>
+using mul = std::ratio_multiply<T1, T2>;
 int main()
 {
-     using shakes = std::chrono::duration<int, std::ratio<1, 100000000>>;
+     using microfortnights = std::chrono::duration<float,
-    using jiffies = std::chrono::duration<int, std::centi>;
+        mul<mul<std::ratio<2>, std::chrono::weeks::period>, std::micro>>;
-     using microfortnights = std::chrono::duration<float, std::ratio<14*24*60*60, 1000000>>;
+     using nanocenturies = std::chrono::duration<float,
-     using nanocenturies = std::chrono::duration<float, std::ratio<100*year, 1000000000>>;
+        mul<mul<std::hecto, std::chrono::years::period>, std::nano>>;
+     using fps_24 = std::chrono::duration<double, std::ratio<1, 24>>;
-     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"
+     std::cout << std::chrono::milliseconds(1s).count() << " milliseconds\n"
-               << shakes(sec).count() << " shakes\n"
+               << std::chrono::microseconds(1s).count() << " microseconds\n"
-               << jiffies(sec).count() << " jiffies\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>(sec).count()
+     std::cout << std::chrono::duration_cast<std::chrono::minutes>(1s).count()
                << " minutes\n";
      // floating-point scale conversion: no cast
-     std::cout << microfortnights(sec).count() << " microfortnights\n"
+     std::cout << microfortnights(1s).count() << " microfortnights\n"
-               << nanocenturies(sec).count() << " nanocenturies\n";
+               << nanocenturies(1s).count() << " nanocenturies\n"
+              << fps_24(1s).count() << " frames at 24fps\n";
 }
- | output=
+|output=
 second is:
+milliseconds
 1000000 microseconds
-100000000 shakes
+1000000000 nanoseconds
-jiffies
 minutes
 .82672 microfortnights
 .316887 nanocenturies
+frames at 24fps
 }}
-[[de:cpp/chrono/duration]]
+{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
-[[es:cpp/chrono/duration]]
-[[fr:cpp/chrono/duration]]
-[[it:cpp/chrono/duration]]
-[[ja:cpp/chrono/duration]]
-[[pt:cpp/chrono/duration]]
-[[ru:cpp/chrono/duration]]
-[[zh:cpp/chrono/duration]]

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

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 representing the tick period (i.e. the number of second's fractions per tick)

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/chrono/duration"

Latest revision as of 04:29, 24 July 2024

Contents

[edit] Member types

[edit] Member functions