Dates, Times and Durations

Our software often needs to deal with dates, times and durations. This lesson gives an brief introduction to the the most useful utilities within C++ to deal with these requirements. In C++, the chrono library is the main way we implement these features.

We can #include the library, and access its functionality through the std::chrono namespace.

1#include <chrono>
2
3using namespace std::chrono;
4

In this lesson, we will cover 3 aspects of chrono - durations, clocks and time points

Durations

A duration is a period of time. The chrono library gives us a range of functions to express durations, such as std::chrono::weeks, std::chrono::seconds and more.

1#include <chrono>
2using namespace std::chrono;
3
4int main() {
5  duration Duration1 { weeks(2) };
6  duration Duration2 { hours(5) };
7  duration Duration3 { milliseconds(100) };
8}
9

Where it makes sense, we can apply arithmetic and comparison operators to durations:

1// Add durations together
2duration Duration { weeks(2) + days(4) };
3
4// Increase an existing duration
5Duration += days(2);
6
7// Doubling a duration
8Duration *= 2;
9
10// Comparing durations
11if (Duration > days(100)) {
12  // Duration is longer than 100 days
13}
14

Duration Literals

Duration literals for hours and below are available:

1#include <chrono>
2using namespace std::chrono;
3
4int main() {
5    duration A { 3h };
6    duration B { 2min };
7    duration C { 1h + 2min + 3s + 4ms + 5us + 6ns };
8}
9

These literals require an appropriate using namespace statement to be available, such as using namespace std::chrono

Duration count

The underlying numeric value within a duration is available using the count method:

1#include <chrono>
2#include <iostream>
3
4using namespace std::chrono;
5
6int main() {
7  duration Duration { 3h };
8  std::cout << Duration.count() << " Hours" << std::endl;
9}
10

13 Hours
2

duration_cast

The duration_cast function allows us to convert a duration into an equivalent one, but using a different unit of measurement. For example, here we convert 3 hours to 180 minutes:

1#include <chrono>
2#include <iostream>
3
4using namespace std::chrono;
5
6int main() {
7    duration Duration { 3h };
8    duration InMinutes { duration_cast<minutes>(Duration) };
9    std::cout << InMinutes.count() << " Minutes" << std::endl;
10}
11

1180 Minutes
2

Pausing Execution Using sleep_for

In combination with the <thread> library, we can use durations to cause our application to go to sleep for a period of time:

1#include <iostream>
2#include <chrono>
3#include <thread>
4
5using namespace std;
6using namespace std::chrono;
7
8int main() {
9  cout << "Starting" << endl;
10  this_thread::sleep_for(seconds(5));
11  cout << "Done!";
12}
13

Clocks

A clock is a source of time information. By default, chrono offers 3 clocks:

• The system_clock, which uses data from the operating system's built in clock. For most cases, using this is the simplest approach.
• The steady_clock, which is designed to not be impacted by changes to the system clock. Use this if it is important that users cannot exploit our software by changing their system clock.
• The high_resolution_clock, which is designed to be highly accurate. Use this if we require millisecond, microsecond or nanosecond level accuracy. This can be useful when measuring performance, for example.

Time Points

Using data from a clock, we can generate a value representing a specific point in time. For example, to get the current time point from the system clock, we can do this:

1#include <chrono>
2
3using namespace std::chrono;
4
5int main() {
6  time_point CurrentTime {
7    system_clock::now()
8  };
9}
10

We can also add or remove durations to time points:

1time_point ThreeWeeksAgo {
2  system_clock::now() - weeks(3)
3};
4

And we can generate durations by comparing two time points:

1#include <chrono>
2#include <thread>
3#include <iostream>
4
5using namespace std;
6using namespace std::chrono;
7
8int main() {
9  time_point StartTime {
10    system_clock::now()
11  };
12
13  this_thread::sleep_for(seconds(5));
14
15  time_point EndTime {
16    system_clock::now()
17  };
18  
19  // Create a duration from two timepoints
20  duration RunningTime {
21    EndTime - StartTime
22  };
23
24  if (RunningTime >= 5s) {
25    cout << "That took a while!";
26  }
27}
28

