C++ Basics

This chapter is from the book

Discovering Modern C++, 2nd Edition

Learn More Buy

This chapter is from the book

This chapter is from the book 

Discovering Modern C++, 2nd Edition

Learn More Buy

1.7 I/O

C++ uses a convenient abstraction called streams to perform I/O operations in sequential media such as screens or keyboards. A stream is an object where a program can either insert characters or extract them. The standard C++ library contains the header <iostream> where the standard input and output stream objects are declared.

1.7.1 Standard Output

By default, the standard output of a program is written to the screen, and we can access it with the C++ stream named cout. It is used with the insertion operator, which is denoted by ≪ (like left shift). We have already seen that it may be used more than once within a single statement. This is especially useful when we want to print a combination of text, variables, and constants, e.g.:

cout ≪ "The square root of " ≪ x ≪ " is " ≪ sqrt(x) ≪ endl;

with an output like

The square root of 5 is 2.23607

endl produces a newline character. An alternative representation of endl is the character \n. For the sake of efficiency, the output may be buffered. In this regard, endl and \n differ: the former flushes the buffer while the latter does not. Flushing can help us when we are debugging (without a debugger) to find out between which outputs the program crashes. In contrast, when a large amount of text is written to files, flushing after every line slows down I/O considerably.

Fortunately, the insertion operator has a relatively low priority so that arithmetic operations can be written directly:

std::cout ≪ "11 * 19 = " ≪ 11 * 19 ≪ std::endl;

All comparisons and logical and bitwise operations must be grouped by surrounding parentheses. Likewise the conditional operator:

std::cout ≪ (age > 65 ? "I'm a wise guy\n" : "I am still half-baked.\n");

When we forget the parentheses, the compiler will remind us (offering us an enigmatic message to decipher).

1.7.2 Standard Input

Handling the standard input in C++ is done by applying the overloaded operator of extraction ≫. The standard input device is usually the keyboard as stream name cin:

int age;
std::cin ≫ age;

This command reads characters from the input device and interprets them as a value of the variable type (here int) it is stored to (here age). The input from the keyboard is processed once the RETURN key has been pressed. We can also use cin to request more than one data input from the user:

std::cin ≫ width ≫ length;

which is equivalent to

std::cin ≫ width;
std::cin ≫ length;

In both cases the user must provide two values: one for width and another for length. They can be separated by any valid blank separator: a space, a tab character, or a newline.

1.7.3 Input/Output with Files

C++ provides the following classes to perform input and output of characters from/to files:

We can use file streams in the same fashion as cin and cout, with the only difference that we have to associate these streams with physical files. Here is an example:

#include <fstream>
int main ()
{
    std::ofstream square_file;
    square_file.open("squares.txt");
    for (int i= 0; i < 10; ++i)
        square_file ≪ i ≪ "^2 = " ≪ i*i ≪ '\n';
    square_file.close();
}

This code creates a file named squares.txt (or overwrites it if it already exists) and writes some lines to it—like we write to cout. C++ establishes a general stream concept that is satisfied by an output file and by std::cout. This means we can write everything to a file that we can write to std::cout and vice versa. When we define operator≪ for a new type, we do this once for ostream (Section 2.7.3) and it will work with the console, with files, and with any other output stream.

Alternatively, we can pass the filename as an argument to the constructor of the stream to open the file implicitly. The file is also implicitly closed when square_file goes out of scope,¹² in this case at the end of the main function. The short version of the preceding program is:

#include <fstream >
int main ()
{
    std::ofstream square_file{"squares.txt"};
    for (int i= 0; i < 10; ++i)
        square_file ≪ i ≪ "^2 = " ≪ i*i ≪ '\n';
}

We prefer the short form (as usual). The explicit form is only necessary when the file is first declared and opened later for some reason. Likewise, the explicit close is only needed when the file should be closed before it goes out of scope.

1.7.4 Generic Stream Concept

Streams are not limited to screens, keyboards, and files; every class can be used as a stream when it is derived¹³ from istream, ostream, or iostream and provides implementations for the functions of those classes. For instance, Boost.Asio offers streams for TCP/IP and Boost. IOStream provides alternatives to the I/O above. The standard library contains a stringstream that can be used to create a string from any kind of printable type. stringstream’s method str() returns the stream’s internal string.

