Duration

A duration is an interval between two points in time. It is represented by the duration class template, which stores a number of ticks and a tick period. The tick period is the time in seconds between two ticks and is represented as a compile-time ratio constant, which means it could be a fraction of a second. Ratios are discussed in the previous section. The duration template accepts two template parameters and is defined as follows:

template <class Rep, class Period = ratio<1>> class duration {...}

The first template parameter, Rep, is the type of variable storing the number of ticks and should be an arithmetic type, for example long, double, and so on. The second template parameter, Period, is the rational constant representing the period of a tick. If you don’t specify the tick period, the default value ratio<1> is used, which represents a tick period of one second.

Three constructors are provided: the default constructor; one that accepts a single value, the number of ticks; and one that accepts another duration. The latter constructor can be used to convert from one duration to another duration, for example, from minutes to seconds. An example is given later in this section.

Durations support arithmetic operations such as +, -, *, /, %, ++, --, +=, -=, *=, /=, and %=, and support the comparison operators. The class also contains the methods shown in the following table.

C++17 adds floor(), ceil(), round(), and abs() operations for durations that behave just as they behave with numerical data.

Let’s see how durations can be used in actual code. A duration where each tick is one second can be defined as follows:

duration<long> d1;

Because ratio<1> is the default tick period, this is the same as writing the following:

duration<long, ratio<1>> d1;

The following defines a duration in minutes (tick period = 60 seconds):

duration<long, ratio<60>> d2;

To define a duration where each tick period is a sixtieth of a second, use the following:

duration<double, ratio<1, 60>> d3;

As you saw earlier in this chapter, the <ratio> header file defines a number of SI rational constants. These predefined constants come in handy for defining tick periods. For example, the following line of code defines a duration where each tick period is one millisecond:

duration<long long, milli> d4;

The following example demonstrates several aspects of durations. It shows you how to define durations, how to perform arithmetic operations on them, and how to convert one duration into another duration with a different tick period.

// Specify a duration where each tick is 60 seconds
duration<long, ratio<60>> d1(123);
cout << d1.count() << endl;

// Specify a duration represented by a double with each tick
// equal to 1 second and assign the largest possible duration to it.
duration<double> d2;
d2 = d2.max();
cout << d2.count() << endl;

// Define 2 durations:
// For the first duration, each tick is 1 minute
// For the second duration, each tick is 1 second
duration<long, ratio<60>> d3(10);  // = 10 minutes
duration<long, ratio<1>> d4(14);   // = 14 seconds

// Compare both durations
if (d3 > d4)
    cout << "d3 > d4" << endl;
else
    cout << "d3 <= d4" << endl;

// Increment d4 with 1 resulting in 15 seconds
++d4;

// Multiply d4 by 2 resulting in 30 seconds
d4 *= 2;

// Add both durations and store as minutes
duration<double, ratio<60>> d5 = d3 + d4;

// Add both durations and store as seconds
duration<long, ratio<1>> d6 = d3 + d4;
cout << d3.count() << " minutes + " << d4.count() << " seconds = "
     << d5.count() << " minutes or "
     << d6.count() << " seconds" << endl;

// Create a duration of 30 seconds
duration<long> d7(30);

// Convert the seconds of d7 to minutes
duration<double, ratio<60>> d8(d7);
cout << d7.count() << " seconds = " << d8.count() << " minutes" << endl;

The output is as follows:

123
1.79769e+308
d3 > d4
10 minutes + 30 seconds = 10.5 minutes or 630 seconds
30 seconds = 0.5 minutes

Pay special attention to the following two lines:

duration<double, ratio<60>> d5 = d3 + d4;
duration<long, ratio<1>> d6 = d3 + d4;

They both calculate d3+d4 but the first line stores it as a floating point value representing minutes, while the second line stores the result as an integral value representing seconds. Conversion from minutes to seconds or vice versa happens automatically.

The following two lines from the preceding example demonstrate how to explicitly convert between different units of time:

duration<long> d7(30);               // seconds
duration<double, ratio<60>> d8(d7);  // minutes

The first line defines a duration representing 30 seconds. The second line converts these 30 seconds into minutes, resulting in 0.5 minutes. Converting in this direction can result in a non-integral value, and thus requires you to use a duration represented by a floating point type; otherwise, you will get some cryptic compilation errors. The following lines, for example, do not compile because d8 is using long instead of a floating point type:

duration<long> d7(30);               // seconds
duration<long, ratio<60>> d8(d7);    // minutes   // Error!

You can, however, force this conversion by using duration_cast():