1That took a while!
2

Outputting Times

Often, we will want to see the actual times being calculated within our software. The time_point objects are not designed for visual output, so there are a few steps we need to go through to get user friendly output.

First, we need to convert our time to a time_t object. This will convert our time point to a numeric value, usually representing the number of seconds that have passed since midnight on 1st January 1970. This format is commonly called epoch time.

When we're using the system_clock, a static function system_clock::to_time_t is available:

1time_point StartTime {
2  system_clock::now()
3};
4time_t TimeSinceEpoch {
5  system_clock::to_time_t(StartTime)
6};
7cout << TimeSinceEpoch;
8

This will output a number, similar to this:

11651075702
2

This is enough to let us confirm our time is working, but it's not the most user friendly output. We want something like 28th April 2023

To get there, first we can use the localtime_r function. This function takes two arguments. The first is a pointer to our time_t. The second argument is a pointer to a tm.

tm is a type of struct designed to hold date and time values, so we will need to create that object:

1tm TimeContainer;
2

Now that we have our time_t (which we called TimeSinceEpoch) and our tm (which we called TimeContainer), we pass their pointers into the localtime_r function.

The localtime_r function will then fill our TimeContainer with the correct data:

1time_point StartTime {
2  system_clock::now()
3};
4time_t TimeSinceEpoch {
5  system_clock::to_time_t(StartTime)
6};
7
8tm TimeContainer;
9localtime_r(&TimeSinceEpoch, &TimeContainer);
10

If we inspect our TimeContainer after running this code, we will find it has properties like tm_year, tm_month, tm_hour and more. These properties will be populated with appropriate values calculated from our TimeSinceEpoch variable.

We could use this this to generate our desired output, but the standard library provides a std::put_time function that can help us.

To access it, we need to #include <iomanip>. We can then call std::put_time, passing in a pointer to our time container, and a string that describes how we want our time to be formatted.

1#include <chrono>
2#include <iostream>
3#include <iomanip>
4
5using namespace std;
6using namespace std::chrono;
7
8int main() {
9  time_point StartTime {
10    system_clock::now()
11  };
12  time_t TimeSinceEpoch {
13    system_clock::to_time_t(StartTime)
14  };
15
16  tm TimeContainer;
17  localtime_r(&TimeSinceEpoch, &TimeContainer);
18
19  cout << put_time(
20    &TimeContainer,
21    "The current time is %r on %A"
22  );
23}
24

Running this code, we'd see we finally get a user friendly time output:

1The current time is 17:08:22 on Wednesday
2

The put_time function examines our format string, and replaces tokens like %r and %A with appropriate content from our TimeContainer.

There are dozens of different tokens we can use to get the output we want. Our options are listed on the official documentation.

Putting Everything Together

Lets put all these concepts together, to see a more complicated example of working with clocks, time points, durations and thread sleeping:

1#include <chrono>
2#include <iomanip>
3#include <iostream>
4#include <thread>
5
6using namespace std;
7using namespace std::chrono;
8
9void PrintTime(const time_t& Time) {
10  tm TimeContainer;
11  localtime_r(&Time, &TimeContainer);
12
13  cout << put_time(
14    &TimeContainer,
15    "The current time is %r on %A"
16  ) << endl;
17}
18
19int main() {
20  time_point StartTime{system_clock::now()};
21  PrintTime(system_clock::to_time_t(StartTime));
22
23  this_thread::sleep_for(seconds(5));
24
25  time_point EndTime{system_clock::now()};
26  PrintTime(system_clock::to_time_t(EndTime));
27
28  duration<float> RunningTime{EndTime - StartTime};
29
30  cout << "The running time was "
31       << RunningTime.count()
32       << " seconds";
33}
34

Our output will be something like:

1The current time is 17:23:21 on Wednesday
2The current time is 17:23:26 on Wednesday
3The running time was 5.01718s
4