We can write output functions that accept every kind of output stream by using a mutable reference to ostream as an argument:

#include <iostream>
#include <fstream>
#include <sstream> 
void write_something(std::ostream& os)
{
    os ≪ "Hi stream, did you know that 3 * 3 = " ≪ 3 * 3 ≪ '\n';
}
int main (int argc, char* argv[])
{
    std::ofstream myfile{"example.txt"};
    std::stringstream mysstream; 
    write_something(std::cout);
    write_something(myfile);
    write_something(mysstream); 
    std::cout ≪ "mysstream is: " ≪ mysstream.str(); // newline contained
}

Likewise, generic input can be implemented with istream and read/write I/O with iostream.

1.7.5 Formatting

⇒ c++03/formatting.cpp

I/O streams are formatted by so-called I/O manipulators which are found in the header file <iomanip>. By default, C++ only prints a few digits of floating-point numbers. Thus, we increase the precision:

double pi= M_PI;
cout ≪ "pi is " ≪ pi ≪ '\n';
cout ≪ "pi is " ≪ setprecision(16) ≪ pi ≪ '\n';

and yield a more accurate number:

pi is 3.14159
pi is 3.141592653589793

C++20 In Section 4.3.1, we will show how the precision can be adjusted to the type’s representable number of digits. Instead of the macro M_PI or a literal value, in C++20 we can use the double constant std::number::pi from <numbers>.

When we write a table, vector, or matrix, we need to align values for readability. Therefore, we next set the width of the output:

cout ≪ "pi is " ≪ setw(30) ≪ pi ≪ '\n';

This results in

pi is                3.141592653589793

setw changes only the next output while setprecision affects all following (numerical) outputs, like the other manipulators. The provided width is understood as a minimum, and if the printed value needs more space, our tables will get ugly.

We can further request that the values be left aligned, and the empty space be filled with a character of our choice, say, -:

cout ≪ "pi is " ≪ setfill('-') ≪ left
     ≪ setw(30) ≪ pi ≪ '\n';

yielding

pi is 3.141592653589793-------------

Another way of formatting is setting the flags directly. Furthermore, we force the “scientific” notation in the normalized exponential representation:

cout.setf(ios_base::showpos);
cout ≪ "pi is " ≪ scientific ≪ pi ≪ '\n';

resulting in:

pi is +3.1415926535897931e+00

Integer numbers can be represented in octal and hexadecimal base by:

cout ≪ "63 octal is " ≪ oct ≪ 63 ≪ ".\n";
cout ≪ "63 hexadecimal is " ≪ hex ≪ 63 ≪ ".\n";
cout ≪ "63 decimal is " ≪ dec ≪ 63 ≪ ".\n";

with the expected output:

63 octal is 77.
63 hexadecimal is 3f.
63 decimal is 63.

Boolean values are by default printed as integers 0 and 1. On demand, we can present them as true and false:

cout ≪ "pi < 3 is " ≪ (pi < 3) ≪ '\n';
cout ≪ "pi < 3 is " ≪ boolalpha ≪ (pi < 3) ≪ '\n';

Finally, we can reset all the format options that we changed:

int old_precision= cout.precision();
cout ≪ setprecision (16)
...
cout.unsetf(ios_base::adjustfield | ios_base::basefield
        | ios_base::floatfield | ios_base::showpos | ios_base::boolalpha);
cout.precision(old_precision);

Each option is represented by a bit in a status variable. To enable multiple options, we can combine their bit patterns with a binary OR.

C++20 1.7.6 New Formatting

⇒ c++20/fmt_example.cpp

As we have seen in the preceding section, traditional stream formatting requires a fair amount of typing. Alternatively, we can use the output from C with the printf function and format strings. This allows us to declare with few symbols what we’ve written with multiple I/O manipulators before.