duration<long> d7(30);               // seconds
auto d8 = duration_cast<duration<long, ratio<60>>>(d7); // minutes

In this case, d8 will be 0 minutes, because integer division is used to convert 30 seconds to minutes.

Converting in the other direction does not require floating point types if the source is an integral type, because the result is always an integral value if you started with an integral value. For example, the following lines convert ten minutes into seconds, both represented by the integral type long:

duration<long, ratio<60>> d9(10);    // minutes
duration<long> d10(d9);              // seconds

The library provides the following standard duration types in the std::chrono namespace:

using nanoseconds  = duration<X 64 bits, nano>;
using microseconds = duration<X 55 bits, micro>;
using milliseconds = duration<X 45 bits, milli>;
using seconds      = duration<X 35 bits>;
using minutes      = duration<X 29 bits, ratio<60>>;
using hours        = duration<X 23 bits, ratio<3600>>;

The exact type of X depends on your compiler, but the C++ standard requires it to be a signed integer type of at least the specified size. The preceding type aliases make use of the predefined SI ratio type aliases that are described earlier in this chapter. With these predefined types, instead of writing this,

duration<long, ratio<60>> d9(10);    // minutes

you can simply write this:

minutes d9(10);                      // minutes

The following code is another example of how to use these predefined durations. The code first defines a variable t, which is the result of 1 hour + 23 minutes + 45 seconds. The auto keyword is used to let the compiler automatically figure out the exact type of t. The second line uses the constructor of the predefined seconds duration to convert the value of t to seconds, and writes the result to the console.

auto t = hours(1) + minutes(23) + seconds(45);
cout << seconds(t).count() << " seconds" << endl;

Because the standard requires that the predefined durations use integer types, there can be compilation errors if a conversion could end up with a non-integral value. While integer division normally truncates, in the case of durations, which are implemented with ratio types, the compiler declares any computation that could result in a non-zero remainder as a compile-time error. For example, the following code does not compile because converting 90 seconds to minutes results in 1.5 minutes:

seconds s(90);
minutes m(s);

However, the following code does not compile either, even though 60 seconds is exactly 1 minute. It is flagged as a compile-time error because converting from seconds to minutes could result in non-integral values.

seconds s(60);
minutes m(s);

Converting in the other direction works perfectly fine because the minutes duration uses an integral type and converting it to seconds always results in an integral value:

minutes m(2);
seconds s(m);

You can use the standard user-defined literals “h”, “min”, “s”, “ms”, “us”, and “ns” for creating durations. Technically, these are defined in the std::literals::chrono_literals namespace, but also made accessible with using namespace std::chrono. Here is an example:

using namespace std::chrono;
// ...
auto myDuration = 42min;    // 42 minutes

Clock

A clock is a class consisting of a time_point and a duration. The time_point type is discussed in detail in the next section, but those details are not required to understand how clocks work. However, time_points themselves depend on clocks, so it’s important to know the details of clocks first.

Three clocks are defined by the standard. The first one is called system_clock and represents the wall clock time from the system-wide real-time clock. The second one is called steady_clock, and it guarantees its time_point will never decrease, which is not guaranteed for system_clock because the system clock can be adjusted at any time. The third one is the high_resolution_clock, which has the shortest possible tick period. Depending on your compiler, it is possible for the high_resolution_clock to be a synonym for steady_clock or system_clock.

Every clock has a static now() method to get the current time as a time_point. The system_clock also defines two static helper functions for converting time_points to and from the time_t C-style time representation. The first function is called to_time_t(), and it converts a given time_point to a time_t; the second function is called from_time_t(), and it returns a time_point initialized with a given time_t value. The time_t type is defined in the <ctime> header file.

The following example shows a complete program which gets the current time from the system and outputs the time in a human-readable format to the console. The localtime() function converts a time_t to a local time represented by tm and is defined in the <ctime> header file. The put_time() stream manipulator, defined in the <iomanip> header, is introduced in Chapter 13.

// Get current time as a time_point
system_clock::time_point tpoint = system_clock::now();
// Convert to a time_t
time_t tt = system_clock::to_time_t(tpoint);
// Convert to local time
tm* t = localtime(&tt);
// Write the time to the console
cout << put_time(t, "%H:%M:%S") << endl;

If you want to convert a time to a string, you can use an std::stringstream or the C-style strftime() function, defined in <ctime>, as follows. Using the strftime() function requires you to supply a buffer that is big enough to hold the human-readable representation of the given time:

// Get current time as a time_point
system_clock::time_point tpoint = system_clock::now();
// Convert to a time_t
time_t tt = system_clock::to_time_t(tpoint);
// Convert to local time
tm* t = localtime(&tt);
// Convert to readable format
char buffer[80] = {0};
strftime(buffer, sizeof(buffer), "%H:%M:%S", t);
// Write the time to the console
cout << buffer << endl;

The chrono library can also be used to time how long it takes for a piece of code to execute. The following example shows how you can do this. The actual type of the variables start and end is high_resolution_clock::time_point, and the actual type of diff is a duration.

// Get the start time
auto start = high_resolution_clock::now();
// Execute code that you want to time
double d = 0;
for (int i = 0; i < 1000000; ++i) {
    d += sqrt(sin(i) * cos(i));
}
// Get the end time and calculate the difference
auto end = high_resolution_clock::now();
auto diff = end - start;
// Convert the difference into milliseconds and output to the console
cout << duration<double, milli>(diff).count() << "ms" << endl;

The loop in this example is performing some arithmetic operations with sqrt(), sin(), and cos() to make sure the loop doesn’t end too fast. If you get really small values for the difference in milliseconds on your system, those values will not be accurate and you should increase the number of iterations of the loop to make it last longer. Small timings will not be accurate because, while timers often have a resolution in milliseconds, on most operating systems, this timer is updated infrequently, for example, every 10 ms or 15 ms. This induces a phenomenon called gating error, where any event that occurs in less than one timer tick appears to take place in zero units of time; any event between one and two timer ticks appears to take place in one timer unit. For example, on a system with a 15 ms timer update, a loop that takes 44 ms will appear to take only 30 ms. When using such timers to time computations, it is important to make sure that the entire computation takes place across a fairly large number of basic timer tick units so that these errors are minimized.

Time Point

A point in time is represented by the time_point class and stored as a duration relative to the epoch. A time_point is always associated with a certain clock and the epoch is the origin of this associated clock. For example, the epoch for the classic Unix/Linux time is 1st of January 1970, and durations are measured in seconds. The epoch for Windows is 1st of January 1601 and durations are measured in 100-nanosecond units. Other operating systems have different epoch dates and duration units.

The time_point class contains a function called time_since_epoch(), which returns a duration representing the time between the epoch of the associated clock and the stored point in time.

Arithmetic operations of time_points and durations that make sense are supported. The following table lists those operations. tp is a time_point and d is a duration.

An example of an operation that is not supported is tp+tp.

Comparison operators are also supported to compare two time points. Two static methods are provided: min(), which returns the smallest possible point in time, and max(), which returns the largest possible point in time.

The time_point class has three constructors.

• time_point(): This constructs a time_point initialized with duration::zero(). The resulting time_point represents the epoch of the associated clock.
• time_point(const duration& d): This constructs a time_point initialized with the given duration. The resulting time_point represents epoch + d.
• template <class Duration2> time_point(const time_point<clock, Duration2>& t): This constructs a time_point initialized with t.time_since_epoch().

Each time_point is associated with a clock. To create a time_point, you specify the clock as the template parameter:

time_point<steady_clock> tp1;

Each clock also knows its time_point type, so you can also write it as follows:

steady_clock::time_point tp1;

The following example demonstrates the time_point class:

// Create a time_point representing the epoch
// of the associated steady clock
time_point<steady_clock> tp1;
// Add 10 minutes to the time_point
tp1 += minutes(10);
// Store the duration between epoch and time_point
auto d1 = tp1.time_since_epoch();
// Convert the duration to seconds and output to the console
duration<double> d2(d1);
cout << d2.count() << " seconds" << endl;

The output should be as follows:

600 seconds

Converting time_points can be done implicitly or explicitly, similar to duration conversions. Here is an example of an implicit conversion. The output is 42000 ms.

time_point<steady_clock, seconds> tpSeconds(42s);
// Convert seconds to milliseconds implicitly.
time_point<steady_clock, milliseconds> tpMilliseconds(tpSeconds);
cout << tpMilliseconds.time_since_epoch().count() << " ms" << endl;

If the implicit conversion can result in a loss of data, then you need an explicit conversion using time_point_cast(), just as duration_cast() is needed for explicit duration casts. The following example outputs 42000 ms, even though you start from 42,424ms.

