Our software often needs to deal with dates, times, and durations. This lesson gives a brief introduction to 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;

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

Chrono Durations

A std::chrono::duration is a period of time, such as two weeks, one hour, or 1 minute and 30 seconds. 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>
2
3int main() {
4  using namespace std::chrono;
5  duration Duration1 { weeks(2) };
6  duration Duration2 { hours(5) };
7  duration Duration3 { milliseconds(100) };
8}

The duration type has overloaded the arithmetic operators such as + and *=, allowing us to combine durations in intuitive ways:

1#include <chrono>
2
3int main() {
4  using namespace std::chrono;
5
6  // Add durations together
7  duration Duration { weeks(2) + days(4) };
8
9  // Increase an existing duration
10  Duration += days(2);
11
12  // Doubling an existing duration
13  Duration *= 2;
14}

We can also compare durations using comparison operators such as > and <=:

1#include <chrono>
2
3int main() {
4  using namespace std::chrono;
5
6  duration Duration { weeks(2) + days(4) };
7
8  // This will be true
9  if (Duration > days(15)) {
10    // ...
11  }
12}

Duration Literals

Duration literals are available. These require us to have an appropriate using namespace statement in place. Options include:

using namespace std::chrono;
using namespace std::chrono_literals;
using namespace std::literals;

In scopes where an appropriate using statement is in effect, we can then express durations using literals such as h, min and s:

1#include <chrono>
2
3int main() {
4  using namespace std::chrono;
5  duration Hours{5h};
6  duration Minutes{5min};
7  duration Seconds{5s};
8  duration Milliseconds{5ms};
9  duration Microseconds{5us};
10  duration Nanoseconds{5ns};
11}

Duration `count()`

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

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

15 Hours

Changing Units Using `duration_cast()`

The duration_cast() function allows us to convert a duration into an equivalent duration, but using a different unit of measurement.

In the following example, we convert 1.5 hours to minutes, which results in a count() of 90 as we'd expect:

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

190 Minutes

Using a `duration` to Pause Execution

In combination with the <thread> library, we can use durations to cause our application to go to sleep for some time. This is available as the sleep_for() function on std::this_thread, which we have access to if we #include <thread>

Below, we use this to insert a 5-second pause between the "Starting" and "Done" logs:

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

1Starting
2Done!

Chrono Clocks

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

The system_clock uses data from the operating system's built-in clock. For most cases, using this is the simplest approach.
The steady_clock is designed not to 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.

Chrono Time Points

Using data from a clock, we can generate a value representing a specific point in time. Chrono represents time points using the std::chrono::time_point type. For example, to get the current time point from the system clock, we can do this:

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

We can also add or remove durations to time points. Below, we generate a time point 3 weeks in the past:

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

We can generate a duration by comparing time points using the - operator. Below, we generate two time points, approximately 5 seconds apart. We then store the difference between those two time points as a duration, which we output as milliseconds using duration_cast():

1#include <chrono>
2#include <iostream>
3#include <thread>
4
5int main() {
6  using namespace std::chrono;
7
8  time_point StartTime{system_clock::now()};
9  std::this_thread::sleep_for(seconds(5));
10  time_point EndTime{system_clock::now()};
11
12  // Create a duration from two time points
13  duration RunningTime{EndTime - StartTime};
14
15  std::cout << "Time difference in ms: "
16    << duration_cast<milliseconds>(
17      RunningTime).count();
18}

1Time difference in ms: 5007

Clock Drift

There is something to bear in mind when using sleep_for(), and almost any other way of causing our application to pause.

That is, our applications will always sleep for slightly longer than we requested. This is due to a nuance in how operating systems schedule processes. We should consider sleep_for() to be an instruction to "sleep for at least this amount of time".

In the previous program, we asked our application to sleep for 5 seconds, but it will typically sleep for around 5.007 seconds.

In most use cases, these fractions of a second don't matter - however, in some scenarios, they do. For example, if we create a long-running program that needs to be updated every second, we might use a loop that includes a sleep_for(1s) statement. However, if our loop iterations are delayed by 0.007 seconds on average, our program would lose around 10 minutes of accuracy every day.

For these scenarios, we need to compensate for the drift. A common way of doing this is to compare the current time point to the time point from the previous iteration of the loop, and adjust our sleep_for() argument accordingly.

For example, if we find the time points are 1.01 seconds apart, our next sleep_for() call should only be for 0.99 seconds. This causes our program to self-correct, and remain accurate even when running for long periods.

Using `std::time_t`

Chrono is a relatively new addition to the language. C++ has an older way of representing times, which is still commonly used. These times are typically stored using the std::time_t type, and we'll need to be able to interact with both.

Our Chrono clocks have functions that allow us to generate std::time_t objects from chrono::time_point objects. When we're using the system_clock, we can call the system_clock::to_time_t() function.

Below, we're using this to store the current time in a std::time_t called Time:

1#include <chrono>
2#include <iostream>
3
4int main() {
5  using namespace std::chrono;
6  time_point StartTime {
7    system_clock::now()
8  };
9
10  std::time_t Time {
11    system_clock::to_time_t(StartTime)
12  };
13
14  std::cout << Time;
15}

This will output a number, similar to this:

11651075702

Creating a `time_point` from a `time_t`

The previous example showed how we can create a time_t from a chrono time_point. We can also go in the opposite direction, creating a time_point from a time_t by using the from_time_t() functions:

1void HandleTime(std::time_t T) {
2  using namespace std::chrono;
3  time_point TP{system_clock::from_time_t(T)};
4  // ...
5}

Date and Time Structs (`tm`)