Nonetheless, we advise against using printf, for two reasons: it can’t be used with user types and it is not type safe. The format string is parsed at run time and the following arguments are treated with an obscure macro mechanism. If the arguments don’t match the format string, the behavior is undefined and can cause program crashes. For instance, a string is passed as a pointer, and from the pointed address on, the bytes are read and printed as char until a binary 0 is found in memory. If we accidentally try printing an int as a string, the int value is misinterpreted as an address from which a sequence of char shall be printed. This will result in either absolute nonsensical output or (more likely) in a memory error if the address is inaccessible. We have to admit that recent compilers parse format strings (when known at compile time) and warn about argument mismatches.

The new <format> library in C++20 combines the expressibility of the format string with the type safety and the user extensibility of stream I/O and adds the opportunity to reorder the arguments in the output. Unfortunately, not even the latest compilers by the time of writing (GCC 12.0, Clang 13, and Visual Studio 16.9.6¹⁴) support the <format> library. Therefore, we used the prototype library <fmt> and refrained from wild-guessing how this would translate to the final standard interface. We strongly encourage you to migrate these examples yourself to <format> as soon as it’s available to you. The syntax is different but the principles are the same.

Instead of a formal specification, we port some printf examples from cppreference.com to the new format:

print("Decimal:\t{} {} {:06} {} {:0} {:+} {:d}\n",
      1, 2, 3, 0, 0, 4, -1);
print("Hexadecimal:\t{:x} {:x} {:X} {:#x}\n", 5, 10, 10, 6);
print("Octal:\t\t{:o} {:#o} {:#o}\n", 10, 10, 4);
print("Binary:\t\t{:b} {:#b} {:#b}\n", 10, 10, 4);

This snippet prints:

Decimal:         1 2 000003 0 0 +4 -1
Hexadecimal:     5 a A 0x6
Octal:           12 012 04
Binary:          1010 0 b1010 0 b100

The first two numbers were just printed without giving any format information. The same output is generated when we ask for a decimal number with the format specifier "{:d}". The third number will be printed (minimally) 6 characters wide and filled with leading 0s. The specifier + allows us to force printing the sign for all numbers. printf allows for specifying unsigned output of numbers. That leads to incorrect large numbers when the value to print is negative. The <format> library refrains from user declarations of unsigned output since this information is already contained in the type of the according argument. If somebody feels the urge to print a negative value as a large positive one, they must convert it explicitly.

The second line demonstrates that we can print values hexadecimally—both with lower-and uppercase for the digits larger than 9. The specifier "#" generates the prefix "0x" used in hexadecimal literals. Likewise, we can print the values as octals and binaries, optionally with the according literal prefix.

With floating-point numbers we have more formatting options:

print("Default:\t{} {:g} {:g}\n", 1.5, 1.5, 1e20);
print("Rounding:\t{:f} {:.0f} {:.22f}\n", 1.5, 1.5, 1.3);
print("Padding:\t{:05.2f} {:.2f} {:5.2 f}\n", 1.5, 1.5, 1.5);
print("Scientific:\t{:E} {:e}\n", 1.5, 1.5);
print("Hexadecimal:\t{:a} {:A}\n\n", 1.5, 1.3);

Then we get:

Default:        1.5 1.5 1e+20
Rounding:       1.500000 2 1.3000000000000000444089
Padding:        01.50 1.50  1.50
Scientific:     1.500000E+00 1.500000e+00
Hexadecimal:    0x1.8p+0 0X1.4 CCCCCCCCCCCDP+0

With empty braces or only containing a colon, we get the default output. This corresponds to the format specifier "{:g}" and yields the same output as streams without the manipulators. The number of fractional digits can be given between a dot and the format specifier "f". Then the value is rounded to that precision. If the requested number is larger than what is representable by the value’s type, the last digits aren’t very meaningful. A digit in front of the dot specifies the (minimal) width of the output. As with integers, we can request leading 0s. Floating-point numbers can be printed in the scientific notation with either an upper- or lowercase "e" to start the exponential part. The hexadecimal output can be used to initialize a variable in another program with precisely the same bits.

The output can be redirected to any other std::ostream:¹⁵