time_point<steady_clock, milliseconds> tpMilliseconds(42'424ms);
// Convert milliseconds to seconds explicitly.
time_point<steady_clock, seconds> tpSeconds(
                    time_point_cast<seconds>(tpMilliseconds));

// Convert seconds back to milliseconds and output the result.
milliseconds ms(tpSeconds.time_since_epoch());
cout << ms.count() << " ms" << endl;

C++17 adds floor(), ceil(), and round() operations for time_points that behave just as they behave with numerical data.

Random Number Engines

The following random number engines are available:

• random_device
• linear_congruential_engine
• mersenne_twister_engine
• subtract_with_carry_engine

The random_device engine is not a software-based generator; it is a special engine that requires a piece of hardware attached to your computer that generates truly non-deterministic random numbers, for example, by using the laws of physics. A classic mechanism measures the decay of a radioactive isotope by counting alpha-particles-per-time-interval, but there are many other kinds of physics-based random-number generators, including measuring the “noise” of reverse-biased diodes (thus eliminating the concerns about radioactive sources in your computer). The details of these mechanisms fall outside the scope of this book.

According to the specification for random_device, if no such device is attached to the computer, the library is free to use one of the software algorithms. The choice of algorithm is up to the library designer.

The quality of a random number generator is referred to as its entropy measure. The entropy() method of the random_device class returns 0.0 if it is using a software-based pseudo-random number generator, and returns a nonzero value if there is a hardware device attached. The nonzero value is an estimate of the entropy of the attached device.

Using a random_device engine is rather straightforward:

random_device rnd;
cout << "Entropy: " << rnd.entropy() << endl;
cout << "Min value: " << rnd.min()
     << ", Max value: " << rnd.max() << endl;
cout << "Random number: " << rnd() << endl;

A possible output of this program could be as follows:

Entropy: 32
Min value: 0, Max value: 4294967295
Random number: 3590924439

A random_device is usually slower than a pseudo-random number engine. Therefore, if you need to generate a lot of random numbers, I recommend to use a pseudo-random number engine, and to use a random_device to generate a seed for the pseudo-random number engine. This is demonstrated in the section “Generating Random Numbers.”

Next to the random_device engine, there are three pseudo-random number engines:

• The linear congruential engine requires a minimal amount of memory to store its state. The state is a single integer containing the last generated random number or the initial seed if no random number has been generated yet. The period of this engine depends on an algorithmic parameter and can be up to 2⁶⁴ but is usually less. For this reason, the linear congruential engine should not be used when you need a high-quality random number sequence.
• Of the three pseudo-random number engines, the Mersenne twister generates the highest quality of random numbers. The period of a Mersenne twister depends on an algorithmic parameter but is much bigger than the period of a linear congruential engine. The memory required to store the state of a Mersenne twister also depends on its parameters but is much larger than the single integer state of the linear congruential engine. For example, the predefined Mersenne twister mt19937 has a period of 2¹⁹⁹³⁷−1, while the state contains 625 integers or 2.5 kilobytes. It is also one of the fastest engines.
• The subtract with carry engine requires a state of around 100 bytes; however, the quality of the generated random numbers is less than that of the numbers generated by the Mersenne twister, and it is also slower than the Mersenne twister.

The mathematical details of the engines and of the quality of random numbers fall outside the scope of this book. If you want to know more about these topics, you can consult a reference from the “Random Numbers” section in Appendix B.

The random_device engine is easy to use and doesn’t require any parameters. However, creating an instance of one of the three pseudo-random number generators requires you to specify a number of mathematical parameters, which can be complicated. The selection of parameters greatly influences the quality of the generated random numbers. For example, the definition of the mersenne_twister_engine class looks like this:

template<class UIntType, size_t w, size_t n, size_t m, size_t r,
         UIntType a, size_t u, UIntType d, size_t s,
         UIntType b, size_t t, UIntType c, size_t l, UIntType f>
    class mersenne_twister_engine {...}

It requires 14 parameters. The linear_congruential_engine and the subtract_with_carry_engine classes also require a number of such mathematical parameters. For this reason, the standard defines a couple of predefined engines. One example is the mt19937 Mersenne twister, which is defined as follows:

using mt19937 = mersenne_twister_engine<uint_fast32_t, 32, 624, 397, 31,
    0x9908b0df, 11, 0xffffffff, 7, 0x9d2c5680, 15, 0xefc60000, 18,
    1812433253>;

These parameters are all magic, unless you understand the details of the Mersenne twister algorithm. In general, you do not want to modify any of these parameters unless you are a specialist in the mathematics of pseudo-random number generators. Instead, it is highly recommended to use one of the predefined type aliases such as mt19937. A complete list of predefined engines is given in a later section.

Random Number Engine Adaptors

A random number engine adaptor modifies the result of a random number engine you associate it with, which is called the base engine. This is an example of the adaptor pattern (see Chapter 29). The following three adaptor templates are defined:

template<class Engine, size_t p, size_t r> class
    discard_block_engine {...}
template<class Engine, size_t w, class UIntType> class
    independent_bits_engine {...}
template<class Engine, size_t k> class
    shuffle_order_engine {...}

The discard_block_engine adaptor generates random numbers by discarding some of the values generated by its base engine. It requires three parameters: the engine to adapt, the block size p, and the used block size r. The base engine is used to generate p random numbers. The adaptor then discards p-r of those numbers and returns the remaining r numbers.

The independent_bits_engine adaptor generates random numbers with a given number of bits w by combining several random numbers generated by the base engine.

The shuffle_order_engine adaptor generates the same random numbers that are generated by the base engine, but delivers them in a different order.

How these adaptors internally work depends on mathematics and falls outside the scope of this book.

A number of predefined engine adaptors are available. The next section gives an overview of the predefined engines and engine adaptors.

Predefined Engines and Engine Adaptors

As mentioned earlier, it is not recommended to specify your own parameters for pseudo-random number engines and engine adaptors, but instead to use one of the standard ones. C++ defines the following predefined engines and engine adaptors, all in the <random> header file. They all have complicated template arguments, but it is not necessary to understand those arguments to be able to use them.

The default_random_engine is compiler dependent.

The following section gives an example of how to use these predefined engines.

Generating Random Numbers

Before you can generate any random number, you first need to create an instance of an engine. If you use a software-based engine, you also need to define a distribution. A distribution is a mathematical formula describing how numbers are distributed within a certain range. The recommended way to create an engine is to use one of the predefined engines discussed in the previous section.

The following example uses the predefined engine called mt19937, using a Mersenne twister engine. This is a software-based generator. Just as with the old rand() generator, a software-based engine should be initialized with a seed. The seed used with srand() was often the current time. In modern C++, it’s recommended to use a random_device to generate a seed, and to use a time-based seed as a fallback in case the random_device does not have any entropy.

random_device seeder;
const auto seed = seeder.entropy() ? seeder() : time(nullptr);
mt19937 eng(static_cast<mt19937::result_type>(seed));

Next, a distribution is defined. This example uses a uniform integer distribution, for the range 1 to 99. Distributions are explained in detail in the next section, but the uniform distribution is easy enough to use for this example:

uniform_int_distribution<int> dist(1, 99);

Once the engine and distribution are defined, random numbers can be generated by calling the function call operator of the distribution, and passing the engine as argument. For this example, this is written as dist(eng):

cout << dist(eng) << endl;

As you can see, to generate a random number using a software-based engine, you always need to specify the engine and distribution. The std::bind() utility, introduced in Chapter 18 and defined in the <functional> header file, can be used to remove the need to specify both the distribution and the engine when generating a random number. The following example uses the same mt19937 engine and uniform distribution as the previous example. It then defines gen() by using std::bind() to bind eng to the first parameter for dist(). This way, you can call gen() without any argument to generate a new random number. The example then demonstrates the use of gen() in combination with the generate() algorithm to fill a vector of ten elements with random numbers. The generate() algorithm is discussed in Chapter 18 and is defined in <algorithm>.

random_device seeder;
const auto seed = seeder.entropy() ? seeder() : time(nullptr);
mt19937 eng(static_cast<mt19937::result_type>(seed));
uniform_int_distribution<int> dist(1, 99);

auto gen = std::bind(dist, eng);

vector<int> vec(10);
generate(begin(vec), end(vec), gen);

for (auto i : vec) { cout << i << "  "; }

Even though you don’t know the exact type of gen(), it’s still possible to pass gen() to another function that wants to use that generator. You have two options: use a parameter of type std::function<int()>, or use a function template. The previous example can be adapted to generate random numbers in a function called fillVector(). Here is an implementation using std::function:

void fillVector(vector<int>& vec, const std::function<int()>& generator)
{
    generate(begin(vec), end(vec), generator);
}

and here is a function template version:

template<typename T>
void fillVector(vector<int>& vec, const T& generator)
{
    generate(begin(vec), end(vec), generator);
}

This function is used as follows:

random_device seeder;
const auto seed = seeder.entropy() ? seeder() : time(nullptr);
mt19937 eng(static_cast<mt19937::result_type>(seed));
uniform_int_distribution<int> dist(1, 99);

auto gen = std::bind(dist, eng);

vector<int> vec(10);
fillVector(vec, gen);

for (auto i : vec) { cout << i << "  "; }

Random Number Distributions

A distribution is a mathematical formula describing how numbers are distributed within a certain range. The random number generator library comes with the following distributions that can be used with pseudo-random number engines to define the distribution of the generated random numbers. It’s a compacted representation. The first line of each distribution is the class name and class template parameters, if any. The next lines are a constructor for the distribution. Only one constructor for each distribution is shown to give you an idea of the class. Consult a Standard Library Reference, see Appendix B, for a detailed list of all constructors and methods of each distribution.

Available uniform distributions:

template<class IntType = int> class uniform_int_distribution
    uniform_int_distribution(IntType a = 0,
                             IntType b = numeric_limits<IntType>::max());
template<class RealType = double> class uniform_real_distribution
    uniform_real_distribution(RealType a = 0.0, RealType b = 1.0);

Available Bernoulli distributions:

class bernoulli_distribution
    bernoulli_distribution(double p = 0.5);
template<class IntType = int> class binomial_distribution
    binomial_distribution(IntType t = 1, double p = 0.5);
template<class IntType = int> class geometric_distribution
    geometric_distribution(double p = 0.5);
template<class IntType = int> class negative_binomial_distribution
    negative_binomial_distribution(IntType k = 1, double p = 0.5);

Available Poisson distributions:

template<class IntType = int> class poisson_distribution
    poisson_distribution(double mean = 1.0);
template<class RealType = double> class exponential_distribution
    exponential_distribution(RealType lambda = 1.0);
template<class RealType = double> class gamma_distribution
    gamma_distribution(RealType alpha = 1.0, RealType beta = 1.0);
template<class RealType = double> class weibull_distribution
    weibull_distribution(RealType a = 1.0, RealType b = 1.0);
template<class RealType = double> class extreme_value_distribution
    extreme_value_distribution(RealType a = 0.0, RealType b = 1.0);

Available normal distributions:

template<class RealType = double> class normal_distribution
    normal_distribution(RealType mean = 0.0, RealType stddev = 1.0);
template<class RealType = double> class lognormal_distribution
    lognormal_distribution(RealType m = 0.0, RealType s = 1.0);
template<class RealType = double> class chi_squared_distribution
    chi_squared_distribution(RealType n = 1);
template<class RealType = double> class cauchy_distribution
    cauchy_distribution(RealType a = 0.0, RealType b = 1.0);
template<class RealType = double> class fisher_f_distribution
    fisher_f_distribution(RealType m = 1, RealType n = 1);
template<class RealType = double> class student_t_distribution
    student_t_distribution(RealType n = 1);

Available sampling distributions:

template<class IntType = int> class discrete_distribution
    discrete_distribution(initializer_list<double> wl);
template<class RealType = double> class piecewise_constant_distribution
    template<class UnaryOperation>
        piecewise_constant_distribution(initializer_list<RealType> bl,
            UnaryOperation fw);
template<class RealType = double> class piecewise_linear_distribution
    template<class UnaryOperation>
        piecewise_linear_distribution(initializer_list<RealType> bl,
            UnaryOperation fw);

Each distribution requires a set of parameters. Explaining all these mathematical parameters is outside the scope of this book, but the rest of this section includes a couple of examples to explain the impact of a distribution on the generated random numbers.

Distributions are easiest to understand when you look at a graphical representation of them. For example, the following code generates one million random numbers between 1 and 99, and counts how many times a certain number is randomly chosen. The counters are stored in a map where the key is a number between 1 and 99, and the value associated with a key is the number of times that that key has been selected randomly. After the loop, the results are written to a CSV (comma-separated values) file, which can be opened in a spreadsheet application.

const unsigned int kStart = 1;
const unsigned int kEnd = 99;
const unsigned int kIterations = 1'000'000;

// Uniform Mersenne Twister
random_device seeder;
const auto seed = seeder.entropy() ? seeder() : time(nullptr);
mt19937 eng(static_cast<mt19937::result_type>(seed));
uniform_int_distribution<int> dist(kStart, kEnd);
auto gen = bind(dist, eng);
map<int, int> m;
for (unsigned int i = 0; i < kIterations; ++i) {
    int rnd = gen();
    // Search map for a key = rnd. If found, add 1 to the value associated
    // with that key. If not found, add the key to the map with value 1.
    ++(m[rnd]);
}

// Write to a CSV file
ofstream of("res.csv");
for (unsigned int i = kStart; i <= kEnd; ++i) {
    of << i << "," << m[i] << endl;
}

The resulting data can then be used to generate a graphical representation. The graph of the preceding uniform Mersenne twister is shown in Figure 20-1.

The horizontal axis represents the range in which random numbers are generated. The graph clearly shows that all numbers in the range 1 to 99 are randomly chosen around 10,000 times, and that the distribution of the generated random numbers is uniform across the entire range.

The example can be modified to generate random numbers according to a normal distribution instead of a uniform distribution. Only two small changes are required. First, you need to modify the creation of the distribution as follows:

normal_distribution<double> dist(50, 10);

Because normal distributions use doubles instead of integers, you also need to modify the call to gen():

int rnd = static_cast<int>(gen());

Figure 20-2 shows a graphical representation of the random numbers generated according to this normal distribution.

The graph clearly shows that most of the generated random numbers are around the center of the range. In this example, the value 50 is randomly chosen around 40,000 times, while values like 20 and 80 are chosen only around 500 times.

Decompose Tuples

There are two ways in which you can decompose a tuple into its individual elements: structured bindings (C++17) and std::tie().

tuple t1(16, "Test"s, true);
auto[i, str, b] = t1;
cout << "Decomposed: i = "
     << i << ", str = \"" << str << "\", b = " << b << endl;

tuple<int, string, bool> t1(16, "Test", true);
int i = 0;
string str;
bool b = false;
cout << "Before: i = " << i << ", str = \"" << str << "\", b = " << b << endl;
tie(i, str, b) = t1;
cout << "After:  i = " << i << ", str = \"" << str << "\", b = " << b << endl;

Before: i = 0, str = "", b = 0
After:  i = 16, str = "Test", b = 1

tuple<int, string, bool> t1(16, "Test", true);
int i = 0;
bool b = false;
cout << "Before: i = " << i << ", b = " << b << endl;
tie(i, std::ignore, b) = t1;
cout << "After:  i = " << i << ", b = " << b << endl;

Before: i = 0, b = 0
After:  i = 16, b = 1

Concatenation

You can use std::tuple_cat() to concatenate two tuples into one tuple. In the following example, the type of t3 is tuple<int, string, bool, double, string>:

tuple<int, string, bool> t1(16, "Test", true);
tuple<double, string> t2(3.14, "string 2");
auto t3 = tuple_cat(t1, t2);

Comparisons

Tuples also support the following comparison operators: ==, !=, <, >, <=, and >=. For the comparison operators to work, the element types stored in the tuple should support them as well. Here is an example:

tuple<int, string> t1(123, "def");
tuple<int, string> t2(123, "abc");
if (t1 < t2) {
    cout << "t1 < t2" << endl;
} else {
    cout << "t1 >= t2" << endl;
}

The output is as follows:

t1 >= t2

Tuple comparisons can be used to easily implement lexicographical comparison operators for custom types that have several data members. For example, suppose you have a simple structure with three data members:¹

struct Foo
{
    int mInt;
    string mStr;
    bool mBool;
};

Implementing a correct operator< for Foo is not trivial! However, using std::tie() and tuple comparisons, this becomes a simple one-liner:

bool operator<(const Foo& f1, const Foo& f2)
{
    return tie(f1.mInt, f1.mStr, f1.mBool) <
           tie(f2.mInt, f2.mStr, f2.mBool);
}

Here is an example of its use:

Foo f1{ 42, "Hello", 0 };
Foo f2{ 32, "World", 0 };
cout << (f1 < f2) << endl;
cout << (f2 < f1) << endl;

make_from_tuple

std::make_from_tuple() constructs an object of a given type T, passing the elements of a given tuple as arguments to the constructor of T. For example, suppose you have the following class:

class Foo
{
    public:
        Foo(string str, int i) : mStr(str), mInt(i) {}
    private:
        string mStr;
        int mInt;
};

You can use make_from_tuple() as follows:

auto myTuple = make_tuple("Hello world.", 42);
auto foo = make_from_tuple<Foo>(myTuple);

The argument given to make_from_tuple() does not have to be a tuple, but it has to be something that supports std::get<>() and std::tuple_size. Both std::array and std::pair satisfy these requirements as well.

This function is not that practical for everyday use, but it comes in handy when writing very generic code using templates and template metaprogramming.

apply

std::apply() calls a given callable (function, lambda expression, function object, and so on), passing the elements of a given tuple as arguments. Here is an example:

int add(int a, int b) { return a + b; }
...
cout << apply(add, std::make_tuple(39, 3)) << endl;

As with make_from_tuple(), this function is also meant more for use with generic code using templates and template metaprogramming, than for everyday use.

Path

The basic component of the library is a path. A path can be an absolute or a relative path, and can include a filename or not. For example, the following code defines a couple of paths. Note the use of a raw string literal to avoid having to escape the backslashes.

path p1(LR"(D:\Foo\Bar)");
path p2(L"D:/Foo/Bar");
path p3(L"D:/Foo/Bar/MyFile.txt");
path p4(LR"(..\SomeFolder)");
path p5(L"/usr/lib/X11"); 

When a path is converted to a string (for example by using the c_str() method), or inserted into a stream, it is converted to the native format of the system on which the code is running. For example:

path p1(LR"(D:\Foo\Bar)");
path p2(L"D:/Foo/Bar"); 
cout << p1 << endl;
cout << p2 << endl; 

The output is as follows:

D:\Foo\Bar
D:\Foo\Bar

You can append a component to a path with the append() method, or with operator/=. A path separator is automatically included. For example:

path p(L"D:\\Foo");
p.append("Bar");
p /= "Bar";
cout << p << endl;

The output is D:\Foo\Bar\Bar.

You can use concat(), or operator+=, to concatenate a string to an existing path. This does not add any path separator! For example:

path p(L"D:\\Foo");
p.concat("Bar");
p += "Bar";
cout << p << endl;

The output now is D:\FooBarBar.

A path supports iterators to iterate over its different components. Here is an example:

path p(LR"(C:\Foo\Bar)");
for (const auto& component : p) {
    cout << component << endl;
}

The output is as follows:

C:
\
Foo
Bar

The path interface supports operations such as remove_filename(), replace_filename(), replace_extension(), root_name(), parent_path(), extension(), has_extension(), is_absolute(), is_relative(), and more. Consult a Standard Library reference, see Appendix B, for a full list of all available functionality.

Directory Entry

A path just represents a directory or a file on a filesystem. A path may refer to a non-existing directory or file. If you want to query an actual directory or file on the filesystem, you need to construct a directory_entry from a path. This construction can fail if the given directory or file does not exist. The directory_entry interface supports operations like is_directory(), is_regular_file(), is_socket(), is_symlink(), file_size(), last_write_time(), and others.

The following example constructs a directory_entry from a path to query the size of a file:

path myPath(L"c:/windows/win.ini");
directory_entry dirEntry(myPath);
if (dirEntry.exists() && dirEntry.is_regular_file()) {
    cout << "File size: " << dirEntry.file_size() << endl;
}

Helper Functions

An entire collection of helper functions is available. For example, you can use copy() to copy files or directories, create_directory() to create a new directory on the filesystem, exists() to query whether or not a given directory or file exists, file_size() to get the size of a file, last_write_time() to get the time the file was last modified, remove() to delete a file, temp_directory_path() to get a directory suitable for storing temporary files, space() to query the available space on a filesystem, and more. Consult a Standard Library reference, see Appendix B, for a full list.

The following example prints out the capacity of a filesystem and how much space is still free:

space_info s = space("c:\\");
cout << "Capacity: " << s.capacity << endl;
cout << "Free: " << s.free << endl;

You can find more examples of these helper functions in the following section on directory iteration.

Directory Iteration

If you want to recursively iterate over all files and subdirectories in a given directory, you can use the recursive_directory_iterator as follows:

void processPath(const path& p)
{
    if (!exists(p)) {
        return;
    }

    auto begin = recursive_directory_iterator(p);
    auto end = recursive_directory_iterator();
    for (auto iter = begin; iter != end; ++iter) {
        const string spacer(iter.depth() * 2, ' ');

        auto& entry = *iter;

        if (is_regular_file(entry)) {
            cout << spacer << "File: " << entry;
            cout << " (" << file_size(entry) << " bytes)" << endl;
        } else if (is_directory(entry)) {
            std::cout << spacer << "Dir: " << entry << endl;
        }
    }
}

This function can be called as follows:

path p(LR"(D:\Foo\Bar)");
processPath(p);

You can also use a directory_iterator to iterate over the contents of a directory and implement the recursion yourself. Here is an example that does the same thing as the previous example but using a directory_iterator instead of a recursive_directory_iterator:

void processPath(const path& p, size_t level = 0)
{
    if (!exists(p)) {
        return;
    }

    const string spacer(level * 2, ' ');

    if (is_regular_file(p)) {
        cout << spacer << "File: " << p;
        cout << " (" << file_size(p) << " bytes)" << endl;
    } else if (is_directory(p)) {
        std::cout << spacer << "Dir: " << p << endl;
        for (auto& entry : directory_iterator(p)) {
            processPath(entry, level + 1);
        }
    }
}