A Unix timestamp is enough to represent a time, but it's not a particularly friendly format to work with. An alternative way time points are stored is as tm structs. These represent dates and times in terms of their components - years, months, hours, etc.

Interpreting our std::time_t in this way involves two parts:

The standard library's tm struct gives us a way to create an object for storing these individual components. Our object will have member variables like tm_year, tm_hour, tm_min, and more. The complete list of its variables, and what they mean, are available on a standard library reference such as cppreference.com.
The localtime__r() function populates a tm object. This function takes two arguments. The first is a pointer to our time_t. The second argument is a pointer to the tm which it will populate:

1localtime_r(&TimePoint, &TimeContainer);

`localtime__r()` on Windows

When compiling on Windows, the localtime_r() function may result in compilation errors. This can be addressed by using localtime_s() instead, and switching the order of the arguments:

1// Before
2localtime_r(&TimePoint, &TimeContainer);
3
4// After
5localtime_s(&TimeContainer, &TimePoint);

Below, we create our tm called TimeContainer, and use the localtime_r() function to populate it using data from our time_t, which we've called TimeSinceEpoch:

1#include <chrono>
2#include <iostream>
3
4int main() {
5  using namespace std::chrono;
6  time_point StartTime {
7    system_clock::now()
8  };
9  std::time_t TimeSinceEpoch {
10    system_clock::to_time_t(StartTime)
11  };
12
13  tm TimeContainer;
14  localtime_s(&TimeContainer, &TimeSinceEpoch);
15
16  std::cout << "The current time is "
17    << TimeContainer.tm_hour << ":"
18    << TimeContainer.tm_min;
19}

1The current time is 23:32

Creating a `time_t` from a `tm`

If we want to go in the opposite direction, the std::mktime() function can help us. We pass it a pointer to a tm and it returns the equivalent time_t:

1void HandleTime(std::tm* T) {
2  std::time_t Time{std::mktime(T)};
3  // ...
4}

Using `std::put_time()` and Format Strings

Note: C++20 introduced std::format(), which is a modern and more flexible alternative to std::put_time(). If using std::put_time() causes issues or unexected output in your environment, don't worry too much about it. Just proceed to the next lesson, where we'll implement the same capability using std::format() instead.

Formatting a date and time to be displayed in a user-friendly way is a surprisingly complex task. With some effort, we could use the various member variables of the tm struct to accomplish it, but there are easier ways.

In this section, we'll cover std::put_time(), which lets us output the content of std::time_t objects using a formatting string. A formatting string is a string that contains special tokens that will be replaced by dynamic values, such as the contents of a variable.

To access std::put_time(), we need to #include <iomanip>. We can then call std::put_time(), which accepts two arguments:

A pointer to our time container
The formatting string

The following shows this in action:

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

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

1The current time is 17:08:01 on Wednesday

The std::put_time() function examines our format string and replaces tokens like %T and %A with dynamic content based on the values stored within the TimeContainer.

There are dozens of different tokens we can use to get the output we want. We cover these tokens in more detail in the next lesson, covering string interpolation. A full list of options is also available from most standard library references, such as cppreference.com.

Putting Everything Together

Let's 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
6void PrintTime(const time_t& Time) {
7  tm TimeContainer;
8  localtime_s(&TimeContainer, &Time);
9
10  std::cout << std::put_time(
11    &TimeContainer,
12    "The current time is %T on %A\n");
13}
14
15int main() {
16  using namespace std::chrono;
17  time_point StartTime{system_clock::now()};
18  PrintTime(system_clock::to_time_t(StartTime));
19
20  std::this_thread::sleep_for(seconds(5));
21
22  time_point EndTime{system_clock::now()};
23  PrintTime(system_clock::to_time_t(EndTime));
24
25  duration RunningTime{
26    EndTime - StartTime};
27
28  std::cout << "The running time was "
29    << duration_cast<milliseconds>(RunningTime)
30         .count()/1000.0 << " seconds";
31}

Our output will be something like:

1The current time is 17:13:12 PM on Wednesday
2The current time is 17:13:17 PM on Wednesday
3The running time was 5.012 seconds

Summary

In this lesson, we've explored the essential concepts of handling dates, times, and durations in C++ using the chrono library. We also introduced other representations of time, including Unix timestamps stored in the std::time_t type, and the tm struct.

Key Learnings:

Understanding and using std::chrono::duration for representing time intervals in various units.
Implementing and manipulating time using the chrono library, including addition, subtraction, and comparison of durations.
Utilizing different types of clocks in C++, namely system_clock, steady_clock, and high_resolution_clock, for various time measurement needs.
Creating and manipulating std::chrono::time_point objects to represent specific points in time.
Converting time points to and from std::time_t and using tm structures for a more readable time format.

Dates, Times and Durations

Chrono Durations

Duration Literals

Duration `count()`

Changing Units Using `duration_cast()`

Using a `duration` to Pause Execution

Chrono Clocks

Chrono Time Points

Using `std::time_t`

Date and Time Structs (`tm`)

Using `std::put_time()` and Format Strings

Putting Everything Together

Summary

String Interpolation

Intro to C++ Programming

Dates, Times and Durations

Chrono Durations

Duration Literals

Duration count()

Changing Units Using duration_cast()

Using a duration to Pause Execution

Chrono Clocks

Chrono Time Points

Using std::time_t

Date and Time Structs (tm)

Using std::put_time() and Format Strings

Putting Everything Together

Summary

String Interpolation

Duration `count()`

Changing Units Using `duration_cast()`

Using a `duration` to Pause Execution

Using `std::time_t`

Date and Time Structs (`tm`)

Using `std::put_time()` and Format Strings