print(std::cerr, "System error code = {}\n", 7);
ofstream error_file("error_file.txt");
print(error_file, "System error code = {}\ n", 7);

In contrast to printf, arguments can now be reordered:

print("I'd rather be {1} than {0}.\ n", "right", "happy");

In addition to referring the arguments by their positions, we can give them names:

print("Hello, {name}! The answer is {number}. Goodbye, {name}.\n",
      arg("name", name), arg("number", number));

Or more concisely:

print("Hello, {name}! The answer is {number}. Goodbye, {name}.\n",
      "name"_a=name, "number"_a=number);

The example also demonstrates that we can print an argument multiple times.

Reordering arguments is very important in multilingual software to provide a natural phrasing. In Section 1.3.1 we printed the average of two values, and now we want to extend this example to five languages:

void print_average(float v1, float v2, int language)
{
    using namespace fmt;
    string formats[]= {
        "The average of {v1} and {v2} is {result}.\n",
        "{result:.6f} ist der Durchschnitt von {v1} und {v2}.\n",
        "La moyenne de {v1} et {v2} est {result}.\n",
        "El promedio de {v1} y {v2} es {result}.\n",
        "{result} corrisponde alla media di {v1} e {v2}.\n"};
    print (formats[language], "v1"_a= v1, "v2"_a= v2,
           "result"_a= (v1+v2)/2.0 f);
}

Of course, the German version is the most pedantic one, requesting six decimal digits no matter what:

The average of 3.5 and 7.3 is 5.4.
5.400000 ist der Durchschnitt von 3.5 und 7.3.
La moyenne de 3.5 et 7.3 est 5.4.
El promedio de 3.5 y 7.3 es 5.4.
5.4 corrisponde alla media di 3.5 e 7.3.

Admittedly, this example would have worked without reordering the arguments but it nicely demonstrates the important possibility to separate the text and the formatting from the values. To store formatted text in a string we don’t need a stringstream any longer but can do it directly with the function format.

Altogether, the new formatting is:

• Compact, as demonstrated in the examples above

• Adaptable to various output orders

• Type-safe, as an exception is thrown when an argument doesn’t match

• Extensible, which we will see in Section 3.5.6

For those reasons, it is superior to the preceding techniques, and we therefore strongly advise using it as soon as sufficient compiler support is available.

1.7.7 Dealing with I/O Errors

To make one thing clear from the beginning: I/O in C++ is not fail-safe. Errors can be reported in different ways and our error handling must comply to them. Let us try the following example program:

int main ()
{
    std::ifstream infile("some_missing_file.xyz");
    int i;
    double d;
    infile ≫ i ≫ d;
    std::cout ≪ "i is " ≪ i ≪ ", d is " ≪ d ≪ '\n';
    infile.close();
}

Although the file does not exist, the opening operation does not fail. We can even read from the nonexisting file and the program goes on. It is needless to say that the values in i and d are nonsense:

i is 1, d is 2.3452e-310

By default, the streams do not throw exceptions. The reason is historical: they are older than the exceptions, and later the behavior was kept to not break software written in the meantime. Another argument is that failing I/O is nothing exceptional but quite common, and checking errors (after each operation) would be natural.

To be sure that everything went well, we have to check error flags, in principle, after each I/O operation. The following program asks the user for new filenames until a file can be opened. After reading its content, we check again for success:

int main ()
{
    std::ifstream infile;
    std::string filename{"some_missing_file.xyz"};
    bool opened= false;
    while (!opened) {
        infile.open(filename);
        if (infile.good()) {
            opened= true;
        } else {
            std::cout ≪ "The file '"≪ filename
                      ≪ "' doesn't exist (or can't be opened),"
                      ≪ "please give a new filename: ";
            std::cin ≫ filename;
        }
}
int i;
double d;
infile ≫ i ≫ d;
    if (infile.good())
        std::cout ≪ "i is " ≪ i ≪ ", d is " ≪ d ≪ '\n';
    else
        std::cout ≪ "Could not correctly read the content.\n";
    infile.close();
}

You can see from this simple example that writing robust applications with file I/O can create some work. If we want to use exceptions, we have to enable them during run time for each stream:

