Dates, Times and Durations

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

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

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);

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

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.

Preview of the Next Lesson

In the upcoming lesson, we’ll learn more about string interpolation in C++, focusing on the powerful std::format() and std::print() functions introduced in C++20 and C++23.

Building on our knowledge from this lesson, we'll see how these functions can be seamlessly integrated with the chrono library to format and display dates and times in a more user-friendly manner.

Key Topics Include:

• Introduction to std::format() and std::print() functions for advanced string formatting.
• Understanding format specifiers and how they can be used to customize the output.
• Practical examples demonstrating the use of std::format() and std::print() in real-world scenarios.
• Techniques for incorporating chrono library types with std::format() to output time and date information.

Free and Unlimited Access

Professional C++

Unlock the true power of C++ by mastering complex features, optimizing performance, and learning expert workflows used in professional development

View Course