cin.exceptions(ios_base::badbit | ios_base::failbit);
cout.exceptions(ios_base::badbit | ios_base::failbit);
std::ifstream infile("f.txt");
infile.exceptions(ios_base::badbit | ios_base::failbit);

The streams throw an exception every time an operation fails or when they are in a “bad” state. Exceptions could be thrown at (unexpected) file end as well. However, the end of file is more conveniently handled by testing (e.g., while (!f.eof())).

In the preceding example, the exceptions for infile are only enabled after opening the file (or the attempt thereof). For checking the opening operation, we have to create the stream first, then turn on the exceptions, and finally open the file explicitly. Enabling the exceptions gives us at least the guarantee that all I/O operations went well when the program terminates properly. We can make our program more robust by catching possible exceptions.

The exceptions in file I/O only protect us partially from making errors. For instance, the following small program is obviously wrong (types don’t match and numbers aren’t separated):

void with_io_exceptions(ios& io)
{    io.exceptions(ios_base::badbit | ios_base::failbit); } 
int main ()
{
    std::ofstream outfile;
    with_io_exceptions(outfile);
    outfile.open("f.txt"); 
    double o1= 5.2, o2= 6.2;
    outfile ≪ o1 ≪ o2 ≪ std::endl;  // no separation
    outfile.close(); 
    std::ifstream infile;
    with_io_exceptions(infile);
    infile.open("f.txt"); 
    int  i1, i2;
    char c;
    infile ≫ i1 ≫ c ≫ i2;            // mismatching types
    std::cout ≪ "i1 = " ≪ i1 ≪ ", i2 = " ≪ i2 ≪ "\n";
}

Nonetheless, it does not throw exceptions and fabricates the following output:

i1 = 5, i2 = 26

As we all know, testing does not prove the correctness of a program. This is even more obvious when I/O is involved. Stream input reads the incoming characters and passes them as values of the corresponding variable type, e.g., int when setting i1. It stops at the first character that cannot be part of the value, first at the dot for the int value i1. If we read another int afterward, it would fail because an empty string cannot be interpreted as an int value. But we do not; instead we read a char next to which the dot is assigned. When parsing the input for i2 we find first the fractional part from o1 and then the integer part from o2 before we get a character that cannot belong to an int value.

Unfortunately, not every violation of the grammatical rules causes an exception in practice: .3 parsed as an int yields zero (while the next input probably fails); -5 parsed as an unsigned results in 4294967291 (when unsigned is 32 bits long). The narrowing principle apparently has not found its way into I/O streams yet (if it ever will for backward compatibility’s sake).

At any rate, the I/O part of an application needs close attention. Numbers must be separated properly (e.g., by spaces) and read with the same type as they were written. Floating-point values can also vary in their local representation and it is therefore recommended to store and read them without internationalization (i.e., with neutral C locale) when the program will run on different systems. Another challenge can be branches in the output so that the file format can vary. The input code is considerably more complicated and might even be ambiguous.

There are two other forms of I/O we want to mention: binary and C-style I/O. The interested reader will find them in Sections A.2.6 and A.2.7, respectively. You can also read this later when you need it.

C++17 1.7.8 Filesystem

⇒ c++17/filesystem_example.cpp

A library that was overdue in C++ is <filesystem>. Now we can list all files in a directory and ask for their type, for instance:¹⁶

namespace fs = std::filesystems;
for (auto & p : fs::directory_iterator("."))
    if (is_regular_file(p))
        cout ≪ p ≪ " is a regular file.\n"; // Error in Visual Studio
    else if(is_directory(p))
        cout ≪ p ≪ " is a directory .\n";
    else
        cout ≪ p ≪ " is neither regular file nor directory.\n";

printed out for a directory containing one executable and a subdirectory:

.\\cpp17_vector_any.exe is a regular file.
.\\sub is a directory.

The filesystem library also allows us to copy files, create symbolic and hard links, and rename files directly within a C++ program in a portable manner. Boost.Filesystem is a reasonable alternative if your compiler is not handling file operations properly or you are obliged to hold back to older standards.